package caqti-tls

  1. Overview
  2. Docs
Caqti TLS support for PGX; config and caqti.unix implementation

Install

Dune Dependency

Authors

Maintainers

Sources

caqti-v2.1.2.tbz
sha256=ba4dfd5ff94376b5e003f682410b7b3b392c0bbaa0253679fe7671c2e07e895b
sha512=0416807fba620429ee4d64f3a6991238112e0e10dfba9703dced46cf332fd22135a9873007d025441228ce66fb192bf730d4bc776dd2c1a973d7604ab6e789e0

Description

This package contains the shared configuration and caqti.unix-specific implementation of TLS for the Caqti network API. This package only applies to PGX, since drivers based on bindings use their own TLS implementation (libpq, mariadb) or have no need for it (sqlite3).

The implementation for caqti-eio and caqti-lwt can be found in caqti-tls-eio and caqti-tls-lwt, respectively.

Published: 05 Sep 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 generate or analyze SQL but provides templating and uniform query parameter handling, including encoding and decoding data according to declared types. It is hoped that this agnostic choice makes it a suitable target for higher level interfaces and code generators.

The following drivers are available:

RDBMS URI scheme library Unix MirageOS
MariaDB mariadb:// mariadb yes no
PostgreSQL postgresql:// postgresql yes no
PostgreSQL pgx:// pgx yes yes
SQLite3 sqlite3:// sqlite3 yes no

The PGX based driver is experimental and only recommended for MirageOS. More about the drivers below.

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 for Stable Releases

The stable API documentation is hosted on https://ocaml.org, where you can search package by name.

A full Caqti release contains the following packages:

The connector modules provide a connect functions which receives an URI, dispatches to an appropriate driver, and returns a connection object as a first-class module, which contains query functionality for the database. The application can either link against the drivers it needs or the link against the caqti.plugin library in order to load the appropriate driver at runtime.

(A few package not mentioned include unreleased TLS packages and the semi-deprecated packages caqti-type-calendar and caqti-dynload.)

API Documentation for Development Snapshots

Apart from the above links, the GitHub pages are updated occasionally with a rendering from the master branch. 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 (4)

  1. tls >= "1.0.0"
  2. ocaml
  3. dune >= "3.9"
  4. caqti >= "2.1.0" & < "2.2.0~"

Dev Dependencies (1)

  1. odoc with-doc

Used by (1)

  1. caqti-mirage >= "2.1.1"

Conflicts

None

OCaml

Innovation. Community. Security.