Backups and upgrades

Everything meilisearch-cdc knows lives in its data directory. Back up cdc.db and the encryption key together, and you can rebuild the installation anywhere.

What to back up

Item	Where	Contains
`cdc.db`	`$CDC_DATA_DIR/cdc.db`	Tasks, connectors, destinations, checkpoints, task statuses, dead letters, diff reports, users, sessions, invitations, alert rules and history, MCP tokens and policy, SMTP and Telegram settings, the audit log. Credentials inside it are encrypted.
The encryption key	`$CDC_DATA_DIR/secret.key`, or wherever `CDC_SECRET_KEY` / `CDC_SECRET_KEY_FILE` comes from	The key that decrypts connector passwords, DynamoDB secret keys, Meilisearch API keys, the SMTP password and the Telegram bot token.
Your configuration	Environment file, unit file, Compose file, tasks file	How the service is started.

The task activity log is kept in memory only and is not part of a backup. The documents themselves live in Meilisearch; back them up there (dumps and snapshots can be requested from the destination's Backups tab).

Without the key, credentials are lost

A backup of cdc.db without its key still restores tasks, users and history, but every stored secret fails to decrypt (cannot decrypt secret: wrong key or the value belongs to another record) and must be entered again. Store the key separately from the database backup, for example in your secret manager.

Taking a backup

The database is a single bbolt file that the running service keeps open. The simplest consistent backup is a cold copy:

sudo systemctl stop meilisearch-cdc
sudo tar -C /var/lib -czf /backup/meilisearch-cdc-$(date +%F).tar.gz meilisearch-cdc
sudo systemctl start meilisearch-cdc

Stopping is safe: tasks drain and save their checkpoint, and resume where they stopped. Changes made in the source meanwhile stay in the source's log (replication slot, binlog, change stream…) as long as its retention allows. With Docker, stop the container and archive the volume:

docker stop cdc
docker run --rm -v cdc-data:/data -v "$PWD":/backup alpine \
  tar -C /data -czf /backup/cdc-data-$(date +%F).tar.gz .
docker start cdc

If you take filesystem or volume snapshots instead (LVM, ZFS, EBS, Kubernetes VolumeSnapshots), make them crash-consistent: bbolt is designed to survive a crash, so an atomic snapshot of the whole volume is a valid backup. Copying the file with cp while the service writes to it is not.

Restoring

Stop the service and replace the data directory with the backup (owner and mode as before: the service user, 0700).
Provide the same key: the restored secret.key, or the same CDC_SECRET_KEY.
Start the service. Tasks whose desired state is running start again from their checkpoints.

A restored checkpoint may point to a source position that no longer exists (the binlog was purged, the replication slot was dropped, the stream was trimmed). The task then logs source position lost and runs a full resync automatically. If you restore onto a different source database, use Reset checkpoint on the affected tasks so they snapshot again.

Upgrading

Read the release notes of every version you skip (Changelog and upgrade notes).
Take a backup as above.
Replace the binary (or change the image tag) and restart. On start the service opens the existing database, re-encrypts any secret still stored with an older key or format, and resumes tasks from their checkpoints.
Reload the dashboard. Installed apps pick up the new version through the service worker and offer Reload (see updates).

# Binary
sudo install -m 0755 meilisearch-cdc_1.2.4_linux_amd64/meilisearch-cdc /usr/local/bin/meilisearch-cdc
sudo systemctl restart meilisearch-cdc

# Docker
docker pull ghcr.io/ja7ad/meilisearch-cdc:1.2.4
docker rm -f cdc && docker run -d --name cdc -p 127.0.0.1:8080:8080 -v cdc-data:/data ghcr.io/ja7ad/meilisearch-cdc:1.2.4

To roll back, stop the service and restore the backup taken before the upgrade together with the older binary.

Starting over

To wipe the stored data but keep the installation (and its key), use meilisearch-cdc admin purge all; see Admin CLI. Purging does not touch Meilisearch indexes unless you purge tasks with --indexes, and does not drop replication slots in your databases.