package caqti

  1. Overview
  2. Docs
package caqti
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

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.

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

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.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct