package caqti

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

Module Caqti_typeSource

Type descriptors for fields and tuples.

Sourceexception Reject of string
Sourcetype (_, _) eq =
  1. | Equal : ('a, 'a) eq
    (*

    Type equality witness. This will eventually be replaced by the equavalent definition available in Stdlib.Type since OCaml 5.1, but for now, we must keep backwards compatibility with older compilers.

    *)

Primitive Field Types

The following is normally only needed for drivers and to define new field types. Everything needed for common usage is covered in Row Types.

Sourcemodule Field : sig ... end

Facilities for extending and using primitive field types.

Row Types

Sourcetype _ product_id

A type-carrying identifier used in t to allow expressing equality predicates, including for associated values. This is not part of the public API, but exposed due to its occurrence in t.

Sourcetype _ t = private
  1. | Field : 'a Field.t -> 'a t
  2. | Option : 'a t -> 'a option t
  3. | Product : 'a product_id * 'i * ('a, 'i) product -> 'a t
  4. | Annot : [ `Redacted ] * 'a t -> 'a t

Type descriptor for row types.

Note. The concrete representation of this type should be considered private, including pattern-matching usage; use the below functions for compatibility with future versions.

Sourceand (_, _) product = private
  1. | Proj_end : ('a, 'a) product
  2. | Proj : 'b t * ('a -> 'b) * ('a, 'i) product -> ('a, 'b -> 'i) product
Sourcetype any =
  1. | Any : 'a t -> any

t with existentially wrapped static type.

Sourceval unify : 'a t -> 'b t -> ('a, 'b) eq option

If t1 and t2 are the same row type representations, then unify t1 t2 is the witness of the unification of their static type parameters, otherwise it is None.

Sourceval equal_value : 'a t -> 'a -> 'a -> bool

equal_value t is the equality predicate for values of row type t.

Sourceval length : 'a t -> int

length t is the number of fields used to represent t.

Sourceval pp : Format.formatter -> 'a t -> unit

pp ppf t prints a human presentation of t on ppf.

Sourceval pp_any : Format.formatter -> any -> unit

pp_any ppf t prints a human presentation of t on ppf.

Sourceval pp_value : Format.formatter -> ('a t * 'a) -> unit

pp_value ppf (t, v) prints a human representation of v given the type descriptor t. This function is meant for debugging; the output is neither guaranteed to be consistent across releases nor to contain a complete record of the data.

Sourceval show : 'a t -> string

show t is a human presentation of t.

Sourceval field : 'a Field.t -> 'a t

field ft is a row of a single field of type ft. This function can be used when adding new field types; use the below functions otherwise.

Sourcemodule Std : Caqti_type_sig.Std with type 'a t := 'a t and type ('a, 'i) product := ('a, 'i) product

Standard type descriptors provided as a submodule for easy inclusion.

include Caqti_type_sig.Std with type 'a t := 'a t and type ('a, 'i) product := ('a, 'i) product

Field Types

The following types correspond to what usually fits in a single field of a result row or input parameter set.

Sourceval bool : bool t

A bool mapped to boolean on the SQL side if supported, otherwise mapped to an integer.

Sourceval int : int t

An int mapped to a sufficiently wide integer on the SQL side.

Sourceval int16 : int t

An int mapped to a smallint (16 bits) on the SQL side.

Sourceval int32 : int32 t

An int32 mapped to an integer (32 bits) on the SQL side.

Sourceval int64 : int64 t

An int64 mapped to a bigint (64 bits) on the SQL side.

Sourceval float : float t

A float mapped to double precision or (best alternative) on the SQL side. Serialization may be lossy (e.g. base 10 may be used), so even if both sides support IEEE 754 double precision numbers, there may be discrepancies in the last digits of the binary representaton.

Sourceval string : string t

An UTF-8 string. The database should accept UTF-8 if non-ASCII characters are present.

Sourceval octets : string t

A string mapped to whichever type is used to represent binary data on the SQL side.

Sourceval pdate : Ptime.t t

A time truncated to a date and mapped to the SQL date type.

Sourceval ptime : Ptime.t t

An absolute time with driver-dependent precision. This corresponds to an SQL timestamp with time zone or a suitable alternative where not available:

  • MariaDB has datetime which is similar to the SQL timestamp and timestamp which is similar to the SQL timestamp with time zone, but the driver does not make the distinction. Caqti sets the session time zone to UTC to avoid misinterpretation, since time values are passed in both directions without time zones. Values have microsecond precision, but you will need to specify the desired precision in the database schema to avoid truncation.
  • PostgreSQL supports this type and it's a good option to avoid any time zone issues if used conistently both on the client side, in SQL expressions, and in the database schema. Note that timestamp with time zone is stored as UTC without time zone, taking up no more space then timestamp. The PostgreSQL timestamp type is problematic since how conversions work and the manual indicate that it is meant to be a local time, and since database columns of this type stores the value without conversion to UTC, it becomes prone to time zone changes. To mitigate the issue, Caqti sets the time zone of sessions to UTC.
  • Sqlite3 does not have a dedicated type for absolute time. The date and time is sent as strings expressed at the UTC time zone using same format that the SQLite datetime function and CURRENT_TIMESTAMP return, except for an additional three decimals to achive millisecond precision.

It might seem better to use standard RFC3339 format, since it is accepted by the SQLite functions, but that would misorder some time values if mixed with the results of these functions, even just the "Z" suffix would misorder values with different precision.

Date and time values which comes from the database without time zone are interpreted as UTC. This is not necessarily correct, and it is highly recommended to use SQL types which are transmitted with time zone information, even if this is UTC.

Sourceval ptime_span : Ptime.span t

A period of time. If the database lacks a dedicated representation, the integer number of seconds is used.

Sourceval enum : encode:('a -> string) -> decode:(string -> ('a, string) result) -> string -> 'a t

enum ~encode ~decode name creates an enum type which on the SQL side is named name, with cases which are converted with encode and decode functions. This is implemented in terms of the Caqti_type.Field.t.Enum field type.

Composite Types

Sourceval product : 'i -> ('a, 'i) product -> 'a t
Sourceval proj : 'b t -> ('a -> 'b) -> ('a, 'i) product -> ('a, 'b -> 'i) product
Sourceval proj_end : ('a, 'a) product

Given a set of projection functions p1 : t -> t1, ..., pN : t -> tN and a function intro : t1 -> ... -> tN -> t to reconstruct values of t from the projections,

  product intro
    @@ proj t1 p1
    @@ ...
    @@ proj tN pN
    @@ proj_end

defines a Caqti type for t, which on the database side will be represented by a consecutive list of fields corresponding to the types t1, ..., tN, each of which may be represented by multiple fields. That is, intro [project1 x] ... [projectN x] is equivalent to x according to an enforced or effective abstraction of t deemed adequate for the application logic.

intro may raise Caqti_type.Reject to indicate that a value cannot be constructed from the given arguments. Projection operators may also raise this exception to indicate that an object cannot be represented in the database, e.g. due to an overflow.

The above only states that intro is a left (pseudo-)inverse of the projections, which is what matters for a faithful representation of OCaml values. The opposite (projection functions being the left inverse of intro) may be relevant if the application needs preserve the database representation when updating objects.

Sourceval custom : encode:('a -> ('b, string) result) -> decode:('b -> ('a, string) result) -> 'b t -> 'a t

custom ~encode ~decode rep creates a custom type represented by rep, where encode is used to encode parameters into rep and decode is used to decode result rows from rep.

Sourceval option : 'a t -> 'a option t

option t turns a set of fields encoded as t into a correspending set of nullable fields. The encoder will encode None as into a tuple of NULL values and the decoder will return None if all fields are NULL.

If the type t itself is option t' for some t', or contains nested tuples and options such that all field types are nested under an option type, then it would have been possible to decode an all-NULL segment of a row as Some x where x is a corresponding tuple-option-tree terminating in None values. The above paragraph resolves this ambiguity since it implies that the outermost option possible will be decoded as None.

Sourceval redacted : 'a t -> 'a t

redacted t is the same type as t but sealed as potentially containing sensitive information to be redacted from pretty-printers and logs.

Tuple Types

As a common case of composite types, constructors for tuples up to 12 components are predefined here. Higher tuples can be created with product.

Sourceval unit : unit t

A type holding no fields. This is used to pass no parameters and as the result for queries which does not return any rows. It can also be nested in tuples, in which case it will not contribute to the total number of fields.

Sourceval t2 : 'a1 t -> 'a2 t -> ('a1 * 'a2) t

Creates a pair type.

Sourceval t3 : 'a1 t -> 'a2 t -> 'a3 t -> ('a1 * 'a2 * 'a3) t

Creates a 3-tuple type.

Sourceval t4 : 'a1 t -> 'a2 t -> 'a3 t -> 'a4 t -> ('a1 * 'a2 * 'a3 * 'a4) t

Creates a 4-tuple type.

Sourceval t5 : 'a1 t -> 'a2 t -> 'a3 t -> 'a4 t -> 'a5 t -> ('a1 * 'a2 * 'a3 * 'a4 * 'a5) t

Creates a 5-tuple type.

Sourceval t6 : 'a1 t -> 'a2 t -> 'a3 t -> 'a4 t -> 'a5 t -> 'a6 t -> ('a1 * 'a2 * 'a3 * 'a4 * 'a5 * 'a6) t

Creates a 6-tuple type.

Sourceval t7 : 'a1 t -> 'a2 t -> 'a3 t -> 'a4 t -> 'a5 t -> 'a6 t -> 'a7 t -> ('a1 * 'a2 * 'a3 * 'a4 * 'a5 * 'a6 * 'a7) t

Creates a 7-tuple type.

Sourceval t8 : 'a1 t -> 'a2 t -> 'a3 t -> 'a4 t -> 'a5 t -> 'a6 t -> 'a7 t -> 'a8 t -> ('a1 * 'a2 * 'a3 * 'a4 * 'a5 * 'a6 * 'a7 * 'a8) t

Creates a 8-tuple type.

Sourceval t9 : 'a1 t -> 'a2 t -> 'a3 t -> 'a4 t -> 'a5 t -> 'a6 t -> 'a7 t -> 'a8 t -> 'a9 t -> ('a1 * 'a2 * 'a3 * 'a4 * 'a5 * 'a6 * 'a7 * 'a8 * 'a9) t

Creates a 9-tuple type.

Sourceval t10 : 'a1 t -> 'a2 t -> 'a3 t -> 'a4 t -> 'a5 t -> 'a6 t -> 'a7 t -> 'a8 t -> 'a9 t -> 'a10 t -> ('a1 * 'a2 * 'a3 * 'a4 * 'a5 * 'a6 * 'a7 * 'a8 * 'a9 * 'a10) t

Creates a 10-tuple type.

Sourceval t11 : 'a1 t -> 'a2 t -> 'a3 t -> 'a4 t -> 'a5 t -> 'a6 t -> 'a7 t -> 'a8 t -> 'a9 t -> 'a10 t -> 'a11 t -> ('a1 * 'a2 * 'a3 * 'a4 * 'a5 * 'a6 * 'a7 * 'a8 * 'a9 * 'a10 * 'a11) t

Creates a 11-tuple type.

Sourceval t12 : 'a1 t -> 'a2 t -> 'a3 t -> 'a4 t -> 'a5 t -> 'a6 t -> 'a7 t -> 'a8 t -> 'a9 t -> 'a10 t -> 'a11 t -> 'a12 t -> ('a1 * 'a2 * 'a3 * 'a4 * 'a5 * 'a6 * 'a7 * 'a8 * 'a9 * 'a10 * 'a11 * 'a12) t

Creates a 12-tuple type.

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