Liking cljdoc? Tell your friends :D

next.jdbc

The public API of the next generation java.jdbc library.

The basic building blocks are the java.sql/javax.sql classes:

  • DataSource -- something to get connections from,
  • Connection -- an active connection to the database,
  • PreparedStatement -- SQL and parameters combined, from a connection,

and the following functions and a macro:

  • get-datasource -- given a hash map describing a database or a JDBC connection string, construct a javax.sql.DataSource and return it,
  • get-connection -- given a connectable, obtain a new java.sql.Connection from it and return that,
  • plan -- given a connectable and SQL + parameters or a statement, return a reducible that, when reduced (with an initial value) will execute the SQL and consume the ResultSet produced,
  • execute! -- given a connectable and SQL + parameters or a statement, execute the SQL, consume the ResultSet produced, and return a vector of hash maps representing the rows (@1); this can be datafied to allow navigation of foreign keys into other tables (either by convention or via a schema definition),
  • execute-one! -- given a connectable and SQL + parameters or a statement, execute the SQL, consume the first row of the ResultSet produced, and return a hash map representing that row; this can be datafied to allow navigation of foreign keys into other tables (either by convention or via a schema definition),
  • execute-batch! -- given a PreparedStatement and groups of parameters, execute the statement in batch mode (via .executeBatch); given a connectable, a SQL string, and groups of parameters, create a new PreparedStatement from the SQL and execute it in batch mode.
  • prepare -- given a Connection and SQL + parameters, construct a new PreparedStatement; in general this should be used with with-open,
  • transact -- the functional implementation of with-transaction,
  • with-transaction -- execute a series of SQL operations within a transaction.

@1 result sets are built, by default, as vectors of hash maps, containing qualified keywords as column names, but the row builder and result set builder machinery is open and alternatives are provided to produce unqualified keywords as column names, and to produce a vector the column names followed by vectors of column values for each row, and lower-case variants of each.

The following options are supported wherever a Connection is created:

  • :auto-commit -- either true or false,
  • :read-only -- either true or false,
  • :connection -- a hash map of camelCase properties to set, via reflection, on the Connection object after it is created.

The following options are supported wherever a Statement or PreparedStatement is created:

  • :concurrency -- :read-only, :updatable,
  • :cursors -- :close, :hold
  • :fetch-size -- the fetch size value,
  • :max-rows -- the maximum number of rows to return,
  • :result-type -- :forward-only, :scroll-insensitive, :scroll-sensitive,
  • :timeout -- the query timeout,
  • :statement -- a hash map of camelCase properties to set, via reflection, on the Statement or PreparedStatement object after it is created.

In addition, wherever a PreparedStatement is created, you may specify:

  • :return-keys -- either true or a vector of key names to return.
The public API of the next generation java.jdbc library.

The basic building blocks are the `java.sql`/`javax.sql` classes:
* `DataSource` -- something to get connections from,
* `Connection` -- an active connection to the database,
* `PreparedStatement` -- SQL and parameters combined, from a connection,

and the following functions and a macro:
* `get-datasource` -- given a hash map describing a database or a JDBC
    connection string, construct a `javax.sql.DataSource` and return it,
* `get-connection` -- given a connectable, obtain a new `java.sql.Connection`
    from it and return that,
* `plan` -- given a connectable and SQL + parameters or a statement,
    return a reducible that, when reduced (with an initial value) will
    execute the SQL and consume the `ResultSet` produced,
* `execute!` -- given a connectable and SQL + parameters or a statement,
    execute the SQL, consume the `ResultSet` produced, and return a vector
    of hash maps representing the rows (@1); this can be datafied to allow
    navigation of foreign keys into other tables (either by convention or
    via a schema definition),
* `execute-one!` -- given a connectable and SQL + parameters or a statement,
    execute the SQL, consume the first row of the `ResultSet` produced, and
    return a hash map representing that row; this can be datafied to allow
    navigation of foreign keys into other tables (either by convention or
    via a schema definition),
