package caqti

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

Module Caqti_errorSource

Error descriptors.

Error Causes

The cause type is an incomplete enumeration of consolidated causes of errors between different database systems. The selection includes the causes which are believed to be useful to handle and excludes causes which are specific to the implementation of a certain database system.

The causes are classified into subtypes to help matching them collectively. Each subtype has a fall-back case which is used if the database system does not clearly report one of the specific cases. An condition which is reported as the fall-back case may in a future version be reported as a specific case, possibly adding a new case to the subtype. Therefore, for backwards compatibility you should match the full subtype rather than the fall-back, e.g.

  (match Caqti_error.cause error with
   | `Unique_violation -> handle_unique_violation ()
   | #integrity_constraint_violation -> handle_other_constraint_violation ()
   | _ -> handle_other_error ())

This ensures that your code stil compiles when a new case is added to integrity_constraint_violation, and that the error condition receiving mapped to the new case is still handled by the subtype pattern when you link to the new version of Caqti.

Currently we do not have access to the extended error codes from SQLite3, meaning that all integrity constraint violation conditions will be reported as `Integrity_constraint_violation__don't_match.

Since the consolitation of each error condition requires some investitation and testing, the selection made is very conservative. If you need to handle an error which is currently unlisted, please open an issue or create a pull request. A pull request should, if possible, include a extension of test_error_cause.ml to demonstrate how the error is triggered by the database systems.

Sourcetype integrity_constraint_violation = [
  1. | `Restrict_violation
    (*

    This is meant to indicate that a deletion or update would cause a foreign key violation, although this may be reported as a `Foreign_key_violation.

    *)
  2. | `Not_null_violation
    (*

    An insertion or update attempts to assign a NULL value to column having a NOT NULL constraint.

    *)
  3. | `Foreign_key_violation
    (*

    An modification would cause a column to reference a non-existing key. This cause may also be reported for cases which should have been covered by `Restrict_violation.

    *)
  4. | `Unique_violation
    (*

    An insertion or update would duplicate a key as declared by a UNIQUE or PRIMARY KEY constraint.

    *)
  5. | `Check_violation
    (*

    A requested change would violate a CHECK constraint.

    *)
  6. | `Exclusion_violation
    (*

    A requested insertion or update would cause an overlap of rows according to an EXCLUDE constraint.

    *)
  7. | `Integrity_constraint_violation__don't_match
    (*

    An yet unclassified cause; match the full subtype instead.

    *)
]

A subtype of cause informing about violation of SQL constraints.

Sourcetype insufficient_resources = [
  1. | `Disk_full
    (*

    The server is out of disk space.

    *)
  2. | `Out_of_memory
    (*

    The server is out of memory

    *)
  3. | `Too_many_connections
    (*

    The server does not accept establishing more connections.

    *)
  4. | `Configuration_limit_exceeded
    (*

    Some unspecific server limit is exceeded.

    *)
  5. | `Insufficient_resources__don't_match
    (*

    An yet unclassified cause; match the full subtype instead.

    *)
]

A subtype of cause informing about insufficient resources on the server side.

Sourcetype cause = [
  1. | integrity_constraint_violation
  2. | insufficient_resources
  3. | `Unspecified__don't_match
]

The selection of causes of errors which have been mapped.

Sourceval show_cause : [< cause ] -> string

Messages

Sourcetype msg = ..

In this type, drivers can stash information about any errors in their own format, which can later be used for pretty-printing and or future operations. Drivers must call define_msg on each constructor added to this type.

Sourceval define_msg : pp:(Format.formatter -> msg -> unit) -> ?cause:(msg -> cause) -> extension_constructor -> unit

Mandatory registration of pretty-printer for a driver-supplied error descriptor.

Sourceval pp_msg : Format.formatter -> msg -> unit

pp_msg ppf msg formats msg on ppf.

Sourcetype msg +=
  1. | Msg : string -> msg
    (*

    The shape of locally generated messages and messages from drivers without dedicated error type.

    *)

Messages with Metadata

Note. Please consider the fields internal for now, they may still be revised or hidden.

Sourcetype load_error = private {
  1. uri : Uri.t;
  2. msg : msg;
}
Sourcetype connection_error = private {
  1. uri : Uri.t;
  2. msg : msg;
}
Sourcetype query_error = private {
  1. uri : Uri.t;
  2. query : string;
  3. msg : msg;
}
Sourcetype coding_error = private {
  1. uri : Uri.t;
  2. typ : Caqti_type.any;
  3. msg : msg;
}

Documented Constructors

Errors during Driver Loading

Sourceval load_rejected : uri:Uri.t -> msg -> [> `Load_rejected of load_error ]

load_rejected ~uri msg indicates that a driver could not be identified from uri.

Sourceval load_failed : uri:Uri.t -> msg -> [> `Load_failed of load_error ]

load_failed ~uri msg indicates that a driver for uri could not be loaded.

Errors during Connect

Sourceval connect_rejected : uri:Uri.t -> msg -> [> `Connect_rejected of connection_error ]

connect_rejected ~uri msg indicates that the driver rejected the URI.

Sourceval connect_failed : uri:Uri.t -> msg -> [> `Connect_failed of connection_error ]

connect_failed ~uri msg indicates that the driver failed to establish a connection to the database.

Errors during Call

Sourceval encode_missing : uri:Uri.t -> field_type:'a Caqti_type.Field.t -> unit -> [> `Encode_rejected of coding_error ]

encode_missing ~uri ~field_type () indicates that the driver does not support field_type and no fallback encoding is available for the type.

Sourceval encode_rejected : uri:Uri.t -> typ:'a Caqti_type.t -> msg -> [> `Encode_rejected of coding_error ]

encode_rejected ~uri ~typ msg indicates that encoding a value to typ failed, e.g. due to being out of range.

Sourceval encode_failed : uri:Uri.t -> typ:'a Caqti_type.t -> msg -> [> `Encode_failed of coding_error ]

encode_failed ~uri ~typ msg indicates that a parameter of type typ was not accepted by the database client library.

Sourceval request_failed : uri:Uri.t -> query:string -> msg -> [> `Request_failed of query_error ]

request_failed ~uri ~query msg indicates that the request could not be transmitted to the database, that the database was not ready to process the request, or that something went wrong while processing the request.

Errors during Result Retrieval

Sourceval decode_missing : uri:Uri.t -> field_type:'a Caqti_type.Field.t -> unit -> [> `Decode_rejected of coding_error ]

decode_missing ~uri ~field_type () indicates that the driver does not support field_type for decoding result rows.

Sourceval decode_rejected : uri:Uri.t -> typ:'a Caqti_type.t -> msg -> [> `Decode_rejected of coding_error ]

decode_rejected ~uri ~typ msg indicates that the driver could not decode a field of type typ from the returned row, e.g. due to an invalid value or limited range of the target type.

Sourceval response_failed : uri:Uri.t -> query:string -> msg -> [> `Response_failed of query_error ]

response_failed ~uri ~query msg indicates that something when wrong while fetching a delayed part of the response.

Sourceval response_rejected : uri:Uri.t -> query:string -> msg -> [> `Response_rejected of query_error ]

response_rejected ~uri ~query msg indicates that the response from the database was rejected due to requirements posed by client code.

Specific Error Types

Sourcetype call = [
  1. | `Encode_rejected of coding_error
  2. | `Encode_failed of coding_error
  3. | `Request_failed of query_error
  4. | `Response_rejected of query_error
]
Sourcetype retrieve = [
  1. | `Decode_rejected of coding_error
  2. | `Request_failed of query_error
  3. | `Response_failed of query_error
  4. | `Response_rejected of query_error
]

Errors which may occur during retrival of result rows. This includes `Request_failed since the request is fused with retrieval for the pgx driver.

Sourcetype call_or_retrieve = [
  1. | call
  2. | retrieve
]
Sourcetype transact = [
  1. | call
  2. | retrieve
]
Sourcetype load = [
  1. | `Load_rejected of load_error
  2. | `Load_failed of load_error
]
Sourcetype connect = [
  1. | `Connect_rejected of connection_error
  2. | `Connect_failed of connection_error
  3. | `Post_connect of call_or_retrieve
]
Sourcetype load_or_connect = [
  1. | load
  2. | connect
]

Generic Error Type and Functions

Sourcetype t = [
  1. | load
  2. | connect
  3. | call
  4. | retrieve
]

The full union of errors used by Caqti.

Sourceval uri : [< t ] -> Uri.t

uri error is the URI of the connection used where error occurred.

Sourceval pp : Format.formatter -> [< t ] -> unit

pp ppf error prints an explanation of error on ppf.

Sourceval show : [< t ] -> string

show error is an explanation of error.

Sourceval cause : [< `Request_failed of query_error | `Response_failed of query_error ] -> cause

A matchable representation of the cause of the error, if available.

Sourcetype counit = |

An uninhabited type used by uncongested.

Sourceval uncongested : ('a, [< t | `Congested of counit ]) result -> ('a, [> t ]) result

uncongested r eliminates an unused `Congested case from the error.

Sourceexception Exn of t

Exn error can be used when an exception is preferred over explicit error handling. The core Caqti API never raises exceptions which originate from runtime errors.

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