Nostrfi
/Docs
Browse documentation
Owner: NostrfiLast reviewed: 2026-11-16

Backup and retention

Schema migrations

Schema changes are applied at startup by a versioned migration runner, which records each applied version in a schema_migrations table. If a migration fails, the relay stops rather than serving traffic against a half-migrated database, and retries the migration on the next start.

Migration 6 (0.3.0) deletes data. It removes every stored ephemeral event (kinds 20000–29999, mostly kind 20001 presence heartbeats) and their tag rows, because the relay no longer stores them. It runs once, on the first start of a 0.3.0 binary, and logs how many events it removed. The database file shrinks after the next checkpoint.To keep those events, back up before upgrading: with the pre-0.3.0 binary's -backup, or by copying db/relay.db while the relay is stopped. Don't take this backup with the 0.3.0 binary, because -backup applies pending migrations first.

Retention

Expired events (NIP-40) are hidden from reads immediately. A background worker deletes them on an interval and then compacts the database:

retention:
  purge_interval_seconds: 3600 # 0 disables the worker

Each sweep is logged with the number of events purged. Deletion requests (NIP-09) and replaceable-event updates remove the old event and its tag rows in one transaction.

Backup

cd backend
go run ./cmd/relay -backup /path/to/backup-dir

This exports the database with DuckDB's native export (Parquet) and writes a backup-manifest.json with the event and tag row counts. It then exits; it does not start the relay.

-backup applies any pending schema migrations before exporting, so a backup taken with a newer binary reflects that binary's migrations, including destructive ones. Administrator grants are part of the database, so they are backed up and restored with it.

Restore

cd backend
go run ./cmd/relay -restore /path/to/backup-dir

Restore imports the backup into a new database, checks the row counts against the manifest, and runs a test query. It fails loudly if either check fails. It refuses to run if the database file already exists, so it never merges with or overwrites a live database.

What you are responsible for

The relay doesn't schedule backups. Running them on a schedule, storing them off the host, rotating them, and choosing a recovery point objective belong to your deployment.

  • Recovery time is restart time plus the time -restore takes on your data. Measure it for your own database size.
  • Deleted events remain in older backups until those backups rotate.
  • Backups are not encrypted. Protect them like the live database; see trust and data.