Skip to main content
tavrn Docs

Database

PostgreSQL holds everything except the uploaded files and the keys; SQLite is only for development.

  • PostgreSQL is the production database: the compose service db (postgres:17-alpine, data in ./pgdata) or an external server or managed service via TAVRN_DATABASE_URL (postgres://user:password@host:port/db; remove the db service then). SQLite is refused outside --dev.
  • Connections: every instance opens a pool of up to 16 connections and keeps at least 2 of them open while idle (see Performance). With several instances set max_connections to at least 16 × instances + 10, or put PgBouncer in session mode in between.
  • Migrations are built into the binary and run automatically at every start (with several instances under a startup lease, one instance after the other). They only go forward: the node refuses to start against a database whose schema is newer than the binary (database migration failed (schema newer than the binary? …)), so a downgrade means restoring a backup (Upgrade and rollback).
  • Backups: pg_dump together with the data volume, see Keys and backups.
  • Major PostgreSQL upgrades (e.g. 17 → 18) are not done by the node: dump with pg_dump, start the new PostgreSQL version on an empty data directory, restore, then start the node. Do not just change the image tag of the db service on an existing ./pgdata.
  • The node cleans up after itself through the hourly housekeeping (handshake log, federation state, orphaned files, message and attachment retention, stale devices, remote users, legal retention, …); no database maintenance besides PostgreSQL’s own autovacuum is needed.

This page is generated from tavrn-node/docs/HANDBOOK.md (AGPL-3.0-only) when the website is built; its links were adapted for this site.