* `execute-batch!` -- given a `PreparedStatement` and groups of parameters,
    execute the statement in batch mode (via `.executeBatch`); given a
    connectable, a SQL string, and groups of parameters, create a new
    `PreparedStatement` from the SQL and execute it in batch mode.
* `prepare` -- given a `Connection` and SQL + parameters, construct a new
    `PreparedStatement`; in general this should be used with `with-open`,
* `transact` -- the functional implementation of `with-transaction`,
* `with-transaction` -- execute a series of SQL operations within a transaction.

@1 result sets are built, by default, as vectors of hash maps, containing
    qualified keywords as column names, but the row builder and result set
    builder machinery is open and alternatives are provided to produce
    unqualified keywords as column names, and to produce a vector the
    column names followed by vectors of column values for each row, and
    lower-case variants of each.

The following options are supported wherever a `Connection` is created:
* `:auto-commit` -- either `true` or `false`,
* `:read-only` -- either `true` or `false`,
* `:connection` -- a hash map of camelCase properties to set, via reflection,
    on the `Connection` object after it is created.

The following options are supported wherever a `Statement` or
`PreparedStatement` is created:
* `:concurrency` -- `:read-only`, `:updatable`,
* `:cursors` -- `:close`, `:hold`
* `:fetch-size` -- the fetch size value,
* `:max-rows` -- the maximum number of rows to return,
* `:result-type` -- `:forward-only`, `:scroll-insensitive`, `:scroll-sensitive`,
* `:timeout` -- the query timeout,
* `:statement` -- a hash map of camelCase properties to set, via reflection,
    on the `Statement` or `PreparedStatement` object after it is created.

In addition, wherever a `PreparedStatement` is created, you may specify:
* `:return-keys` -- either `true` or a vector of key names to return.
raw docstring

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

next.jdbc.datafy

This namespace provides datafication of several JDBC object types, all within the java.sql package:

  • Connection -- datafies as a bean.
  • DatabaseMetaData -- datafies as a bean; six properties are navigable to produce fully-realized datafiable result sets.
  • ParameterMetaData -- datafies as a vector of parameter descriptions.
  • ResultSet -- datafies as a bean; if the ResultSet has an associated Statement and that in turn has an associated Connection then an additional key of :rows is provided which is a datafied result set, from next.jdbc.result-set/datafiable-result-set with default options. This is provided as a convenience, purely for datafication of other JDBC data types -- in normal next.jdbc usage, result sets are datafied under full user control.
  • ResultSetMetaData -- datafies as a vector of column descriptions.
  • Statement -- datafies as a bean.

