Module Caqti_template.RequestSource

Request template.

A request template combines a function to generate an SQL query template with type descriptors use to encode parameters and decode result rows. The function will receive information about the SQL dialect when called by the chosen database driver library.

Requests are passed to Caqti_connection_sig.S.call or one of its shortcut methods provided by a database connection handle, and will be turned into a prepared query, cached by the connection handle, if prepared queries are supported by the driver and unless explicitly disabled, see create for details on the latter.

Primitive Constructor and Accessors

Sourcetype prepare_policy =
  1. | Direct
    (*

    The query string is sent to the database on each request, or if the driver only supports prepared queries, the preprepared query will be released after each use. Most importantly nothing is retained by the driver related to request template created with this policy, so this is a safe option for dynamically generated request templates. This option is only a suitable choice when it is known in advance that the request will be executed at most once, or very rarely, such as schema updates.

    *)
  2. | Dynamic
    (*

    The query string is prepared once per connection and scheduled for release after the request object has been garbage collected.

    *)
  3. | Static
    (*

    The query string is prepared once per connection on not released before the connection is closed. This policy will cause a resource leak on long-lived connections if the template is dynamically generated. As the name suggest, this policy should only be used when the request template has static lifetime.

    *)

The prepare policy decides whether Caqti drivers use prepared queries and, if so, the expected lifetime of the template.

Sourcetype ('a, 'b, +'m) t constraint 'm = [< `Zero | `One | `Many ]

A request specification embedding a query generator, parameter encoder, and row decoder.

  • 'a is the type of the expected parameter bundle.
  • 'b is the type of a returned row.
  • 'm is the possible multiplicities of returned rows.
Sourceval create : prepare_policy -> ('a Row_type.t * 'b Row_type.t * 'm Row_mult.t) -> (Dialect.t -> Query.t) -> ('a, 'b, 'm) t

create prepare_policy (arg_type, row_type, row_mult) f is a request template

  • whose query will be prepared (or not) according to prepare_policy,
  • which takes parameters of type arg_type,
  • which returns rows of type row_type with multiplicity row_mult, and
  • which submits a query string rendered from the Query.t returned by f di, where di is the Dialect.t supplied by the driver library of the connection.

The driver is responsible for turning parameter references into a form accepted by the database system, while other dialectical differences must be handled by f.

The function f should be pure; no guarantee is given on when and how many times it is called. For efficiency reasons it is memoized internally using a small LRU cache, reflecting that fact that it is typically only called on a few arguments during the lifetime of the program.

Sourceval create_multi : prepare_policy -> (Dialect.t -> Query.t list) -> (unit, unit, [ `Zero ]) t

create_multi prepare_policy f creates a request template which can contain multiple queries and no query. Neither parameters nor result rows are supported.

For schema initialization, using Direct prepare policy is recommended. In particular, if one statement depends on tables or other objects created by a previous statement, then only the Direct policy works across all database systems. Prepared queries are typically restricted to single statements, in which case Caqti will prepare them separatly. For SQLite3, at least, a statement depending on a object cannot be prepared before the statement creating the object is executed.

Sourceval prepare_policy : (_, _, _) t -> prepare_policy

prepare_policy req is the prepare policy of req.

Sourceval param_type : ('a, _, _) t -> 'a Row_type.t

param_type req is the type of parameter bundles expected by req.

Sourceval row_type : (_, 'b, _) t -> 'b Row_type.t

row_type req is the type of rows returned by req.

Sourceval row_mult : (_, _, 'm) t -> 'm Row_mult.t

row_mult req indicates how many rows req may return. This is asserted when constructing the query.

Sourceval queries : ('a, 'b, 'm) t -> Dialect.t -> Query.t list

queries req returns a function which, given a driver, generates the list of queries to execute in order. All queries receive the same parameters and the last query provides the result set. If the list of queries is empty, no operation is performed and the request type must allow an empty response.

Formatting

Sourceval make_pp : ?dialect:Dialect.t -> ?subst:Query.subst -> unit -> Format.formatter -> ('a, 'b, 'm) t -> unit

make_pp ?subst ?dialect () is a pretty-printer for a request, which expands the query using subst and dialect.

  • parameter subst

    Used to partially expand the query string. Defaults to the empty substitution.

  • parameter dialect

    The driver info to pass to the call-back which returns the query. Defaults to Dialect.Unknown.

Sourceval pp : Format.formatter -> ('a, 'b, 'm) t -> unit

pp ppf req prints req on ppf in a form suitable for human inspection.

Sourceval make_pp_with_param : ?dialect:Dialect.t -> ?subst:Query.subst -> unit -> Format.formatter -> (('a, 'b, 'm) t * 'a) -> unit

make_pp_with_param ?subst ?dialect () is a pretty-printer for a request and parameter pair. See make_pp for the optional arguments. This functions is meant for debugging; the output is neither guaranteed to be consistent across releases nor to contain a complete record of the data. Lost database records cannot be reconstructed from the logs.

Due to concerns about exposure of sensitive data in debug logs, this function only prints the parameter values if CAQTI_DEBUG_PARAM is set to true. If you enable it for applications which do not consistenly annotate sensitive parameters with Row_type.redacted, make sure your debug logs are well-secured.