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 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),
* `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.

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.

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 propertiies 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.

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.

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

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.

`execute-batch!` provides a way to add batches of parameters to a
`PreparedStatement` and then execute it in batch mode (via `.executeBatch`).

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

See also https://cljdoc.org/d/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/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.

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.

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.

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 implemenations for `Executable` and
the default `datafy`/`nav` behavior for rows from a result set.

See also https://cljdoc.org/d/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.

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. If you
extend `Sourceable` or `Connectable`, those specs will likely be too strict.

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.

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/jkk/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 for building SQL strings.

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

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.

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.