This repository contains OCaml examples using the Caqti library. It is meant to be checked out and used for learning.

This is currently work in progress.

NOTE: a reading order is suggested below. One of the objectives of this directed study is to take an OCaml beginner from zero to hero, to quickly get a feel of what it's like to work with a database and OCaml. More experienced may want to skip certain sections obviously.

---

What we will be building

We will learn to handle this mildly complex relationship with Caqti and PostgreSQL:

erDiagram
    AUTHOR one to one or many BIBLIOGRAPHY : ""
    AUTHOR {
        int id PK
        string first_name "NOT NULL"
        string middle_name "NULL"
        string last_name "NOT NULL"
    }
    BOOK one to one or many BIBLIOGRAPHY : ""
    BOOK {
        int id PK
        string title "NOT NULL"
        string description "NOT NULL"
        string isbn "NOT NULL UNIQUE"
        date published_on "NOT NULL"
    }
    BIBLIOGRAPHY {
        int author_id FK
        int book_id FK
    }

Loading

• an author can publish one or many books
• a book can be written by one or many authors

General overview

We will also:

• interact with the system via the utop REPL
• run a binary that will call into a lib to generate (and display) CRUD queries
• implement tests to ensure we always have a working system
• explain general OCaml-specific concepts along the way
  • the goal is to give a friendly introduction to an OCaml beginner
  • but we expect you to already be a programmer
  • we expect you to know SQL

Goals

• learn to use caqti with a single connection (no concurrency)
• learn to use caqti with lwt
• learn to use caqti with async
• learn to use caqti with eio
• learn to use the satellite project ppx_rapper, which can be interesting from the perspective of reducing boilerplate

Prerequisites

You must have a working installation of PostgreSQL.

Also, you may run the following command to install the dependencies:

# Or install packages manually, see: dev.opam
opam install . --deps-only

Database setup

As long as you have a "standard" postgreSQL installation, you should be able to easily run a local database on port 5433

• make db-init
• make db-start
• make db-create
• make db-psql
  • or just use: PGHOST=localhost PGDATABASE=caqti_study PGPORT=5433 psql

Also check these commands:

• make db-status
• make db-reset

Running all the tests

To double-check you're all set, you may want to run the project's test suite with:

PGHOST=localhost PGDATABASE=caqti_study PGPORT=5433 dune build

# We run the tests in a single thread currently, see: issues/9.
PGHOST=localhost PGDATABASE=caqti_study PGPORT=5433 dune runtest -j1

Running and adding more tests is also a good way to make improvements to this repo if you feel like contributing.

Suggested reading order

• Hello World: setup a basic OCaml project
• Hello Tests: learn how to test
• Hello Caqti (blocking)
• Hello Caqti Lwt (promises)
• Hello Caqti Async (promises, another flavor)
• Create a CLI app with Caqti/Lwt
• Hello Ppx_rapper(code-gen to reduce boilerplate)