package caqti-async

  1. Overview
  2. Docs
Async support for Caqti

Install

Dune Dependency

Authors

Maintainers

Sources

caqti-v2.0.1.tbz
sha256=7eb57225c521fe25395653d960b1c381bb2b2ccae47bc2a827bb16611988da8b
sha512=eeafaf495b08fb8620ddee1711b8f9fa2ca0c79fb450a905c8d071806b7046d665e1e2ac0e7d3c7ca1258455decbf184e689e9ecb2453ec9d952b864f9dd14f4

Description

Published: 22 Aug 2023

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:

API documentation from ocaml.org contains documentation for matching releases of individual packages:

If the above lacks links to modules, it may be due to build issues. You may instead refer to my own latest rendering:

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

OCSF logo Thanks to the OCaml Software Foundation for economic support to the development of Caqti.

Dependencies (8)

  1. ocaml
  2. dune >= "2.5"
  3. core_unix
  4. core
  5. conduit-async >= "1.5.0"
  6. caqti >= "2.0.0" & < "2.1.0~"
  7. async_unix >= "v0.11.0"
  8. async_kernel >= "v0.11.0"

Dev Dependencies (6)

  1. odoc with-doc
  2. cmdliner with-test & >= "1.1.0"
  3. caqti-driver-sqlite3 with-test & >= "2.0.0" & < "3.0.0~"
  4. caqti-dynload with-test & >= "2.0.0" & < "3.0.0~"
  5. alcotest-async with-test & >= "1.5.0"
  6. alcotest with-test & >= "1.5.0"

Used by (1)

  1. ppx_rapper_async

Conflicts

None

OCaml

Innovation. Community. Security.