Skip to content

Backup and Restore

This guide explains how to back up and restore EventSourcingDB using the HTTP API. It covers when and how to create backups, how to restore them, and what constraints apply.

Overview

Backups in EventSourcingDB are newline-delimited JSON files that contain both events and schemas. Snapshots are implicitly included because they are stored as regular events.

Currently, only full backups are supported. Incremental or differential backups are not yet available.

Performing a Backup

To create a backup, send a POST request to /api/v1/backup. The server responds with a stream of newline-delimited JSON representing all events and schemas in the database.

curl \
  -X POST \
  -H "Authorization: Bearer <API_TOKEN>" \
  http://localhost:3000/api/v1/backup \
  -o backup.json

By default, the backup is streamed to standard output. In the example above, the -o option redirects it to a file named backup.json.

The filename backup.json is used for demonstration purposes only — you can choose any name or storage path that fits your backup strategy.

The backup can be run while the database is in normal operation or in read-only mode. During the backup, EventSourcingDB automatically switches into read-only mode to prevent write conflicts. This temporary mode is lifted when the backup completes.

Optional Manual Read-Only Mode

If you're migrating to a new instance, you can explicitly enable read-only mode before starting the backup to ensure no writes occur after the backup completes. However, read-only mode can then only be exited via restart. Use it with care.

Restoring a Backup

To restore a backup, send the backup file as a binary payload to the /api/v1/restore endpoint:

curl \
  -i \
  -X POST \
  -H "Authorization: Bearer <API_TOKEN>" \
  --data-binary '@backup.json' \
  http://localhost:3000/api/v1/restore

The database will enter lockdown mode during the restore. In this mode, all read and write operations are disabled. Lockdown mode ensures consistency and is automatically lifted once the restore is complete.

Restore Requires an Empty Database

Restores can only be performed into an empty database. If data is already present, the restore will be rejected. This prevents accidental overwrites or conflicts.

Compatibility

There are no hard limits on the size of the backup file, apart from operating system constraints. EventSourcingDB imposes no restrictions. Backups are version-tolerant and can be restored across different versions of EventSourcingDB, assuming format compatibility is maintained.

Best Practices

  • Store backups in a secure, version-controlled location
  • Use read-only mode for zero-downtime migrations
  • Monitor backup and restore processes via logs and HTTP status codes
  • Restore only into freshly initialized databases
  • Use version-pinned builds to ensure compatibility

Backups give you confidence that your event history is safe, portable, and restorable — across environments and over time.