Module Caqti_connection_sigSource

Signature of connection handles.

The main signature S of this module represents a database connection handle. This is obtained by connection functions implemented in the subpackages caqti-async, caqti-eio, caqti-lwt, and caqti-mirage.

While values of Caqti_request.t hold SQL code to be sent to the database, connection handles defined here provide the means to execute them with actual parameters on an RDBMS. So, there is a separation between preparation and execution. This is motivated by the common support for prepared queries in database client libraries, and by the desire to keep the possibly deeply nested data-processing code uncluttered by strings of SQL code. For this separation to be reasonably safe, the request declares the types of parameters and result, and these type declarations are placed right next to the SQL code, so that we can rely on OCaml's powers of refactoring large code bases safely.

The result type of Caqti_request.t only describes how to decode individual rows, leaving the decision of how to process multiple rows to the execution interface. Therefore, for each request constructor from Caqti_request.Infix, there are one or more matching retrieval functions in the present signature.