Backup and Recovery#

Trilium automatically creates SQLite database snapshots on a daily, weekly, and monthly schedule. Each backup is a complete copy of document.db — including all note content, metadata, and the encrypted data key needed to decrypt protected notes. Backups are overwrite-based: each schedule type maintains a single file that is replaced on the next scheduled run.

Backup Files#

Backup files live in the backup/ subdirectory of the Trilium data directory. By default this is {TRILIUM_DATA_DIR}/backup/, but it can be overridden with the TRILIUM_BACKUP_DIR environment variable 1. The directory is created with 0o700 permissions on first use 2.

Files are identified by the pattern backup-*.db; in-progress SQLite journal files (e.g., *.db-journal) are explicitly excluded from the listing 3.

How Backups Are Created#

The server-side implementation is ServerBackupService which extends the abstract BackupService from @triliumnext/core.

• Schedule: The scheduler calls regularBackup() every 4 hours via setInterval, with a first run 5 minutes after startup 4. regularBackup() internally checks elapsed time against lastDailyBackupDate, lastWeeklyBackupDate, and lastMonthlyBackupDate options to decide which backup types are due 5.

• Concurrency safety: Each backup runs inside a sync mutex (syncMutexService.doExclusively) to avoid capturing an inconsistent DB state mid-sync 6.

• Mechanism: sql.copyDatabase(backupFile) performs the actual copy. This uses SQLite's online backup API via better-sqlite3, so the copy is safe to take on a live, running database.

• Manual backups: The backupNow(name) method creates backup-{name}.db on demand. The name is sanitized to [a-zA-Z0-9_-] to prevent path traversal 7.

• Per-schedule enables: Each type is independently controllable via dailyBackupEnabled, weeklyBackupEnabled, and monthlyBackupEnabled options 5.

Encryption Keys in Backups#

Backups are full database copies, so they include the encryptedDataKey, passwordVerificationHash, passwordVerificationSalt, and passwordDerivedKeySalt options. This means:

• A backup made before a password reset retains the old encrypted data key. Restoring that backup and using the original password will recover access to protected notes 8.
• Conversely, if a password is reset after a backup was taken, the new key in the live database differs from the key in old backups — you must use the password active at backup time to decrypt 8.

The anonymization tool (anonymization.ts) scrubs these fields when creating a sanitized copy for bug reports, confirming they are present in standard backups.

Migration Backups#

Before any schema migration, Trilium creates a timestamped backup (before-migration-{dateSuffix}) rather than using the static backup-{type}.db names, ensuring migration backups are never silently overwritten by a scheduled run 9.

Recovery Procedure#

To restore from a backup:

1. Stop Trilium completely.
2. Copy your chosen backup file (e.g., backup-daily.db) from {TRILIUM_DATA_DIR}/backup/ to {TRILIUM_DATA_DIR}/document.db, replacing the existing database.
3. Restart Trilium and log in using the password that was active when that backup was created 8.

Caution: Restoration reverts the entire database to the backup's point in time. Export any unprotected notes you want to keep before overwriting 8.

Backups can also be downloaded directly from the UI via Options → Backup which calls GET /api/database/backup/download?filePath=... 10. Path traversal is prevented server-side by validating the resolved path stays within BACKUP_DIR 11.

Key Source Files#