Module Caqti.TemplaterSource

This is a convenience API which collects everything needed to create request templates. A request template describes an SQL query, how to encode parameters, and how to decode result rows. This is the recommended entry point for typical usage.

Basic Usage

Consider the example:

  let bounds_upto_req =
    let open Caqti.Templater in
    static T.(t2 int32 float -->! option (t2 float float))
    "SELECT min(y), max(y) FROM samples WHERE series_id = ? AND x < ?"

First we opening the current module. We then pick the function static to create a template for prepared queries where the query template has static lifetime. The first argument describes the parameter type and the result row type combined with an arrow which describes the multiplicity of the result rows. The exclamation mark in the arrow indicates that precisely one result row is expected. The second argument is the query template, here in the form of a string.

In the query template, ? refer to parameters, but you can also use the PostgreSQL-style $1, $2, etc. if you prefer, as long as you stick to the same convention for a given query template. Caqti drivers translate parameter references to fit the database system, rearranging parameters if necessary.

Caqti provides a way to handle dialectical differences between database systems apart from the parameter syntax. The example above uses a shortcut, since it does not need this functionality. In the full form it looks like:

  let bounds_upto_req =
    let open Caqti.Templater in
    static_gen
      T.(t2 int32 float -->! option (t2 float float)) @@ Fun.const @@
      Q.parse
        "SELECT min(y), max(y) FROM samples WHERE series_id = ? AND x < ?"

The callback receives a Template.Dialect.t and returns a Template.Query.t. We can now see that the still same query string is explicitly parsed. Template.Query and Template.Query_fmt provides alternative ways of constructing query template which is more suitable for dynamically generated queries.

The following example makes use of the dialect argument to handle dialectical differences regarding string concatenation:

  let concat_req =
    let open Caqti.Templater in
    static_gen T.(t2 string string -->! string) @@ function
     | D.Mysql _ -> Q.parse "SELECT concat(?, ?)"
     | _ -> Q.parse "SELECT ? || ?"

In summary

• Pick the main function according to the lifetime of prepared queries and whether to use the simplified or generic callback.
• In the request type argument, the arrow decoration selects the expected multiplicity of result rows: -->. for zero, -->! for one, -->? for zero or one, -->* for zero or more.

Supplementing

If needed, you can supplement the current module with custom types:

  module Ct : sig
    open Caqti.Template

    include module type of (struct include Caqti.Templater end)

    module T : sig
      include module type of T

      val password : string Row_type.t
      val uri : Uri.t Row_type.t
    end
  end = struct
    open Caqti.Template

    include Caqti.Templater

    module T = struct
      include T

      let password = redacted string (* a string redacted from logs *)

      let uri =
        let encode x = Ok (Uri.to_string x) in
        let decode s = Ok (Uri.of_string s) in
        Row_type.custom ~encode ~decode string
    end
  end

Reference

Type Descriptors

Dialect Descriptors

Query Templates

Request Templates

The following are shortcuts for Template.Request.create and Template.Query.parse In particular static, dynamic, and direct covers the most common case of sending a pre-composed query string to the database while the static_gen, dynamic_gen, and direct_gen are the correspending fully generic variants.

Where the query is supplied as function of a dialect, the function should be pure and may be recalled repeatedly, cf. Template.Request.create.