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.

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 an error response indicating that the system is in read-only mode.

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.