Liking cljdoc? Tell your friends :D

next.jdbc.connection

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.
raw docstring

->poolclj

(->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).
sourceraw docstring

componentclj

(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.
sourceraw docstring

dbtypesclj

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).
sourceraw docstring

jdbc-urlclj

(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!
sourceraw docstring

uri->db-specclj

(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.
sourceraw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close