Upgrade guide

Should you upgrade?

KurrentDB 26.0 is a long term support (LTS) release and will be supported for a minimum of two years, with a two month grace period for organizing upgrades when the LTS goes out of support. See the release schedule for further information.

Upgrade to this version if you want to try the new features and changes in this release. Also please note that with this release 23.10 LTS and 25.1 STS are going out of support. Consider upgrading to a supported version (24.10 or 26.0) if you are on either of these versions.

General changes, features and fixes are described in the what's new and release notes.

Upgrade procedure

You can perform an online rolling upgrade directly to KurrentDB 25.1 from these earlier versions:

• 25.1
• 25.0
• 24.10
• 23.10
• 22.10

Follow the upgrade procedure below on each node, starting with a follower node:

1. Stop the node.
2. Uninstall any previous versions of EventStoreDB.
3. Install the new version and update the configuration. If you use licensed features, ensure that you configure a license key.
4. Start the node.
5. Wait for the node to become a follower or read-only replica.
6. Repeat the process for the next node.

Upgrading the cluster this way keeps the cluster online and able to service requests. There may still be disruptions to your services during the upgrade, namely:

• Client connections may be disconnected when nodes go offline or elections occur.
• The cluster is less fault-tolerant while a node is offline for an upgrade because the cluster requires a quorum of nodes to be online to service write requests.
• Replicating large amounts of data to a node can have a performance impact on the Leader in the cluster.

::: warning If you modified the Linux service file to increase the open files limit, those changes will be overridden during the upgrade. You will need to reapply them after the upgrade. :::

To 26.0.0

Breaking Changes

• The primary yaml config file now takes precedence over the json files (logconfig.json, kestrelsettings.json, metricsconfig.json and any custom json in the configuration directory).
• Queue busyness (proportion of time a queue is processing messages) has been removed as a metric and stat. It is more informative to look at the queue length - amount of time a message is waiting in the queue before being processed.

Deprecation Notices

• WorkerThreads option is deprecated and no longer has any effect.

To 25.1

Upgrade Notices

• Consider if the new StreamInfoCacheCapacity default is appropriate for your workload.
• Consider whether to leave SecondaryIndexing:Enabled at its default of true. Leaving it enabled will cause increased IO activity on all nodes while the secondary indexes are built. Note that secondary indexes are not compatible with online file-copy backup, please use volume snapshot instead.

Breaking Changes

