package caqti-dynload

  1. Overview
  2. Docs
Dynamic linking of Caqti drivers using findlib.dynload.

Install

Dune Dependency

Authors

Maintainers

Sources

caqti-0.9.0.tbz
sha256=4c84a16d983d0fed2786f536a3fa4d8fa113b8b30b4deea4a74772582d5489b2
md5=42a2e2d3b73d7fbaecc618549aad2865

Description

This library registers a dynamic linker which will be called when encoutering an unhandled database URI. It tries to load a findlib package named "caqti-driver-" where "" is the scheme of the URI, which is expected register a driver for the scheme.

This is a separate package to avoid the dependency on the findlib.dynload for architectures, like MirageOS, where dynamic linking may be unavailable. The alternative is to link drivers directly into the application.

Published: 01 Feb 2018

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.

Status

Large parts of Caqti was rewritten for 0.8 and 0.9, the latter being the first release targeted for to the official OPAM repository. The old API is still available in findlib libraries under the suffix .v1. I need to keep these for the time being, but do not use them for new code.

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 or cache 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 statically link against the caqti-driver-* libraries which you expect to use.

Documentation

As the main entry point, you would normally use either of

Caqti_lwt : Caqti_connection_sig.S with type 'a io = 'a Lwt.t
Caqti_async : Caqti_connection_sig.S with type 'a io = 'a Deferred.t

which is provided by caqti-lwt or caqti-async, 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.

A good place to start is with the documented example. The API reference is currently not online, but can be generated with topkg doc from the source code or with odig from an OPAM installation.

The most important modules to know about are:

  • Caqti_type and Caqti_request for constructing prepared or one-shot queries.

  • Caqti_lwt and Caqti_async 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.

Dependencies (6)

  1. ppx_driver
  2. ppx_optcomp >= "v0.9.0" & < "v0.11.0"
  3. ocamlfind
  4. jbuilder >= "1.0+beta7"
  5. caqti = "0.9.0"
  6. ocaml

Dev Dependencies

None

Used by

None

Conflicts

None

OCaml

Innovation. Community. Security.