Skip to main content

Metadata Backup Overview

In normal operation, RustMailer persists all metadata in native_db instances. For performance reasons, metadata is split across three separate native_db instances, each stored as a single file under the directory specified by RUSTMAILER_ROOT_DIR. The three files are:

  • meta.db: Stores core metadata, including account information, OAuth tokens, email templates, webhook configurations, and other critical metadata.
  • tasks.db: Contains scheduling and task-related data, such as task status and execution history.
  • envelope.db: Stores all email metadata caches for accounts, along with related indexing data.

This separation ensures that frequently accessed metadata can be managed efficiently without impacting overall performance.

Why Backup Metadata?​

The primary reason to back up metadata is to prevent loss of critical data. Current RustMailer backup implementation focuses on meta.db, while tasks.db and envelope.db are not backed up automatically.
If RUSTMAILER_BACKUP_DIR is not specified, the backup process will not be enabled.

Implications of this design:

  • meta.db backup ensures that core cluster data remains safe in case of failure.
  • tasks.db and envelope.db are not backed up, so incomplete tasks and historical task data may be lost.
  • Cached email metadata in envelope.db can be rebuilt automatically via a full re-sync, minimizing long-term disruption.

This approach balances backup cost and critical data protection while allowing automatic recovery of non-critical information.

Backup Implementation​

RustMailer employs a background task that runs once every 24 hours. Each execution:

  1. Creates a snapshot of current metadata (meta.db only; tasks.db and envelope.db are not included).
  2. Stores the snapshot in the directory specified by RUSTMAILER_BACKUP_DIR

The backup file is named in the format {YYYYMMDD_HHMMSS}_meta.db, for example: 20250814_193045_meta.db.

The maximum number of backup files to retain is configurable via the RUSTMAILER_MAX_BACKUPS parameter. Older backups beyond this limit are automatically deleted to conserve storage.

This system ensures that critical metadata is safely preserved while allowing non-critical caches and tasks to be reconstructed if needed.

tip

This approach balances backup cost and critical data protection while allowing automatic recovery of non-critical information. This is the current implementation; future versions may, based on user feedback, add configuration options to control the backup scope and interval.