Database.Repo

Database

A supervised connection pool for a SQL or cache store.

Pipe a backend (postgres, sqlite, ets, valkey) with host/user/password settings, put supervised under your [Supervisor], then run `database module` work with `transaction`. Tables and queries live in [Database.Table] and [Database.Rows]. See `examples/03_todo_app` for a full wire-up.

repo =
    Repo.postgres
        |> Repo.host "127.0.0.1"
        |> Repo.dbPort 5432
        |> Repo.user "selm"
        |> Repo.password "selm"
        |> Repo.dbName "todos"

-- in Server.application init:
Supervisor.new OneForOne
    |> Supervisor.add (Repo.supervised repo)

-- in a request handler:
Repo.transaction (Todos.list (Server.cookies req))

Use on "cache" when you named a second pool with Repo.name. SQL pools own migrations by default; set schemaOwner False on cache-only pools.

Types

Config

type Config = Config

Pool configuration for a SQL or cache store.

Examples

Repo.postgres
    |> Repo.host "127.0.0.1"
    |> Repo.dbName "app"

Repo

type Repo = Repo

Opaque handle for a started repository pool.

Examples

case Repo.start repo of
    Ok started ->
        -- use Repo.transaction / Repo.on against this pool
        Ok ()

    Err _ ->
        Err "repo failed to start"

Values

default

default : Config

Default repository configuration (before you pick a backend).

Examples

Repo.default
    |> Repo.poolSize 4

postgres

postgres : Config

Configure a Postgres repository.

selm_pg connects with cleartext TCP (no SSL yet). Keep Postgres on loopback, a private network, or behind a TLS-terminating sidecar. Prefer SCRAM (or trust on loopback) over cleartext password auth when the path is not local.

Examples

Repo.postgres
    |> Repo.host "127.0.0.1"
    |> Repo.dbPort 5432
    |> Repo.user "selm"
    |> Repo.password "selm"
    |> Repo.dbName "todos"

sqlite

sqlite : Config

Configure a SQLite repository (set the file with path).

Examples

Repo.sqlite
    |> Repo.path "app.sqlite"
    |> Repo.poolSize 4

ets

ets : Config

Configure an in-process ETS cache repository.

Examples

Repo.ets
    |> Repo.name "cache"
    |> Repo.schemaOwner False

valkey

valkey : Config

Configure a Valkey cache repository (Cache get/set/delete over RESP).

selm_store_valkey uses cleartext TCP (no TLS yet). Keep Valkey on loopback, a private network, or behind a TLS-terminating sidecar.

Examples

Repo.valkey
    |> Repo.host "127.0.0.1"
    |> Repo.name "cache"

poolSize

poolSize : Int -> Config -> Config

Set the connection pool size.

Examples

Repo.postgres
    |> Repo.poolSize 8

host

host : String -> Config -> Config

Set the database host.

Examples

Repo.postgres
    |> Repo.host "127.0.0.1"

dbPort

dbPort : Int -> Config -> Config

Set the database port (dbPort avoids the reserved port keyword).

Examples

Repo.postgres
    |> Repo.dbPort 5432

user

user : String -> Config -> Config

Set the database user.

Examples

Repo.postgres
    |> Repo.user "selm"

password

password : String -> Config -> Config

Set the database password.

Examples

Repo.postgres
    |> Repo.password "selm"

dbName

dbName : String -> Config -> Config

Set the database name (dbName avoids the reserved database keyword).

Examples

Repo.postgres
    |> Repo.dbName "todos"

path

path : String -> Config -> Config

Set the SQLite file path.

Examples

Repo.sqlite
    |> Repo.path "app.sqlite"

name

name : String -> Config -> Config

Register this pool under a name (default keeps selm_default_repo). Pass the same string to on when running transactions.

Examples

Repo.ets
    |> Repo.name "cache"

schemaOwner

schemaOwner : Bool -> Config -> Config

Whether this pool runs SQL migrations (SQL defaults True; cache defaults False).

Examples

Repo.ets
    |> Repo.name "cache"
    |> Repo.schemaOwner False

supervised

supervised : Config -> ChildSpecification Repo

Child specification for the repository pool. Add it with Supervisor.add in Server.application init.

Examples

Supervisor.new OneForOne
    |> Supervisor.add (Repo.supervised repo)

start

start : Config -> Result StartError (Started Repo)

Start the repository pool without a supervisor tree (tests and one-off CLI tasks). Prefer supervised in long-running servers.

Examples

case Repo.start (Repo.sqlite |> Repo.path "test.sqlite") of
    Ok _ ->
        Repo.transaction work

    Err _ ->
        Err "start failed"

transaction

transaction : Transaction a -> Result String a

Run a [Database.Transaction] on the default repo. Returns `Err` when the transaction fails or rolls back.

Examples

case Repo.transaction (Todos.getTodos (Server.cookies req)) of
    Ok rows ->
        Server.json 200 (encode rows)

    Err message ->
        Server.text 500 message

on

on : String -> Transaction a -> Result String a

Run a transaction on a named repo pool (see name).

Examples

case Repo.on "cache" (Cache.set "session" token) of
    Ok () ->
        Server.empty 204 []

    Err _ ->
        Server.empty 500 []