Durable storage

Generated projects use local SQLite at data/cayu.db. Use shared durable stores when independent server or worker processes must coordinate.

Select one store

Storage-aware CLI precedence is explicit --sqlite or --postgres, then CAYU_DATABASE_URL, then the typed project table, then the existing project’s exact data/cayu.db file. Resolution does not construct the application or guess another database filename.

[tool.cayu.session_store]
backend = "sqlite"
path = "data/cayu.db"

Relative paths are resolved from pyproject.toml. For PostgreSQL, install its extra and use an environment-variable name:

[tool.cayu.session_store]
backend = "postgres"
env = "CAYU_DATABASE_URL"

Keep connection credentials in secret configuration. Set CAYU_REQUIRE_POSTGRES=1 where a missing database URL must fail instead of selecting SQLite.

Apply migrations before startup

cayu storage status --json
cayu storage migrate

status is read-only: exit 0 means up to date, 3 means a forward migration passes preflight, 4 means incompatible, and 1 or 2 signals an operational or usage error. PostgreSQL application startup validates schema and does not silently run DDL.

For a populated PostgreSQL database, migrate requires an explicit supported backup authority or waiver. Inspect storage command flags before choosing one. Preserve the backup and migration receipt with the deployment.

When using transaction pooling, configure CAYU_DATABASE_DIRECT_URL for the dedicated listener and migration advisory locks. CAYU_DATABASE_POOL_MAX defaults to 5 per pool; account for the listener and separate eval-store pool as well as worker process count.

Reference: storage API and configuration.