# 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**.

```shell
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:

```shell
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 itself, apart from operating system constraints. What does apply is the **[licensed event capacity](/docs/eventsourcingdb/v1.0/limits)**: 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 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.