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.
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 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).
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 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.
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.
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).
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 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!
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`: ```clojure (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 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.
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.
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close