Skip to content

Upgrading EventSourcingDB

This guide explains how to upgrade EventSourcingDB to a newer version. It covers general upgrade procedures, compatibility guarantees, and best practices for safe deployments.

Overview

Upgrading EventSourcingDB is designed to be simple and safe. In most cases, you can stop the running instance and start the new version using the same data directory. There are no special migration steps unless explicitly stated in the release notes.

Upgrade Procedure

The general steps are:

  1. Stop the current EventSourcingDB process.
  2. Replace the binary or container image with the new version.
  3. Start EventSourcingDB again, using the same persistent data directory.

This process is the same whether you are running EventSourcingDB as a pre-built binary, in Docker, or in Kubernetes.

Check the Release Notes

Always review the release notes and changelog of the new version before upgrading. If any breaking changes or manual steps are required, they will be documented there.

First Start After Upgrading

A new version may convert data in the data directory once, at its first start. It starts right away and serves reads and writes meanwhile, but some requests, such as listing subjects or running EventQL queries, are answered with a 503 until the conversion is done, which can take several minutes. Registering an event schema works meanwhile, but checks all existing events even for an event type without events, which takes the longer the more events the database holds. This needs no manual steps. The health endpoint reports this as rebuilding in its check store:indexes, and as ready once the conversion is done. If the conversion fails, for example because the disk is full, it is tried again until it succeeds, and the check reports the status fail meanwhile, so the health endpoint answers with a 500.

Compatibility

EventSourcingDB aims for long-term compatibility across versions. No manual adjustment of data or configuration is usually required. Backups created with one version can be restored in newer versions, and in older versions as long as those can read everything the backup contains: a backup that contains events written by version 1.3 or later cannot be restored in an earlier version, since those versions cannot verify version 2 of the hash.

Clients that verify event hashes need an SDK that knows the version of the hash the server writes. Version 1.3 writes version 2: update such clients first, to an SDK version that supports it, and upgrade the server afterwards. A client with an older SDK reports every event written after the upgrade as tampered with.

Downgrading

EventSourcingDB does not support downgrading a data directory. Once a newer version has used a data directory, do not start an older version on it. Where an older version cannot read the data directory safely, it refuses to start.

To go back to an older version, restore a backup into it. Create the backup before upgrading, as recommended below. A backup created with the newer version can be restored in an older one only as described under Compatibility.

Downtime Considerations

Currently, EventSourcingDB operates as a single-instance service. As a result, upgrades require downtime. Zero-downtime upgrades will be supported in future releases once clustering and replication become available.

Safety Recommendations

  • Always create a backup before upgrading
  • Use version-pinned binaries or image tags
  • Verify the upgrade in a staging environment before applying it in production
  • Monitor the logs after startup for any warnings or errors

Upgrading EventSourcingDB is typically fast and reliable – and with proper preparation, it can be performed with minimal risk.