fix #247

add examples showing how to get extra connection string params in a
connection pool

CHANGELOG.md

@@ -4,6 +4,7 @@ Only accretive/fixative changes will be made from now on.
 
 * 1.3.next in progress
   * Fix [#248](https://github.com/seancorfield/next-jdbc/issues/248) by allowing `:port` to be `:none`.
+  * Address [#247](https://github.com/seancorfield/next-jdbc/issues/247) by adding examples of using `next.jdbc.connection/jdbc-url` to build a connection string with additional parameters when creating connection pools.
 
 * 1.3.865 -- 2023-03-31
   * Fix [#246](https://github.com/seancorfield/next-jdbc/issues/246) by adopting the `strop` function from HoneySQL.

doc/getting-started.md

@@ -504,6 +504,19 @@ In addition, for HikariCP, you can specify properties to be applied to the under
 
 _(under the hood, `java.data` converts that hash map to a `java.util.Properties` object with `String` keys and `String` values)_
 
+If you need to pass in extra connection URL parameters, it can be easier to use
+`next.jdbc.connection/jdbc-url` to construct URL, e.g.,
+
+```clojure
+(connection/->pool com.zaxxer.hikari.HikariDataSource
+                   {:jdbcUrl
+                    (connection/jdbc-url {:dbtype "mysql" :dbname "thedb" :useSSL false})
+                    :username "dbuser" :password "secret"})
+```
+
+Here we pass `:useSSL false` to `jdbc-url` so that it ends up in the
+connection string, but pass `:username` and `:password` for the pool itself.
+
 > Note: both HikariCP and c3p0 defer validation of the settings until a connection is requested. If you want to ensure that your datasource is set up correctly, and the database is reachable, when you first create the connection pool, you will need to call `jdbc/get-connection` on it (and then close that connection and return it to the pool). This will also ensure that the pool is fully initialized. See the examples below.
 
 Some important notes regarding HikariCP:

src/next/jdbc/connection.clj

@@ -253,6 +253,16 @@
   `.setJdbcUrl`). `clojure.java.data/to-java` is used to construct the
   object and call the setters.
 
+  If you need to pass in connection URL parameters, it can be easier to use
+  `next.jdbc.connection/jdbc-url` to construct URL, e.g.,
+
+  (->pool HikariDataSource
+          {:jdbcUrl (jdbc-url {:dbtype .. :dbname .. :useSSL false})
+           :username .. :password ..})
+
+  Here we pass `:useSSL false` to `jdbc-url` so that it ends up in the
+  connection string, but pass `:username` and `:password` for the pool itself.
+
   Note that the result is not type-hinted (because there's no common base
   class or interface that can be assumed). In particular, connection pooled
   datasource objects may need to be closed but they don't necessarily implement
@@ -325,6 +335,12 @@
           '(com.zaxxer.hikari HikariDataSource))
   (isa? PooledDataSource java.io.Closeable) ;=> false
   (isa? HikariDataSource java.io.Closeable) ;=> true
+  ;; create a pool with a combination of JDBC URL and username/password:
+  (->pool HikariDataSource
+          {:jdbcUrl
+           (jdbc-url {:dbtype "mysql" :dbname "clojure_test"
+                      :useSSL false})
+           :username "root" :password (System/getenv "MYSQL_ROOT_PASSWORD")})
   ;; use c3p0 with default reflection-based closing function:
   (def dbc (component ComboPooledDataSource
                       {:dbtype "mysql" :dbname "clojure_test"
@@ -344,7 +360,8 @@
   ;; invoke datasource component to get the underlying javax.sql.DataSource:
   (next.jdbc.sql/get-by-id (ds) :fruit 1)
   ;; stop the component and close the pooled datasource:
-  (component/stop ds))
+  (component/stop ds)
+  )
 
 (defn- string->url+etc
   "Given a JDBC URL, return it with an empty set of options with no parsing."