next.jdbc.result-set — seancorfield/next.jdbc 1.1.613

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.

ArrayResultSetBuilder clj

as-arrays clj

(as-arrays rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces a vector of column names followed by vectors of row values.

as-arrays-adapter clj

(as-arrays-adapter builder-fn column-reader)

Given an array builder function (e.g., as-unqualified-arrays) and a column reading function, return a new builder function that uses that column reading function instead of .getObject so you can override the default behavior.

The default column-reader behavior would be equivalent to:

(defn default-column-reader
  [^ResultSet rs ^ResultSetMetaData rsmeta ^Integer i]
  (.getObject rs i))

Your column-reader can use the result set metadata to determine whether to call .getObject or some other method to read the column's value.

read-column-by-index is still called on the result of that read.

Note: this is different behavior to builder-adapter's column-by-index-fn.

as-lower-arrays clj

(as-lower-arrays rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces a vector of lower-case column names followed by vectors of row values.

as-lower-maps clj

(as-lower-maps rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces bare vectors of hash map rows, with lower-case keys.

as-maps clj

(as-maps rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces bare vectors of hash map rows.

This is the default :builder-fn option.

as-maps-adapter clj

(as-maps-adapter builder-fn column-reader)

Given a map builder function (e.g., as-lower-maps) and a column reading function, return a new builder function that uses that column reading function instead of .getObject so you can override the default behavior.

The default column-reader behavior would be equivalent to:

(defn default-column-reader
  [^ResultSet rs ^ResultSetMetaData rsmeta ^Integer i]
  (.getObject rs i))

Your column-reader can use the result set metadata to determine whether to call .getObject or some other method to read the column's value.

read-column-by-index is still called on the result of that read.

Note: this is different behavior to builder-adapter's column-by-index-fn.

as-modified-arrays clj

(as-modified-arrays rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces a vector of modified column names followed by vectors of row values.

Requires both the :qualifier-fn and :label-fn options.

as-modified-maps clj

(as-modified-maps rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces bare vectors of hash map rows, with modified keys.

Requires both the :qualifier-fn and :label-fn options.

as-unqualified-arrays clj

(as-unqualified-arrays rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces a vector of simple column names followed by vectors of row values.

as-unqualified-lower-arrays clj

(as-unqualified-lower-arrays rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces a vector of simple, lower-case column names followed by vectors of row values.

as-unqualified-lower-maps clj

(as-unqualified-lower-maps rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces bare vectors of hash map rows, with simple, lower-case keys.

as-unqualified-maps clj

(as-unqualified-maps rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces bare vectors of hash map rows, with simple keys.

as-unqualified-modified-arrays clj

(as-unqualified-modified-arrays rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces a vector of simple, modified column names followed by vectors of row values.

Requires the :label-fn option.

as-unqualified-modified-maps clj

(as-unqualified-modified-maps rs opts)

Given a ResultSet and options, return a RowBuilder / ResultSetBuilder that produces bare vectors of hash map rows, with simple, modified keys.

Requires the :label-fn option.

builder-adapter clj

(builder-adapter builder-fn column-by-index-fn)

Given any builder function (e.g., as-lower-maps) and a column reading function, return a new builder function that uses that column reading function instead of .getObject and read-column-by-index so you can override the default behavior.

The default column-by-index-fn behavior would be equivalent to:

(defn default-column-by-index-fn
  [builder ^ResultSet rs ^Integer i]
  (read-column-by-index (.getObject rs i) (:rsmeta builder) i))

Your column-by-index-fn can use the result set metadata (:rsmeta builder) and/or the (processed) column name (nth (:cols builder) (dec i)) to determine whether to call .getObject or some other method to read the column's value, and can choose whether or not to use the ReadableColumn protocol-based value processor (and could add metadata to the value to satify that protocol on a per-instance basis).

clob->string clj

(clob->string clob)

Given a CLOB column value, read it as a string.

clob-column-reader clj

(clob-column-reader rs _ i)

An example column-reader that still uses .getObject but expands CLOB columns into strings.

datafiable-result-set clj

(datafiable-result-set rs)

(datafiable-result-set rs conn-or-opts)

(datafiable-result-set rs connectable opts)

Given a ResultSet, a connectable, and an options hash map, return a fully realized, datafiable result set per the :builder-fn option passed in. If no :builder-fn option is provided, as-maps is used as the default.

The connectable and the options can both be omitted. If connectable is omitted, nil is used and no foreign key navigation will be available for any datafied result. If you want to pass a hash map as the connectable, you must also pass an options hash map.

This can be used to process regular result sets or metadata result sets.

DatafiableRow clj protocol

Protocol for making rows datafiable and therefore navigable.

The default implementation just adds metadata so that datafy can be called on the row, which will produce something that nav can be called on, to lazily navigate through foreign key relationships into other tables.

If datafiable-row is called when reducing the result set produced by next.jdbc/plan, the row is fully-realized from the ResultSet first, using the :builder-fn (or as-maps by default).

datafiable-row clj

(datafiable-row this connectable opts)

Produce a datafiable representation of a row from a ResultSet.

foldable-result-set clj

(foldable-result-set rs)

(foldable-result-set rs conn-or-opts)

(foldable-result-set rs connectable opts)

Given a ResultSet and an optional connectable, return an r/CollFold that can be folded. An options hash map may be provided.

You are responsible for ensuring the Connection for this ResultSet and the connectable both remain open until the fold is complete!

If the connectable is omitted, no foreign key navigation would be available in any datafied result. If you want to pass a hash map as the connectable, you must also pass an options hash map.

get-column-names clj

(get-column-names rsmeta _)

Given ResultSetMetaData, return a vector of column names, each qualified by the table from which it came.

get-lower-column-names clj

(get-lower-column-names rsmeta opts)

Given ResultSetMetaData, return a vector of lower-case column names, each qualified by the table from which it came.

get-modified-column-names clj

(get-modified-column-names rsmeta opts)

Given ResultSetMetaData, return a vector of modified column names, each qualified by the table from which it came.

Requires both the :qualifier-fn and :label-fn options.

get-unqualified-column-names clj

(get-unqualified-column-names rsmeta _)

Given ResultSetMetaData, return a vector of unqualified column names.

get-unqualified-lower-column-names clj

(get-unqualified-lower-column-names rsmeta opts)

Given ResultSetMetaData, return a vector of unqualified column names.

get-unqualified-modified-column-names clj

(get-unqualified-modified-column-names rsmeta opts)

Given ResultSetMetaData, return a vector of unqualified modified column names.

Requires the :label-fn option.

InspectableMapifiedResultSet clj protocol

Protocol for exposing aspects of the (current) result set via functions.

The intent here is to expose information that is associated with either the (current row of the) result set or the result set metadata, via functions that can be called inside a reducing function being used over next.jdbc/plan, including situations where the reducing function has to realize a row by calling datafiable-row but still wants to call these functions on the (realized) row.

column-names clj

(column-names this)

Return a vector of the column names from the result set.

Reifies the result builder, in order to construct column names, but should not cause any row realization.

metadata clj

(metadata this)

Return the raw ResultSetMetaData object from the result set.

Should not cause any row realization.

If next.jdbc.datafy has been required, this metadata will be fully-realized as a Clojure data structure, otherwise this should not be allowed to 'leak' outside of the reducing function as it may depend on the connection remaining open, in order to be valid.

row-number clj

(row-number this)

Return the current 1-based row number, if available.

Should not cause any row realization.

MapResultSetBuilder clj

ReadableColumn clj protocol

Protocol for reading objects from the java.sql.ResultSet. Default implementations (for Object and nil) return the argument, and the Boolean implementation ensures a canonicalized true/false value, but it can be extended to provide custom behavior for special types. Extension via metadata is supported.

read-column-by-index clj

(read-column-by-index val rsmeta idx)

Function for transforming values after reading them via a column index.

read-column-by-label clj

(read-column-by-label val label)

Function for transforming values after reading them via a column label.

reducible-result-set clj

(reducible-result-set rs)

(reducible-result-set rs opts)

Given a ResultSet, return an IReduceInit that can be reduced. An options hash map may be provided.

You are responsible for ensuring the Connection for this ResultSet remains open until the reduction is complete!

ResultSetBuilder clj protocol

Protocol for building result sets in various representations.

Default implementations for building vectors of hash maps and vectors of column names and row values: MapResultSetBuilder & ArrayResultSetBuilder

->rs clj

(->rs _)

Called to create the basis of the result set.

rs! clj

(rs! _ rs)

Called to finalize the result set once it is complete.

with-row clj

(with-row _ rs row)

Called with the result set and the row to be added.

RowBuilder clj protocol

Protocol for building rows in various representations.

The default implementation for building hash maps: MapResultSetBuilder

->row clj

(->row _)

Called once per row to create the basis of each row.

column-count clj

(column-count _)

Return the number of columns in each row.

row! clj

(row! _ row)

Called once per row to finalize each row once it is complete.

with-column clj

(with-column _ row i)

Called with the row and the index of the column to be added; this is expected to read the column value from the ResultSet!

with-column-value clj

(with-column-value _ row col v)

Called with the row, the column name, and the value to be added; this is a low-level function, typically used by with-column.