Modeling
SynthEvents
Remembering
EventSourcingDB
Building
ArchitectureKit
Version
1.3 · latest1.21.11.0
Docs / EventSourcingDB 1.0 / Operations / Read-Only Mode

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:

  • Changed in 1.3Via 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:

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

Changed in 1.3Broken in 1.0, fixed in 1.3Clients attempting to write events will receive 503 Service Unavailable, with the message the current operation mode conflicts with the given request: writing is not permitted at this time. The other operations are not refused this way: registering an event schema fails with 500 Internal Server Error, and restoring a backup is not refused at all, but writes into the database anyway.

Read-Only Mode While the Disk Is Almost FullChanged in 1.3#

EventSourcingDB keeps a reserve of 1 GiB free on the file system that holds its data directory. Once less than that is free, it refuses writes and puts itself into read-only mode, and once at least 1 GiB is free again, it accepts writes again by itself, without a restart. It checks the free space every 30 seconds.

Clients whose writes are refused meanwhile receive 503 Service Unavailable, as in read-only mode. The health endpoint reports this in its check system:diskRemaining with the status warn.

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.