Caqti_connection_sig.S
Full connection signature available to users.
val driver_info : Caqti_driver_info.t
Information about the driver providing this connection module.
val driver_connection : driver_connection option
The underlying connection object of the driver if available. The open variant constructor is defined in the driver library. This is currently only implemented for caqti-driver-sqlite3 for the purpose of defining custom functions.
include Base
val call :
f:(('b, 'm) Response.t -> ('c, 'e) Stdlib.result fiber) ->
('a, 'b, 'm) Caqti_request.t ->
'a ->
('c, [> Caqti_error.call ] as 'e) Stdlib.result fiber
call ~f request params
executes request
with parameters params
invoking f
to process the result; except the driver may postpone the request until f
attempts to retrieve the result.
One of the result retrieval functions must be called exactly once before f
returns a non-error result. If a result retrieval function is not called, it is unspecified whether the database query has been issued.
The argument of f
is only valid during the call to f
, and must not be returned or operated on by other threads.
val set_statement_timeout :
float option ->
(unit, [> Caqti_error.call ]) Stdlib.result fiber
Set or clear the timeout after which a running SQL statement will be terminated if supported by the driver. This is currently supported for MariaDB (using max_statement_time
) and PostgreSQL (using statement_timeout
) and has no effect for SQLite3.
val start : unit -> (unit, [> Caqti_error.transact ]) Stdlib.result fiber
Starts a transaction if supported by the underlying database, otherwise does nothing.
val commit : unit -> (unit, [> Caqti_error.transact ]) Stdlib.result fiber
Commits the current transaction if supported by the underlying database, otherwise does nothing.
val rollback : unit -> (unit, [> Caqti_error.transact ]) Stdlib.result fiber
Rolls back a transaction if supported by the underlying database, otherwise does nothing.
val deallocate :
('a, 'b, 'm) Caqti_request.t ->
(unit, [> Caqti_error.call ]) Stdlib.result fiber
deallocate req
deallocates the prepared query for req
if it was allocated. The request must not be oneshot.
val disconnect : unit -> unit fiber
Calling disconnect ()
closes the connection to the database and frees up related resources.
val validate : unit -> bool fiber
For internal use by pool implementations. Tries to ensure the validity of the connection and must return false
if unsuccessful.
include Convenience with type 'a fiber := 'a fiber
Each of these shortcuts combine call
with the correspondingly named retrieval function from Caqti_response_sig.S
.
val exec :
('a, unit, [< `Zero ]) Caqti_request.t ->
'a ->
(unit, [> Caqti_error.call_or_retrieve ] as 'e) Stdlib.result fiber
exec req x
performs req
with parameters x
and checks that no rows are returned. See also Caqti_response_sig.S.exec
.
val exec_with_affected_count :
('a, unit, [< `Zero ]) Caqti_request.t ->
'a ->
(int, [> Caqti_error.call_or_retrieve | `Unsupported ] as 'e) Stdlib.result
fiber
exec_with_affected_count req x
performs req
with parameters x
, checks that no rows are returned, and returns the number of affected rows.
See also Caqti_response_sig.S.exec
and Caqti_response_sig.S.affected_count
.
val find :
('a, 'b, [< `One ]) Caqti_request.t ->
'a ->
('b, [> Caqti_error.call_or_retrieve ] as 'e) Stdlib.result fiber
find req x
performs req
with parameters x
, checks that a single row is retured, and returns it.
See also Caqti_response_sig.S.find
.
val find_opt :
('a, 'b, [< `Zero | `One ]) Caqti_request.t ->
'a ->
('b option, [> Caqti_error.call_or_retrieve ] as 'e) Stdlib.result fiber
find_opt req x
performs req
with parameters x
and returns either None
if no rows are returned or Some y
if a single now y
is returned and fails otherwise.
See also Caqti_response_sig.S.find_opt
.
val fold :
('a, 'b, [< `Zero | `One | `Many ]) Caqti_request.t ->
('b -> 'c -> 'c) ->
'a ->
'c ->
('c, [> Caqti_error.call_or_retrieve ] as 'e) Stdlib.result fiber
fold req f x acc
performs req
with parameters x
and passes acc
through the composition of f y
across the result rows y
in the order of retrieval.
See also Caqti_response_sig.S.fold
.
val fold_s :
('a, 'b, [< `Zero | `One | `Many ]) Caqti_request.t ->
('b -> 'c -> ('c, 'e) Stdlib.result fiber) ->
'a ->
'c ->
('c, [> Caqti_error.call_or_retrieve ] as 'e) Stdlib.result fiber
fold_s req f x acc
performs req
with parameters x
and passes acc
through the monadic composition of f y
across the returned rows y
in the order of retrieval.
Please be aware of possible deadlocks when using resources from the callback. In particular, if the same connection pool is invoked as the one used to obtain the current connection, it will deadlock if the pool has just run out of connections. An alternative is to collect the rows first e.g. with fold
and do the nested queries after exiting.
See also Caqti_response_sig.S.fold_s
.
val iter_s :
('a, 'b, [< `Zero | `One | `Many ]) Caqti_request.t ->
('b -> (unit, 'e) Stdlib.result fiber) ->
'a ->
(unit, [> Caqti_error.call_or_retrieve ] as 'e) Stdlib.result fiber
iter_s req f x
performs req
with parameters x
and sequences calls to f y
for each result row y
in the order of retrieval.
Please see the warning in fold_s
about resource usage in the callback.
See also Caqti_response_sig.S.iter_s
.
val collect_list :
('a, 'b, [< `Zero | `One | `Many ]) Caqti_request.t ->
'a ->
('b list, [> Caqti_error.call_or_retrieve ] as 'e) Stdlib.result fiber
collect_list request x
performs a req
with parameters x
and returns a list of rows in order of retrieval. The accumulation is tail recursive but slightly less efficient than rev_collect_list
.
val rev_collect_list :
('a, 'b, [< `Zero | `One | `Many ]) Caqti_request.t ->
'a ->
('b list, [> Caqti_error.call_or_retrieve ] as 'e) Stdlib.result fiber
rev_collect_list request x
performs request
with parameters x
and returns a list of rows in the reverse order of retrieval. The accumulation is tail recursive and slighly more efficient than collect_list
.
val with_transaction :
(unit -> ('a, 'e) Stdlib.result fiber) ->
('a, [> Caqti_error.transact ] as 'e) Stdlib.result fiber
with_transaction f
wraps f
in a transaction which is committed iff f
returns Ok _
.
include Populate
with type 'a fiber := 'a fiber
and type ('a, 'err) stream := ('a, 'err) stream
val populate :
table:string ->
columns:string list ->
'a Caqti_type.t ->
('a, 'err) stream ->
(unit, [> Caqti_error.call_or_retrieve | `Congested of 'err ]) Stdlib.result
fiber
populate table columns row_type seq
inputs the contents of seq
into the database in whatever manner is most efficient as decided by the driver.