Unix socket rename (PR #4951)

As part of the rebrand, the unix socket file has been renamed from eventstore.sock to kurrent.sock.

This only affects users of the redactor tool, who will need to download the latest version.

DisableFirstLevelHttpAuthorization option removed (PR #5237)

This option has had no effect since v20.6.0 and has been removed from the server. Remove this option if it is present in your configuration.

Deprecation Notices

MemDb (PR #5274)

The MemDb option has been deprecated and will be removed in a future version to allow us to simplify and unify some core code paths. Users wishing to continue to run KurrentDB in memory can do so with ramfs or similar. Please reach out to us if this is problematic for your use case.

To 25.0

Event Store – the company and the product – have rebranded as Kurrent.

As part of this rebrand, EventStoreDB has been renamed to KurrentDB, with the first release of KurrentDB being version 25.0.

Read more about the rebrand in the rebrand FAQ.

Breaking changes

File and location changes when upgrading from EventStoreDB

You will need to take the following changes into account when upgrading from EventStoreDB:

On Windows

1. The executable EventStore.ClusterNode.exe has been renamed to KurrentDB.exe.
2. The test client executable EventStore.TestClient.exe has been renamed to KurrentDB.TestClient.exe.

On Linux

1. The eventstore service has been renamed to kurrentdb.
2. The eventstored executable has been renamed to kurrentd.
3. The eventstore user has been renamed to kurrent.
4. The default locations have changed from eventstore to kurrentdb:

If the following EventStore locations exist and the KurrentDB locations do not, KurrentDB will use the EventStore locations instead:

• The default config file /etc/kurrentdb/kurrentdb.conf -> /etc/eventstore/eventstore.conf
• The default data directory /var/lib/kurrentdb/ -> /var/lib/eventstore/
• The default log directory /var/log/kurrentdb/ -> /var/log/eventstore/

If you install KurrentDB through a package manager, it will create a default configuration file at /etc/kurrentdb/kurrentdb.conf for you and therefore won't fall back to the EventStore config file. You will need to copy any configuration over from eventstore.conf to kurrentdb.conf.

::: warning If you are running KurrentDB as a service, you will need to grant the kurrent user access to any data, logs, or configuration directories that the eventstore user had access to. :::

Log Levels supported in logconfig.json

The log levels specified in logconfig.json must now be Microsoft levels rather than Serilog levels.

If you have customized your logconfig.json you will need to change Fatal to Critical and Verbose to Trace. #4837

Metrics name changes

::: info The old EventStore metric names can still be used by changing the two meter names in metricsconfig.json to have EventStore prefixes:

  "Meters": [
-    "KurrentDB.Core",
-    "KurrentDB.Projections.Core"
+    "EventStore.Core",
+    "EventStore.Projections.Core"
  ],

However, this functionality will eventually be removed in a future release.

If you are using the Open Telemetry Collector, you may also need to set add_metric_suffixes to false in its configuration file:

exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"
    add_metric_suffixes: false

:::

All of the eventstore prefixes have been changed to kurrentdb

The following metric names have had _total appended to the end when exposed in Prometheus format on the /metrics endpoint to match the spec:

The following metric names have changed generally

Removed configuration options

A number of configuration options have been removed in 25.0. KurrentDB will not start by default if any of these options are present in the database configuration.

The following options were renamed in EventStoreDB version 23.10. KurrentDB will no longer start if the deprecated option is present in the database configuration:

The following deprecated options were removed as they had no effect:

• AlwaysKeepScavenged
• GossipOnSingleNode
• DisableInternalTcpTls
• OptimizeIndexMerge

New OAuth redirect uri

The new embedded web UI requires a new redirect uri in order to work with the OAuth plugin.

If you use the OAuth plugin and the web UI, you will need to allow the /signin-oidc redirect uri in your identity server configuration in addition to the /oauth/callback uri.

For example, if you had the following redirect uris configured in your identity server:

"RedirectUris": [
  "https://localhost:2113/oauth/callback",
  "https://127.0.0.1:2113/oauth/callback"
]

Then you would need to update it to this:

"RedirectUris": [
  "https://localhost:2113/signin-oidc",
  "https://127.0.0.1:2113/signin-oidc",
  "https://localhost:2113/oauth/callback",
  "https://127.0.0.1:2113/oauth/callback"
]

Deprecation Notices

Configuration sections and prefixes

The EventStore configuration section and configuration root has been renamed to KurrentDB.

The EVENTSTORE_ environment variable prefix has been changed to KURRENTDB_

Custom HTTP content types

The vnd.eventstore.* content types have been renamed to vnd.kurrent.*:

The application/vnd.eventstore.atomsvc+json content type has been removed and replaced with application/vnd.kurrent.atomsvc+json.

Xml content types are unchanged.

Custom HTTP headers

The ES-* HTTP headers have been renamed to Kurrent-*.

Deprecated headers accepted by the server:

Deprecated headers provided by the server in certain responses:

To 24.10

Persistent Subscriptions checkpoints compatibility

24.10+ writes Persistent Subscription Checkpoints prefixed with a $, to bring them into line with other system events. The change is backwards compatible (new versions of the server will understand the old checkpoints), but old versions of the server will not understand the new checkpoints.

The 23.10 series has been patched to understand the new checkpoints starting with 23.10.8. Consider upgrading to 23.10.8 (or a more recent patch) before upgrading to 24.10+ so that in the event of a rollback persistent subscriptions will continue smoothly.

Breaking changes

Histograms endpoint has been removed

The /histogram/{name} endpoint has been removed.

Any tooling that relies on the histogram endpoint will receive a 404 when requesting this endpoint after upgrading.

Support for v1 PTables has been removed

Support for extremely old PTables (v1) has been removed.

This will only affect databases created before EventStoreDB version 3.9.0, and which have not upgraded their PTables since EventStoreDB version 3.9.0.

PTables are automatically upgraded when merged or when the PTables are rebuilt. So, if your EventStoreDB has been running for some time on a version >= 3.9.0, then you are unlikely to be affected by this change.

If 32bit PTables are present, we detect them on startup and exit. If this happens, you can use a version >= v3.9.0 and < v24.10.0 to upgrade the PTables, or alternatively you can delete the index and it will be rebuilt. The rebuild would involve reading the whole database, which can take a long time on large databases.

Otel Exporter commercial plugin configuration changes

The configuration for this plugin is now nested in the KurrentDB subsection to ensure consistency with the other plugins. Additionally, this plugin used to be configured via JSON or environment variables, but it can now be configured directly in the server's main configuration.

For example, an old JSON configuration file could look like this:

{
  "OpenTelemetry": {
    "Otlp": {
      "Endpoint": "http://localhost:4317"
    }
  }
}

Which would now look like this:

{
  "KurrentDB": {
    "OpenTelemetry": {
      "Otlp": {
        "Endpoint": "http://localhost:4317"
      }
    }
  }
}

And can instead be moved to the main config file like this:

OpenTelemetry:
  Otlp:
    Endpoint: "http://localhost:4317"

User Certificates commercial plugin configuration changes

The configuration for this plugin used to be nested in a subsection titled Plugins. This is no longer the case. Additionally, this plugin used to be configured via JSON or environment variables, but it can now be configured directly in the server's main configuration.

For example, an old JSON configuration file could look like this:

{
  "EventStore": {
    "Plugins": {
      "UserCertificates": {
        "Enabled": true
      }
    }
  }
}

Which would now look like this:

{
  "KurrentDB": {
    "UserCertificates": {
      "Enabled": true
    }
  }
}

And can instead be moved to the main config file like this:

UserCertificates:
  Enabled: true

External TCP API removed

The external TCP API was removed in EventStoreDB 24.2.0. This affects external clients using the TCP API and its related configurations.

::: tip KurrentDB 25.0 includes a plugin that enables the TCP client protocol. This plugin can only be used with a license :::

A number of configuration options have been removed as part of this. KurrentDB will not start by default if any of the following options are present in the database configuration:

• AdvertiseTcpPortToClientAs
• DisableExternalTcpTls
• EnableExternalTcp
• ExtHostAdvertiseAs
• ExtTcpHeartbeatInterval
• ExtTcpHeartbeatTimeout
• ExtTcpPort
• ExtTcpPortAdvertiseAs
• NodeHeartbeatInterval
• NodeHeartbeatTimeout
• NodeTcpPort
• NodeTcpPortAdvertiseAs
• TcpReadTimeoutMs

Stricter node certificate requirements

EventStoreDB 24.2.0 introduced stricter requirements for Key Usages in node certificates.

These requirements are:

• The certificate Extended Key Usages (EKUs) either:
  • Contains both the ClientAuth EKU and the ServerAuth EKU, or
  • Is empty.
• The certificate Key Usages contains either:
  • DigitalSignature and KeyEncipherment, or
  • DigitalSignature and KeyAgreement.

If a node certificate does not meet these requirements, the nodes in the cluster will be unable to make gossip and election requests. In this case, you will see the following logs:

[16480,21,14:57:06.209,WRN] Failed authorization check for "(anonymous)" in 00:00:00.0000826 with "node/gossip : update Deny : Policy : Legacy 1 9999-12-31 11:59:59 PM +00:00 : default:denied by default:Deny, $"

You can correct this by regenerating the certificates with the correct key usages. See the Certificate Configuration documentation for more information about configuring and generating certificates.

To v23.10

Breaking changes

The updates to anonymous access described in the release notes have introduced some breaking changes. We have also removed, renamed, and deprecated some options in KurrentDB.

None of these changes will prevent you from performing an online rolling upgrade of the cluster, but you will need to take them into account before you perform an upgrade.

When upgrading from 22.10 and earlier, you will need to account for the following breaking changes:

Clients must be authenticated by default

We have disabled anonymous access to streams by default. This means that read and write requests from clients need to be authenticated.

If you see authentication errors when connecting to KurrentDB after upgrading, please ensure that you either use default credentials on the connection or provide user credentials with the request itself.

If you want to revert to the old behavior, you can enable the AllowAnonymousStreamAccess and AllowAnonymousEndpointAccess options in KurrentDB.

Requests to the HTTP API must be authenticated by default

Like with anonymous access to streams, anonymous access to the HTTP and gRPC endpoints has been disabled by default. The exceptions are the /gossip, /info, and /ping endpoints.

Any tools or monitoring scripts accessing the HTTP endpoints (e.g., /stats) must make authenticated requests to KurrentDB.

If you want to revert to the old behavior, you can enable the AllowAnonymousStreamAccess and AllowAnonymousEndpointAccess options in KurrentDB.

PrepareCount and CommitCount options have been removed

We have removed the PrepareCount and CommitCount options from KurrentDB. KurrentDB will fail if these options are present in the config on startup.

These options did not have any effect and can be safely removed from your configuration file if you have them defined.

Persistent subscriptions config event has been renamed

We have renamed the event type used to store a persistent subscription configuration from PersistentConfig1 to $PersistentConfig. This event type is a system event, so naming it as such will allow certain filters to exclude it correctly.

If you have any tools or clients relying on this event type, you will need to update them before upgrading.