package caqti-driver-postgresql
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=e1f580848faf3a54f23174067f2c75f77f6a2fe50ca8bc923428d0e1841192c5
sha512=7a11edfcfbbe4855347b066e222cf6bf46d1afedcd4978661b9a2b3931921faa1768a6bc24031fd3afa84537fe2adc8b139399deb77120461bee8fb394d68e82
Description
Published: 08 Sep 2022
README
README.md
Synopsis
Caqti provides a monadic cooperative-threaded OCaml connector API for relational databases.
The purpose of Caqti is further to help make applications independent of a particular database system. This is achieved by defining a common signature, which is implemented by the database drivers. Connection parameters are specified as an URI, which is typically provided at run-time. Caqti then loads a driver which can handle the URI, and provides a first-class module which implements the driver API and additional convenience functionality.
Caqti does not make assumptions about the structure of the query language, and only provides the type information needed at the edges of communication between the OCaml code and the database; i.e. for encoding parameters and decoding returned tuples. It is hoped that this agnostic choice makes it a suitable target for higher level interfaces and code generators.
Drivers
The following drivers are available.
MariaDB (
mariadb://
)Implemented in terms of ocaml-mariadb using asynchronous calls.
Supports transactions.
Pools connections and caches statements.
PostgreSQL (
postgresql://
)Implemented in terms of postgresql-ocaml using asynchronous calls.
Supports transactions.
Pools connections and caches statements.
SQLite3 (
sqlite3://
)Implemented in terms of sqlite3-ocaml using preemptive threading for non-blocking operation.
Supports transactions.
Does not pool connections but caches statements.
If you link against caqti-dynload
, then drivers are loaded dynamically based on the URI. If dynamic loading is unavailable on your platform, you may instead link against the caqti-driver-*
libraries which you expect to use.
Documentation
For a gentle introduction, I recommend reading Interfacing OCaml and PostgreSQL with Caqti by Bobby Priambodo. There is also a documented example in this repository.
A recent rendering of the full API reference is available online. You can also generate the API reference matching your installed version using odig. Finally, topkg doc
builds the reference from a Git checkout using topkg-care.
As the main entry point, you would normally use either of
Caqti_lwt : Caqti_connect_sig.S with type 'a future := 'a Lwt.t
Caqti_async : Caqti_connect_sig.S with type 'a future := 'a Deferred.t
Caqti_blocking : Caqti_connect_sig.S with type 'a future = 'a
provided by caqti-lwt
, caqti-async
, and caqti.blocking
, respectively. These provide a connect functions which receives an URI, loads the appropriate driver, and returns a connection as a first-class module containing query functionality for the database.
The most important modules to know about are:
Caqti_type
andCaqti_request
for constructing prepared or one-shot queries.Caqti_lwt
,Caqti_async
, andCaqti_blocking
for connecting to the database and obtaining a first class module implementingCaqti_connection_sig.S
.Caqti_connection_sig.S
andCaqti_response_sig.S
for executing queries.
Running under utop
Dynamic linking does not work under utop. The workaround is to link against the needed database driver. E.g.
# #require "caqti-lwt";;
# #require "caqti-driver-postgresql";;
# open Lwt.Infix;;
# open Caqti_request.Infix;;
(* Create a DB handle. *)
# module Db = (val Caqti_lwt.connect (Uri.of_string "postgresql://") >>= Caqti_lwt.or_fail |> Lwt_main.run);;
module Db : Caqti_lwt.CONNECTION
(* Create a request which merely adds two parameters. *)
# let plus = Caqti_request.(Caqti_type.(tup2 int int) ->! Caqti_type.int) "SELECT ? + ?";;
val plus : (int * int, int, [< `Many | `One | `Zero > `One ]) Caqti_request.t =
<abstr>
(* Run it. *)
# Db.find plus (7, 13);;
- : (int, [> Caqti_error.call_or_retrieve ]) result = Ok 20
Related Software
ppx_rapper - a syntax extension for Caqti/PostgreSQL queries
Sponsor
Dependencies (4)
-
postgresql
>= "5.0.0"
-
dune
>= "2.0"
-
caqti
>= "1.9.0" & < "1.10.0~"
- ocaml
Used by (9)
-
dream
>= "1.0.0~alpha3"
-
petrol
>= "1.2.0"
-
sihl
>= "0.4.0"
-
sihl-cache
>= "0.4.0"
-
sihl-email
>= "0.4.0"
-
sihl-queue
>= "0.4.0"
-
sihl-storage
>= "0.4.0"
-
sihl-token
>= "0.4.0"
-
sihl-user
>= "0.4.0"
Conflicts
None