SQLite foundation

One Trestle process owns one SQLite database at <data-dir>/trestle.db, giving transactions, ordering and backup a clear owner.

Migration authority

The _trestle_schema_migrations history table is the source of truth for the applied schema version. PRAGMA user_version is only a compatibility mirror: a valid history restores an absent mirror, but history is never reconstructed from a nonzero marker, and disagreement or damaged history fails closed instead of guessing.

Startup contract

• The data directory is created with owner-only permissions.
• Foreign keys are enabled and verified before readiness.
• A finite five-second busy timeout avoids unbounded lock waits.
• WAL mode is requested for supported local filesystems.
• A database from a newer Trestle schema version is refused.

Inspect safely

sqlite3 ./data/trestle.db "PRAGMA foreign_keys; PRAGMA journal_mode;"

Prefer the Trestle API for writes. Direct SQL can bypass validation, audit, events and job creation even when the database accepts it.

Connection ownership

The store serializes database access through one owned connection. That keeps migration and transaction behavior deterministic while the product is explicitly single-node.

Backup

Use the Backups dashboard or administrative backup API rather than copying a live database file. Trestle uses SQLite's consistent backup mechanism, records history and packages local file objects with a manifest.

Unsupported layouts

Network filesystems and multiple Trestle processes sharing one database are unsupported. Replicate backup artifacts or downstream data, not the live SQLite file.