Backup

Mount the backup service and its admin routes.

Route prefix for the backup management endpoints.

Filesystem directory where snapshot files are written. Mount a persistent volume here in production.

Snapshot serialization format. JSON keeps backups portable and human-inspectable.

How many snapshots to keep. Older ones are pruned once the limit is exceeded.

Whether the restore endpoint is permitted to run. When false, restore attempts are rejected with 403 even for authenticated admins — a deliberate guard for production.

Tables omitted from snapshots — high-churn operational logs that would bloat backups and aren't business data.

Opt-in AES-256-GCM encryption at rest. The value is treated as an env var NAME — the plugin resolves process.env[encryptionKey] and falls back to the literal string if that var is unset. When set, new backups are written encrypted (MAGIC | IV | authTag | ciphertext); legacy plaintext backups still restore (auto-detected), and a wrong/missing key or tampered file fails closed. Note: the download endpoint streams the file verbatim as UTF-8, so encrypted backups are only consumable via the in-process restore path — leave this unset if you need portable downloadable JSON.

Cron-driven automatic backups.

createBackup writes {schema}_{timestamp}.json to storagePath: a manifest (version, schema, per-table row counts + columns, totalRows) and the data (every included table's rows). Tables are discovered from the live schema, minus excludeTables — so in multi-tenant mode you can snapshot a specific tenant schema.

Both POST /admin/backup and POST /admin/backup/:id/restore accept an optional JSON body field `schema` (string) that targets a specific tenant in multi-tenant mode: when present it is resolved via the tenant registry (getSchemaContext), and an unknown schema is rejected with 404 { message: `Schema not found: <schema>` }; the resolved tenant's tables are then backed up / restored. Omit the field to target the service's default schema (the plugin's configured schemaName). Requires a tenant registry — without multi-tenancy the field is effectively ignored.

Every run inserts a log row that moves running → completed | failed (and later → restored), recording size, table/row counts, trigger (manual | scheduled | pre_restore), who ran it and the cron used. listBackups reads the latest 100; downloads stream the file by id.

Restore refuses unless allowRestore is true and the source backup is completed. It first takes an automatic pre_restore snapshot, then runs the whole restore inside ONE db.transaction (SET CONSTRAINTS ALL DEFERRED): per table it DELETEs all rows and re-INSERTs the file's rows in chunks of 500, and any mid-restore failure rolls everything back — so you never end up with a half-restored database, and the pre_restore snapshot makes even a successful restore reversible. One exception: a table that had zero rows in the snapshot is skipped entirely (the empty-rows check short-circuits before the DELETE), so it is NOT cleared — any rows added to that table since the backup are retained rather than wiped. A successful restore is additionally recorded in the audit_logs table via logger.audit (operation RESTORE, entityName backup_logs, capturing the acting user, the source backup id, the IP from x-forwarded-for and the user-agent) — a distinct side effect from the backup_logs status flip to 'restored', and emitted only after the restore succeeds.

After every backup enforceMaxBackups counts and prunes only COMPLETED backups beyond the newest maxBackups — its query filters backup_logs to status='completed', so restored (a restore flips the source backup's status to 'restored') and any other non-completed backups are excluded from both the count and the pruning, and can accumulate past maxBackups via this path. The scheduled run additionally calls cleanupExpiredBackups, which ignores status and drops anything older than retentionDays — that is what eventually removes those restored/non-completed backups. Both delete the file and its log row together.