next.jdbc.connection — com.github.seancorfield/next.jdbc 1.3.981

Standard implementations of get-datasource and get-connection.

Also provides dbtypes as a map of all known database types, and the ->pool and component functions for creating pooled datasource objects.

->pool clj

(->pool clazz db-spec)

Given a (connection pooled datasource) class and a database spec, return a connection pool object built from that class and the database spec.

Assumes the clazz has a .setJdbcUrl method (which HikariCP and c3p0 do).

If you already have a JDBC URL and want to use this method, pass :jdbcUrl in the database spec (instead of :dbtype, :dbname, etc).

Properties for the connection pool object can be passed as mixed case keywords that correspond to setter methods (just as :jdbcUrl maps to .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 java.io.Closeable (HikariCP does, c3p0 does not).

component clj

(component clazz db-spec)

(component clazz db-spec close-fn)

Takes the same arguments as ->pool but returns an entity compatible with Stuart Sierra's Component: when com.stuartsierra.component/start is called on it, it builds a connection pooled datasource, and returns an entity that can either be invoked as a function with no arguments to return that datasource, or can have com.stuartsierra.component/stop called on it to shutdown the datasource (and return a new startable entity).

If db-spec contains :init-fn, that is assumed to be a function that should be called on the newly-created datasource. This allows for modification of (mutable) connection pooled datasource and/or some sort of database initialization/setup to be called automatically.

By default, the datasource is shutdown by calling .close on it. If the datasource class implements java.io.Closeable then a direct, type-hinted call to .close will be used, with no reflection, otherwise Java reflection will be used to find the first .close method in the datasource class that takes no arguments and returns void.

If neither of those behaviors is appropriate, you may supply a third argument to this function -- close-fn -- which performs whatever action is appropriate to your chosen datasource class.

dbtypes clj

A map of all known database types (including aliases) to the class name(s) and port that next.jdbc supports out of the box. For databases that have non-standard prefixes for the :dbname and/or :host values in the JDBC string, this table includes :dbname-separator and/or :host-prefix. The default prefix for :dbname is either / or : and for :host it is //. For local databases, with no :host/:port segment in their JDBC URL, a value of :none is provided for :host in this table. In addition, :property-separator can specify how you build the JDBC URL.

For known database types, you can use :dbtype (and omit :classname).

If you want to use a database that is not in this list, you can specify a new :dbtype along with the class name of the JDBC driver in :classname. You will also need to specify :port. For example:

{:dbtype "acme" :classname "com.acme.JdbcDriver" ...}

The value of :dbtype should be the string that the driver is associated with in the JDBC URL, i.e., the value that comes between the jdbc: prefix and the ://<host>... part. In the above example, the JDBC URL that would be generated would be jdbc:acme://<host>:<port>/<dbname>.

If you want next.jdbc to omit the host/port part of the URL, specify :host :none, which would produce a URL like: jdbc:acme:<dbname>, which allows you to work with local databases (or drivers that do not need host/port information).

The default prefix for the host name (or IP address) is //. You can override this via the :host-prefix option.

The default separator between the host/port and the database name is /. The default separator between the subprotocol and the database name, for local databases with no host/port, is :. You can override this via the :dbname-separator option.

JDBC drivers are not provided by next.jdbc -- you need to specify the driver(s) you need as additional dependencies in your project. For example:

[com.acme/jdbc "1.2.3"] ; lein/boot

or:

com.acme/jdbc {:mvn/version "1.2.3"} ; CLI/deps.edn

Note: the :classname value can be a string or a vector of strings. If a vector of strings is provided, an attempt will be made to load each named class in order, until one succeeds. This allows for a given :dbtype to be used with different versions of a JDBC driver, if the class name has changed over time (such as with MySQL).

jdbc-url clj

(jdbc-url db-spec)

Given a database spec (as a hash map), return a JDBC URL with all the attributes added to the query string. The result is suitable for use in calls to ->pool and component as the :jdbcUrl key in the parameter map for the connection pooling library.

This allows you to build a connection-pooled datasource that needs additional settings that the pooling library does not support, such as :serverTimezone:

  (def db-spec {:dbtype .. :dbname .. :user .. :password ..
                :serverTimezone "UTC"})
  (def ds (next.jdbc.connection/->pool
           HikariCP {:jdbcUrl (next.jdbc.connection/jdbc-url db-spec)
                     :maximumPoolSize 15}))

This also clearly separates the attributes that should be part of the JDBC URL from the attributes that should be configured on the pool.

Since JDBC drivers can handle URL encoding differently, if you are trying to pass attributes that might need encoding, you should make sure they are properly URL-encoded as values in the database spec hash map. This function does not attempt to URL-encode values for you!

uri->db-spec clj

(uri->db-spec uri)

clojure.java.jdbc (and some users out there) considered the URI format to be an acceptable JDBC URL, i.e., with credentials embdedded in the string, rather than as query parameters.

This function accepts a URI string, optionally prefixed with jdbc: and returns a db-spec hash map.