caqti-driver-mariadb

MariaDB driver for Caqti using C bindings
README

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 preemtive 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 and Caqti_request for constructing prepared or one-shot
    queries.

  • Caqti_lwt, Caqti_async, and Caqti_blocking for connecting to the
    database and obtaining a first class module implementing
    Caqti_connection_sig.S.

  • Caqti_connection_sig.S and Caqti_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;;

(* 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.find 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

Install
Sources
caqti-v1.8.0.tbz
sha256=2630233f335f910290e24b318ac7f6e712b3109fb55581b2b8c324127a9a4b12
sha512=9ce23cbc02b9d6c856a8db0713dbb1aa393aa43bc1d565121420636f7f6fa1ed64c7269e98cfeb92b5e9c8e23e42e2e8e1705b5fe978abd3c3f0cc3259d32b98
Dependencies
odoc
with-doc
mariadb
>= "1.1.1"
dune
>= "2.0"
cmdliner
with-test & >= "1.1.0"
caqti
>= "1.8.0" & < "1.9.0~"
alcotest
with-test & >= "1.5.0"
Reverse Dependencies
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"