Because different database drivers may throw SQLException for various unimplemented or unavailable properties on objects in various states, the default behavior is to return those exceptions using the :qualify option for clojure.java.data/from-java-shallow, so for a property :foo, if its corresponding getter throws an exception, it would instead be returned as :foo/exception. This behavior can be overridden by binding next.jdbc.datafy/*datafy-failure* to any of the other options supported: :group, :omit, or :return. See the clojure.java.data documentation for more details.

This namespace provides datafication of several JDBC object types,
all within the `java.sql` package:

* `Connection` -- datafies as a bean.
* `DatabaseMetaData` -- datafies as a bean; six properties
      are navigable to produce fully-realized datafiable result sets.
* `ParameterMetaData` -- datafies as a vector of parameter descriptions.
* `ResultSet` -- datafies as a bean; if the `ResultSet` has an associated
      `Statement` and that in turn has an associated `Connection` then an
      additional key of `:rows` is provided which is a datafied result set,
      from `next.jdbc.result-set/datafiable-result-set` with default options.
      This is provided as a convenience, purely for datafication of other
      JDBC data types -- in normal `next.jdbc` usage, result sets are
      datafied under full user control.
* `ResultSetMetaData` -- datafies as a vector of column descriptions.
* `Statement` -- datafies as a bean.

Because different database drivers may throw `SQLException` for various
unimplemented or unavailable properties on objects in various states,
the default behavior is to return those exceptions using the `:qualify`
option for `clojure.java.data/from-java-shallow`, so for a property
`:foo`, if its corresponding getter throws an exception, it would instead
be returned as `:foo/exception`. This behavior can be overridden by
`binding` `next.jdbc.datafy/*datafy-failure*` to any of the other options
supported: `:group`, `:omit`, or `:return`. See the `clojure.java.data`
documentation for more details.
raw docstring

next.jdbc.date-time

Optional namespace that extends next.jdbc.prepare/SettableParameter to various date/time types so that they will all be treated as SQL timestamps (which also supports date and time column types) and has functions to extend next.jdbc.result-set/ReadableColumn.

Simply requiring this namespace will extend the SettableParameter protocol to the four types listed below.

In addition, there are several read-as-* functions here that will extend next.jdbc.result-set/ReadableColumn to allow java.sql.Date and java.sql.Timestamp columns to be read as (converted to) various Java Time types automatically. The expectation is that you will call at most one of these, at application startup, to enable the behavior you want.

Database support for Java Time:

  • H2 and SQLite support conversion of Java Time (Instant, LocalDate, LocalDateTime) out of the box,
  • Nearly all databases support conversion of java.util.Date out of the box -- except PostgreSQL apparently!

Types supported by this namespace:

  • java.time.Instant
  • java.time.LocalDate
  • java.time.LocalDateTime
  • java.util.Date -- mainly for PostgreSQL

PostgreSQL does not seem able to convert java.util.Date to a SQL timestamp by default (every other database can!) so you'll probably need to require this namespace, even if you don't use Java Time, when working with PostgreSQL.

Optional namespace that extends `next.jdbc.prepare/SettableParameter`
to various date/time types so that they will all be treated as SQL
timestamps (which also supports date and time column types) and has
functions to extend `next.jdbc.result-set/ReadableColumn`.

Simply requiring this namespace will extend the `SettableParameter` protocol
to the four types listed below.

In addition, there are several `read-as-*` functions here that will
extend `next.jdbc.result-set/ReadableColumn` to allow `java.sql.Date`
and `java.sql.Timestamp` columns to be read as (converted to) various
Java Time types automatically. The expectation is that you will call at
most one of these, at application startup, to enable the behavior you want.

Database support for Java Time:
* H2 and SQLite support conversion of Java Time (`Instant`, `LocalDate`,
  `LocalDateTime`) out of the box,
* Nearly all databases support conversion of `java.util.Date` out of
  the box -- except PostgreSQL apparently!

Types supported by this namespace:
* `java.time.Instant`
* `java.time.LocalDate`
* `java.time.LocalDateTime`
* `java.util.Date` -- mainly for PostgreSQL

PostgreSQL does not seem able to convert `java.util.Date` to a SQL
timestamp by default (every other database can!) so you'll probably
need to require this namespace, even if you don't use Java Time, when
working with PostgreSQL.
raw docstring

next.jdbc.optional

Builders that treat NULL SQL values as 'optional' and omit the corresponding keys from the Clojure hash maps for the rows.

Builders that treat NULL SQL values as 'optional' and omit the
corresponding keys from the Clojure hash maps for the rows.
raw docstring

next.jdbc.plan

Some helper functions that make common operations with next.jdbc/plan much easier.

Some helper functions that make common operations with `next.jdbc/plan`
much easier.
raw docstring

next.jdbc.prepare

Mostly an implementation namespace for how PreparedStatement objects are created by the next generation java.jdbc library.

set-parameters is public and may be useful if you have a PreparedStatement that you wish to reuse and (re)set the parameters on it.

Defines the SettableParameter protocol for converting Clojure values to database-specific values.

See also https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT/api/next.jdbc.date-time for implementations of SettableParameter that provide automatic conversion of Java Time objects to SQL data types.

See also https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT/api/next.jdbc.types for as-xxx functions that provide per-instance implementations of SettableParameter for each of the standard java.sql.Types values.

Mostly an implementation namespace for how `PreparedStatement` objects are
created by the next generation java.jdbc library.

`set-parameters` is public and may be useful if you have a `PreparedStatement`
that you wish to reuse and (re)set the parameters on it.

Defines the `SettableParameter` protocol for converting Clojure values
to database-specific values.

See also https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT/api/next.jdbc.date-time
for implementations of `SettableParameter` that provide automatic
conversion of Java Time objects to SQL data types.

See also https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT/api/next.jdbc.types
for `as-xxx` functions that provide per-instance implementations of
`SettableParameter` for each of the standard `java.sql.Types` values.
raw docstring

next.jdbc.protocols

This is the extensible core of the next generation java.jdbc library.

  • Sourceable -- for producing javax.sql.DataSource objects,
  • Connectable -- for producing new java.sql.Connection objects,
  • Executable -- for executing SQL operations,
  • Preparable -- for producing new java.sql.PreparedStatement objects,
  • Transactable -- for executing SQL operations transactionally.
This is the extensible core of the next generation java.jdbc library.

* `Sourceable` -- for producing `javax.sql.DataSource` objects,
* `Connectable` -- for producing new `java.sql.Connection` objects,
* `Executable` -- for executing SQL operations,
* `Preparable` -- for producing new `java.sql.PreparedStatement` objects,
* `Transactable` -- for executing SQL operations transactionally.
raw docstring

next.jdbc.quoted

Provides functions for use with the :table-fn and :column-fn options that define how SQL entities should be quoted in strings constructed from Clojure data.

Provides functions for use with the `:table-fn` and `:column-fn` options
that define how SQL entities should be quoted in strings constructed
from Clojure data.
raw docstring

next.jdbc.result-set

An implementation of ResultSet handling functions.

Defines the following protocols:

  • DatafiableRow -- for turning a row into something datafiable
  • ReadableColumn -- to read column values by label or index
  • RowBuilder -- for materializing a row
  • ResultSetBuilder -- for materializing a result set

A broad range of result set builder implementation functions are provided.

Also provides the default implementations for Executable and the default datafy/nav behavior for rows from a result set.

See also https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT/api/next.jdbc.date-time for implementations of ReadableColumn that provide automatic conversion of some SQL data types to Java Time objects.

An implementation of `ResultSet` handling functions.

Defines the following protocols:
* `DatafiableRow` -- for turning a row into something datafiable
* `ReadableColumn` -- to read column values by label or index
* `RowBuilder` -- for materializing a row
* `ResultSetBuilder` -- for materializing a result set

A broad range of result set builder implementation functions are provided.

Also provides the default implementations for `Executable` and
the default `datafy`/`nav` behavior for rows from a result set.

See also https://cljdoc.org/d/com.github.seancorfield/next.jdbc/CURRENT/api/next.jdbc.date-time
for implementations of `ReadableColumn` that provide automatic
conversion of some SQL data types to Java Time objects.
raw docstring

next.jdbc.specs

Specs for the core API of next.jdbc.

The functions from next.jdbc, next.jdbc.sql, and next.jdbc.prepare have specs here.

Just :args are spec'd. These specs are intended to aid development with next.jdbc by catching simple errors in calling the library. The connectable argument is currently just any? but both get-datasource and get-connection have stricter specs.

In addition, there is an instrument function that provides a simple way to instrument all of the next.jdbc functions, and unstrument to undo that.

Specs for the core API of next.jdbc.

The functions from `next.jdbc`, `next.jdbc.sql`, and `next.jdbc.prepare`
have specs here.

Just `:args` are spec'd. These specs are intended to aid development
with `next.jdbc` by catching simple errors in calling the library.
The `connectable` argument is currently just `any?` but both
`get-datasource` and `get-connection` have stricter specs.

In addition, there is an `instrument` function that provides a simple
way to instrument all of the `next.jdbc` functions, and `unstrument`
to undo that.
raw docstring

next.jdbc.sql

Some utility functions that make common operations easier by providing some syntactic sugar over execute!/execute-one!.

This is intended to provide a minimal level of parity with clojure.java.jdbc (insert!, insert-multi!, query, find-by-keys, get-by-id, update!, and delete!).

For anything more complex, use a library like HoneySQL https://github.com/seancorfield/honeysql to generate SQL + parameters.

The following options are supported:

  • :table-fn -- specify a function used to convert table names (strings) to SQL entity names -- see the next.jdbc.quoted namespace for the most common quoting strategy functions,
  • :column-fn -- specify a function used to convert column names (strings) to SQL entity names -- see the next.jdbc.quoted namespace for the most common quoting strategy functions.

In addition, find-by-keys supports :order-by to add an ORDER BY clause to the generated SQL.

Some utility functions that make common operations easier by
providing some syntactic sugar over `execute!`/`execute-one!`.

This is intended to provide a minimal level of parity with
`clojure.java.jdbc` (`insert!`, `insert-multi!`, `query`, `find-by-keys`,
`get-by-id`, `update!`, and `delete!`).

For anything more complex, use a library like HoneySQL
https://github.com/seancorfield/honeysql to generate SQL + parameters.

The following options are supported:
* `:table-fn` -- specify a function used to convert table names (strings)
    to SQL entity names -- see the `next.jdbc.quoted` namespace for the
    most common quoting strategy functions,
* `:column-fn` -- specify a function used to convert column names (strings)
    to SQL entity names -- see the `next.jdbc.quoted` namespace for the
    most common quoting strategy functions.

In addition, `find-by-keys` supports `:order-by` to add an `ORDER BY`
clause to the generated SQL.
raw docstring

next.jdbc.sql.builder

Some utility functions for building SQL strings.

These were originally private functions in next.jdbc.sql but they may prove useful to developers who want to write their own 'SQL sugar' functions, such as a database-specific upsert! etc.

Some utility functions for building SQL strings.

These were originally private functions in `next.jdbc.sql` but
they may prove useful to developers who want to write their own
'SQL sugar' functions, such as a database-specific `upsert!` etc.
raw docstring

next.jdbc.transaction

Implementation of SQL transaction logic.

In general, you cannot nest transactions. clojure.java.jdbc would ignore any attempt to create a nested transaction, even tho' some databases do support it. next.jdbc allows you to call with-transaction even while you are inside an active transaction, but the behavior may vary across databases and the commit or rollback boundaries may not be what you expect. In order to avoid two transactions constructed on the same connection from interfering with each other, next.jdbc locks on the Connection object (this prevents concurrent transactions on separate threads from interfering but will cause deadlock on a single thread -- so beware).

Consequently, this namespace exposes a dynamic variable, *nested-tx*, which can be used to vary the behavior when an attempt is made to start a transaction when you are already inside a transaction.

Implementation of SQL transaction logic.

In general, you cannot nest transactions. `clojure.java.jdbc` would
ignore any attempt to create a nested transaction, even tho' some
databases do support it. `next.jdbc` allows you to call `with-transaction`
even while you are inside an active transaction, but the behavior may
vary across databases and the commit or rollback boundaries may not be
what you expect. In order to avoid two transactions constructed on the
same connection from interfering with each other, `next.jdbc` locks on
the `Connection` object (this prevents concurrent transactions on separate
threads from interfering but will cause deadlock on a single thread --
so beware).

Consequently, this namespace exposes a dynamic variable, `*nested-tx*`,
which can be used to vary the behavior when an attempt is made to start
a transaction when you are already inside a transaction.
raw docstring

next.jdbc.types

Provides convenience functions for wrapping values you pass into SQL operations that have per-instance implementations of SettableParameter so that .setObject() is called with the appropriate java.sql.Types value.

Provides convenience functions for wrapping values you pass into SQL
operations that have per-instance implementations of `SettableParameter`
so that `.setObject()` is called with the appropriate `java.sql.Types` value.
raw docstring

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

× close