package caqti

Signature of connection handles.

You can obtain a connection handle from Caqti_lwt or Caqti_async, which both implement the Caqti_connect_sig interface.

While Caqti_request.t objects 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. That is, the request does not detail how to fold over rows, and for this reason, the separation into request constructors and executors entails a collection of pairwise compatible convenience functions across multiplicities between the APIs. E.g. when there are like-named Caqti_request.find_opt and S.find_opt functions, the first declares the row multiplicity, while the latter implements a way to fold rows into an OCaml datatype for that multiplicity.

Though a request object stipulates the expected multiplicity, there is still choice left for how to fold rows. E.g., a request constructed by Caqti_request.collect, or in fact any request, can be processed with S.fold, S.fold_s, S.iter_s, or S.collect_list. The two functions Caqti_request.create and S.fold can construct and process any supported SQL query.