Library
Module
Module type
Parameter
Class
Class type
Error descriptors.
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.
type integrity_constraint_violation = [
| `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
.
| `Not_null_violation
An insertion or update attempts to assign a NULL
value to column having a NOT NULL
constraint.
| `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
.
| `Unique_violation
An insertion or update would duplicate a key as declared by a UNIQUE
or PRIMARY KEY
constraint.
| `Check_violation
A requested change would violate a CHECK
constraint.
| `Exclusion_violation
A requested insertion or update would cause an overlap of rows according to an EXCLUDE
constraint.
| `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.
type insufficient_resources = [
| `Disk_full
The server is out of disk space.
*)| `Out_of_memory
The server is out of memory
*)| `Too_many_connections
The server does not accept establishing more connections.
*)| `Configuration_limit_exceeded
Some unspecific server limit is exceeded.
*)| `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.
type cause = [
| integrity_constraint_violation
| insufficient_resources
| `Unspecified__don't_match
]
The selection of causes of errors which have been mapped.
val show_cause : [< cause ] -> string
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 define_msg
on each constructor added to this type.
val define_msg :
pp:(Stdlib.Format.formatter -> msg -> unit) ->
?cause:(msg -> cause) ->
extension_constructor ->
unit
Mandatory registration of pretty-printer for a driver-supplied error descriptor.
val pp_msg : Stdlib.Format.formatter -> msg -> unit
pp_msg ppf msg
formats msg
on ppf
.
Note. Please consider the fields internal for now, they may still be revised or hidden.
val 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
.
val 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.
val connect_rejected :
uri:Uri.t ->
msg ->
[> `Connect_rejected of connection_error ]
connect_rejected ~uri msg
indicates that the driver rejected the URI.
val 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.
val encode_missing :
uri:Uri.t ->
field_type:'a Caqti_type.field ->
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.
val 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.
val 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.
val request_rejected :
uri:Uri.t ->
query:string ->
msg ->
[> `Request_rejected of query_error ]
request_rejected ~uri ~query msg
indicates that query
was not accepted by the database or driver.
val 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.
val decode_missing :
uri:Uri.t ->
field_type:'a Caqti_type.field ->
unit ->
[> `Decode_rejected of coding_error ]
decode_missing ~uri ~field_type ()
indicates that the driver does not support field_type
for decoding result rows.
val 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.
val 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.
val 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.
type call = [
| `Encode_rejected of coding_error
| `Encode_failed of coding_error
| `Request_rejected of query_error
@deprecated No longer used.
| `Request_failed of query_error
| `Response_rejected of query_error
]
type retrieve = [
| `Decode_rejected of coding_error
| `Response_failed of query_error
| `Response_rejected of query_error
]
type connect = [
| `Connect_rejected of connection_error
| `Connect_failed of connection_error
| `Post_connect of call_or_retrieve
]
val uri : [< t ] -> Uri.t
uri error
is the URI of the connection used where error
occurred.
val pp : Stdlib.Format.formatter -> [< t ] -> unit
pp ppf error
prints an explanation of error
on ppf
.
val show : [< t ] -> string
show error
is an explanation of error
.
val cause :
[< `Request_failed of query_error | `Response_failed of query_error ] ->
cause
A matchable representation of the cause of the error, if available.
val uncongested :
('a, [< t | `Congested of Caqti_common.counit ]) Stdlib.result ->
('a, [> t ]) Stdlib.result
uncongested r
eliminates an unused `Congested
case from the error.
exception 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.