Module `Caqti_template.Request`Source

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 =

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

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.

Source

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

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 query : ('a, 'b, 'm) t -> Dialect.t -> Query.t

query req is the function which generates the query of this request possibly tailored for the given driver.

Formatting

Source

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

Source

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

Install

Dune Dependency

Authors

Maintainers

Sources

doc/caqti.template/Caqti_template/Request/index.html

Module `Caqti_template.Request`Source

Primitive Constructor and Accessors

Formatting

package caqti

Install

Dune Dependency

Authors

Maintainers

Sources

doc/caqti.template/Caqti_template/Request/index.html

Module Caqti_template.RequestSource

Primitive Constructor and Accessors

Formatting

Module `Caqti_template.Request`Source