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.

If the backup cannot be completed – say part of the store cannot be read – the stream ends with an error line instead:

{"type":"error","payload":"..."}

If the database shuts down while the backup runs, the line says database is shutting down: try again later; run the backup again once it is back.

The status code is already 200 by the time the first line goes out, so the last line is what tells you whether the backup is complete. Treat a backup that ends with an error line as incomplete, and do not keep it as your backup.

The backup can be run while the database is in normal operation or in read-only mode. Writes go on while the backup runs. The backup holds the state at its start – the events written and the schemas registered up to then – and leaves out whatever is written after it began.

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, and any restart exits it, including one you did not plan, such as Kubernetes restarting the pod. To keep the old instance read-only for the whole migration, start it with the --read-only flag instead.

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.

When a Restore Fails

If a restore fails, for example because the backup is invalid, exceeds the licensed capacity, or EventSourcingDB shuts down meanwhile, EventSourcingDB removes what it has restored so far, so that the database is empty again and the restore can be retried.

If removing it fails as well, EventSourcingDB refuses reads and writes. The health endpoint reports this as locked with the status fail, and the log names the cause. If EventSourcingDB stops without shutting down gracefully while a restore is running, for example because it is killed or the machine loses power, it refuses to start on the data directory afterwards. In both cases, empty the data directory, start EventSourcingDB, and restore the backup again.

Compatibility

There are no hard limits on the size of the backup file itself, apart from operating system constraints. What does apply is the licensed event capacity: a restore whose backup holds more events than the license permits is rejected. 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, HTTP status codes, and the last line of each backup
  • 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.