package caqti-mirage
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=483a535f41e2641917fc1832ce4ad15ffc3f4e8283b1b3018a2617349583090a
sha512=6a1222c0c55cb16a9d409980f9f2400340689b87e21aafed2d7459fd7feaeb109c2dfaf77f55f8422fbb7d3772342565ced7fed78a7b77af5aedab5bfd5ae882
Description
Published: 20 Feb 2024
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.
RDBMS | URI scheme | library | Unix | MirageOS |
---|---|---|---|---|
MariaDB | mariadb:// |
mariadb | yes | no |
PostgreSQL | postgresql:// |
postgresql | yes | no |
PostgreSQL | pgx:// |
pgx (p) | yes | yes |
SQLite3 | sqlite3:// |
sqlite3 | yes | no |
The PGX based driver is not production-ready yet due to the lack of TLS, esp. given that the only supported authentication mechanism is plaintext.
If you link against caqti-dynload
, then drivers are loaded dynamically based on the URI. If dynamic loading is unavailable on your platform, link instead against the caqti-driver-*
libraries which you expect to use.
Documentation
Tutorials and examples:
The caqti-study repository is a tutorial with examples, which we will keep up to date with the latest release of Caqti. It is work in progress; suggestions and contributions are welcome.
Interfacing OCaml and PostgreSQL with Caqti by Bobby Priambodo gives a gentle introduction, though the Caqti API has changed to some extend since it was written.
The documented example in this repository can give a first idea.
API documentation from ocaml.org contains documentation for matching releases of individual packages:
caqti-eio (pending release)
caqti-mirage (pending release)
caqti-driver-pgx (pending release)
If the above lacks links to modules, it may be due to build issues. You may instead refer to my own latest rendering:
Caqti API Reference contains the index with the most important entry points being:
caqti-blocking for Unix system library with no concurrency, supports all drivers
caqti-lwt.unix for Lwt with Unix system library, supports all drivers
caqti-async for Async with Unix system library, supports all drivers
caqti-eio.unix for experimental Eio support.
caqti-mirage for experimental MirageOS support.
The linked modules 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.
You can also build the API reference matching your installed version using odig or run dune build @doc
in a Git checkout.
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_unix.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.(t2 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 queries, simplifying type specifications.
Sponsor
Thanks to the OCaml Software Foundation for economic support to the development of Caqti.Dependencies (18)
- tcpip
-
tls-mirage
< "1.0.0"
-
tls
< "1.0.0"
- ocaml
- mirage-time
-
mirage-random
< "4.0.0"
- mirage-clock
- mirage-channel
-
lwt
>= "5.3.0"
- logs
- ipaddr
-
dune
>= "3.9"
- domain-name
-
dns-client-mirage
>= "7.0.0"
-
dns-client
>= "7.0.0"
-
caqti-tls
>= "2.1.0" & < "2.2.0~"
-
caqti-lwt
>= "2.1.0" & < "2.2.0~"
-
caqti
>= "2.1.0" & < "2.2.0~"
Dev Dependencies (1)
-
odoc
with-doc
Used by
None
Conflicts
None