package caqti

  1. Overview
  2. Docs
On This Page
  1. Value Formatters
package caqti
Legend:
Library
Module
Module type
Parameter
Class
Class type

Format-based query construction.

type 'a t = Stdlib.Format.formatter -> 'a -> unit

The type of a function which formats values of type 'a or fragments based on an input of type 'a.

val qprintf : ('a, Stdlib.Format.formatter, unit, Caqti_query.t) Stdlib.format4 -> 'a

qprintf allows building Caqti queries using a printf-style interface.

When using qprintf, you can use the query, quote, env and param printers from this module to generate the corresponding query fragments.

In addition, you can use the "Q" and "E" string tags to delimit portions of the formatting string that should be interpreted as quotes and environment variables, respectively. The "Q" and "E" tags can not be nested: within the tags, qprintf behaves no differently than Format.asprintf and will generate a string, not a query (only when the tag is closed does the string get converted into a query).

The two following calls to qprintf:

qprintf "FUNC(@{<Q>Quoted value with %d format(s)})" 1

and

qprintf "FUNC(%a)" quote (Format.asprintf "Quoted value with %d format(s)" 1)

are functionally equivalent. Both compute

S [L "FUNC("; Q "Quoted value with 1 format(s)"; L ")"]

but the first one is nicer to work with.

  • raises Failure

    if the "Q" and "E" tags are nested.

val kqprintf : (Caqti_query.t -> 'a) -> ('b, Stdlib.Format.formatter, unit, 'a) Stdlib.format4 -> 'b

kqprintf is the continuation-passing version of qprintf (like Format.kasprintf for Format.asprintf).

You usually want qprintf instead.

val param : int t

param is a formatter that includes the corresponding parameter in a query built by qprintf.

Note that to include a parameter in a query, param *must* be used: using literal "$" or "?" will be sent as-is to the SQL driver and will not be processed by Caqti.

val env : string t

env is a formatter that includes the corresponding environment variable in a query built by qprintf.

Note that to include an environment variable in a query, env *must* be used: using literal "$(...)" will be sent as-is to the SQL driver and will not be processed by Caqti.

val quote : string t

quote is a formatter that includes a TEXT literal in a query built by qprintf.

val query : Caqti_query.t t

query can be used with qprintf to embed a query that was already parsed in the format string. Direct use of query should be rare, and param, env, or quote should be used instead when possible.

Using query with any other formatter will ignore the query and instead print a dummy value (currently "... SQL FRAGMENT ...") instead.

Value Formatters

The following formatters emit values of basic field types by passing them as parameters. This is done by emitting a Caqti_query.t.V node with a appropriate field type.

val bool : bool t
val int : int t
val float : float t
val string : string t
val octets : string t
val pdate : Ptime.t t
val ptime : Ptime.t t
val ptime_span : Ptime.span t