Module `Template.Request`

Request templates. A request template combines a query template from which SQL code is generated, with a request type describing how to encode parameters and decode result rows.

The query template is parametrized over a Template.Dialect.t provided by the database driver, esp. to identify the SQL dialect and other relevant information about the RDMBS.

To execute a query, a request template is passed to Connection.S.call or one of its shortcut methods provided by a database connection handle, and may be turned into a prepared query and cached on the database handle, depending on the prepare_policy and driver support.

Primitive Constructor and Accessors

type prepare_policy =

| 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.
*)
| Dynamic
(*
The query string is prepared once per connection and scheduled for release after the request object has been garbage collected.
*)
| 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.

type ('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.

val create : 
  prepare_policy ->
  ('a, 'b, 'm) Request_type.t ->
  (Template.Dialect.t -> Template.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.

val create_multi : 
  prepare_policy ->
  (Template.Dialect.t -> Template.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.

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

prepare_policy req is the prepare policy of req.

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

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

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

row_type req is the type of rows returned by req.

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

val queries : ('a, 'b, 'm) t -> Template.Dialect.t -> Template.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

val make_pp : 
  ?dialect:Template.Dialect.t ->
  ?subst:Template.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.

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

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

val make_pp_with_param : 
  ?dialect:Template.Dialect.t ->
  ?subst:Template.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.

Install

dune-project
Dependency

Authors

Maintainers

Sources

doc/caqti/Caqti/Template/Request/index.html

Module `Template.Request`

Primitive Constructor and Accessors

Formatting

package caqti

Install

dune-project Dependency

Authors

Maintainers

Sources

doc/caqti/Caqti/Template/Request/index.html

Module Template.Request

Primitive Constructor and Accessors

Formatting

dune-project
Dependency

Module `Template.Request`