README.md

November 22, 2023 ยท View on GitHub

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
    }
  • 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