talea

How to run talea on the append-log store

Run a single-node talea with no external services at all: storage is a directory of append-only log files, durability is an fsync per commit batch, and single-book write throughput is roughly 10× the Postgres backend on the same hardware. Result: one talead instance you can put real traffic on, as long as one instance is all you need.

Choose this backend when you want embedded deployment (no database to operate) with the highest single-book write throughput. Choose Postgres instead when you need multiple server instances, SQL access to the ledger, or operational tooling you already have for a database. The SQLite path remains the zero-setup default for development.

Prerequisites

Steps

  1. Initialize: create the data directory, generate an API token, write .env:

    cargo run -p talead -- init --db-url log://./talea-data

    This writes TALEA_DB_URL, TALEA_API_TOKEN, and TALEA_BIND to .env. There are no migrations to run — the store creates its layout on first open. If talea.seed.toml exists, its assets and accounts are applied idempotently. Re-running init is safe; --force regenerates the token.

  2. Serve:

    cargo run -p talead -- serve

    serve loads .env from the working directory; real environment variables take priority. The defaults to revisit for production:

    Variable Default Set it when
    TALEA_BIND 127.0.0.1:8080 Exposing beyond localhost
    TALEA_MAX_INFLIGHT 256 Tuning the shed point — this is also the practical batch-size ceiling for group commit
    TALEA_WRITE_QUEUE_DEPTH / TALEA_WRITE_BATCH_MAX 256 / 64 Hot-book write tuning
    TALEA_LOG_SNAPSHOT_EVERY 100000 Trading startup time against snapshot frequency; 0 disables snapshots (startup replays the whole log)
    TALEA_LOG_IDEM_HOT_CAP 1000000 Bounding idempotency-index memory; older keys spill to disk
    TALEA_LOG_SEGMENT_MAX 128 MiB Segment file rotation size
    TALEA_METRICS_BIND unset You want Prometheus metrics (note: the DB pool gauges read 0 — there is no pool)

  3. (Recommended) Scope tokens per service, exactly as on Postgres — the tokens file works identically on every backend. Follow step 4 of the Postgres how-to; nothing about it is backend-specific.

  4. Configure your load balancer against /health as readiness, not liveness — same rule as every backend (why).

Verification

export TALEA_TOKEN=$(grep TALEA_API_TOKEN .env | cut -d= -f2)
curl -i http://127.0.0.1:8080/health
# HTTP/1.1 200 OK
# x-talea-backend: log
cargo run -p talea-client --bin talea -- trial-balance --book demo

x-talea-backend: log confirms you’re on the store you think you’re on.

One process, one directory

The store takes an exclusive advisory lock on <dir>/LOCK for the life of the process. A second talead against the same directory fails at startup with data dir already locked. This is the design, not a limitation to work around: the write arbiter that keeps sequences gapless lives inside the process (why). The lock is released by the OS when the process exits, however it exits — a crash never leaves a stale lock.

Multi-instance deployments need a write arbiter every instance can see; that’s the database backends. See How to run on Postgres.

Backups

The data directory is the ledger. Two safe ways to copy it:

Avoid a plain cp/rsync of a live directory: files copied at different moments can disagree (a half-copied sealed segment looks like real corruption and the copy will refuse to start). If you can’t stop the process and don’t have filesystem snapshots, copy via a brief maintenance window.

Segments are never deleted by the server. Disk usage grows with ledger history — the same keep-everything policy as the SQL backends’ event tables.

Troubleshooting