Read-Only Mode¶

This guide explains how to enable and use the read-only mode in EventSourcingDB. In this mode, all write operations are disabled, while reads and queries continue to work as usual. This is useful for maintenance, upgrades, migrations, or any scenario where writing should be temporarily or permanently disallowed.

Enabling Read-Only Mode¶

There are two ways to activate read-only mode:

Via API call: Send a POST request to the /api/v1/put-into-read-only-mode endpoint:

curl \
  -i \
  -X POST \
  -H "authorization: Bearer <API_TOKEN>" \
  http://localhost:3000/api/v1/put-into-read-only-mode

Via command-line flag: Start EventSourcingDB with the --read-only flag:
```
./eventsourcingdb run [...] --read-only
```

Once enabled, the database will reject all write attempts. The mode cannot be disabled dynamically. To leave read-only mode, restart EventSourcingDB and do not provide the --read-only flag.

Read-Only Mode Ends With the Next Start

Read-only mode switched on via the API lasts until EventSourcingDB is next started, whether you restart it on purpose or not – for example when Kubernetes restarts its pod. Where writes must stay refused across restarts, start EventSourcingDB with the --read-only flag instead, for example in the manifest of its deployment.

What Still Works¶

In read-only mode, the following operations remain fully functional:

Reading events via the read API
Observing events via the observe API (though no new events will arrive)
Running EventQL queries

This allows you to continue processing projections, audits, and analyses without interruption.

What Is Disabled¶

The following operations are blocked while read-only mode is active:

Writing new events
Registering new schemas
Any other operation that modifies stored data

Clients attempting these operations will receive 503 Service Unavailable, with a message saying that the current operation mode conflicts with the request because the store is read-only.

Read-Only Mode After a Storage Failure¶

If EventSourcingDB fails to store a write, for example because the disk is full or failing, it puts itself into read-only mode and stays in it until it is restarted. Reads go on and see everything that was stored before the failure. The same happens if EventSourcingDB keeps failing to move stored writes into its data files – which it does in the background, retrying while it fails – until the writes waiting for that take up as much memory as it allows.

The health endpoint reports this as read-only with the status fail, and the log names the cause. Fix the cause, then restart EventSourcingDB.

The client whose write failed receives an error and cannot tell from it whether the write was stored. After the restart, read the events to find out.

Read-Only Mode While the Disk Is Almost Full¶

EventSourcingDB keeps a reserve of 1 GiB free on the file system that holds its data directory, so that a write never runs out of space halfway. Once less than that is free, it refuses writes and puts itself into read-only mode, and once at least 2 GiB are free again, it accepts writes again by itself, without a restart. It checks the free space when it starts, before it accepts the first write, and every second after that.

Clients whose writes are refused meanwhile receive 503 Service Unavailable, with a message saying that the disk is full. The health endpoint reports this as read-only with the status warn, and its check system:diskRemaining with the status fail, so the health endpoint answers with a 500. That check warns beforehand, once 80 % of the space above the reserve is used, but not before less than 100 GiB are left above it: on a disk of 100 GiB, that is at about 21 GiB free, and on a disk of 10 TiB, at about 101 GiB free.

Typical Use Cases¶

Read-only mode is helpful in a variety of operational contexts, including:

System maintenance: Prevent accidental changes during backups or inspections.
Upgrades and migrations: Freeze the system state to ensure consistency while transitioning to a new version.
Kiosk or analytics deployments: Serve data without risk of mutation in dedicated read-only environments.

Operating Safely in Read-Only Mode¶

Read-only mode provides a simple but effective safeguard when write access must be suspended. It helps protect data integrity while preserving access for consumers, dashboards, and downstream systems.

Use it to keep your system transparent and stable – even when changes are not allowed.