22.10.0 Release Notes

We are pleased to announce the official release of EventStoreDB OSS & Commercial version 22.10.0 LTS.

This is an LTS release and will be supported until October 2024.
Read more about our versioning strategy here.

The complete changelog can be found here. If you need help planning your upgrade or want to discuss support, please contact us here.

EventStoreDB 22.10.0 is available for the following operating systems:

• Windows
• Ubuntu 18.04
• Ubuntu 20.04
• Ubuntu 22.04 (Preview)
• CentOS 7 (Commercial version)
• Amazon Linux 2 (Commercial version)
• Oracle Linux 7 (Commercial version)

Additionally, you can find docker images including the experimental ARM64 image on Dockerhub.

Should I upgrade?

22.10.0 is an LTS version and will be supported for 2 years until version 24.10.0 is released in October 2024.

Both versions 22.6.x and 20.10.x are going out of support following this release. If you are running either of these versions (or an older one than 20.10.x) then we recommend that you upgrade to continue receiving support and fixes.

If you are on 21.10.x and wondering if you should upgrade, then check the feature highlights to see what’s new in 22.10.0 vs 21.10.0. If you are not wanting to upgrade for any of those features, then ensure that you are on the latest version of 21.10 (21.10.8 at the time of this writing) to get the latest fixes and patches.

This graph maps out the current and planned EventStoreDB releases:

Important fixes in 21.10.8

If you are not upgrading to 22.10.0, then we highly recommend keeping EventStoreDB up to date with the latest LTS patch versions.

These patches contain important fixes for cluster stability, performance, and the prevention of possible data-loss scenarios.

The upgrade can be done directly from any version of 20.10 and 21.10. There is no need to step through all of the versions, and the upgrade steps are the same as below.

20.10 is out of support

LTS versions of EventStoreDB are supported for a period of 2 years, which means that 20.10 is out of support following the release of 22.10.0.

As such, we recommend that you either upgrade to 22.10.0 if you are running version 20.10 or lower. You can upgrade directly to 22.10.0 from any version of 20.10.x, you do not need to upgrade to 21.10.x first.

There is a 2-month grace period where we will continue to provide support for 20.10.x to allow for upgrading to a newer version. This grace period will end in January 2023.

22.6 is out of support

22.6.0 was an interim release, which is only supported until the following release of EventStoreDB. If you are on 22.6.0 then we recommend that you upgrade to 22.10.0 as interim versions will not receive support or fixes beyond this release.

Upgrade Procedure

To upgrade a cluster from 20.10.x or 21.10.x,  a usual rolling upgrade can be done:

• Pick a node (start with the follower nodes first, then choose the leader last).
• Stop the node, upgrade it and start it.

Where Can I Get the Packages?

Downloads are available on our website.

The packages can also be installed using the following instructions.

Ubuntu 18.04/20.04 (via packagecloud)

curl -s https://packagecloud.io/install/repositories/EventStore/EventStore-OSS/script.deb.sh | sudo bash
sudo apt-get install eventstore-oss=22.10.0

Ubuntu 22.04 Preview(via packagecloud)

curl -s https://packagecloud.io/install/repositories/EventStore/EventStore-OSS/script.deb.sh | sudo bash
sudo apt-get install eventstore-oss=22.10.0~preview1

Windows (via Chocolatey)

choco install eventstore-oss -version 22.10.0

Docker (via docker hub)

docker pull eventstore/eventstore:22.10.0-focal
docker pull eventstore/eventstore:22.10.0-bullseye-slim

Highlights for this release

.NET 6.0 Upgrade

.NET 5.0 went out of support this year, so we have upgraded to .NET 6.0 in this LTS release.

The .NET 6.0 upgrade was also the main thing holding up non-alpha ARM64 releases due to the number of stability improvements it potentially brings to ARM. As such, we will be working towards an official ARM64 release in the future.

We currently do not plan to backport this upgrade to EventStoreDB 21.10.x. If you are concerned about running on an unsupported version of dotnet then we recommend that you upgrade to 22.10.0.

Improved Scavenge Process

22.10.0 includes the new scavenge process which runs approximately 4-40x faster depending on the circumstances, and uses much less memory than scavenges in the previous versions.

The new scavenge has a few differences from the previous version:

Nodes can scavenge to the same point

The new scavenge process saves a scavenge point in the log containing the location that the scavenge will run up to and the timestamp used for checking ‘maxAge’ during the scavenge.

This scavenge point is shared across all of the nodes in the cluster. Any time a scavenge is started on a node, it will first check if there are any existing scavenge points from another node. If there is, it will scavenge up to the latest scavenge point. Otherwise, it will create a new one.

In this way, each node in the cluster will have the same data after a scavenge has been run on all of the nodes.

Data is removed from the current active chunk

Previously, the most recently written chunk in the database would not be scavenged because the chunk was not marked as complete.

The new scavenge process completes the current chunk when it writes a scavenge point. This means that all of your data is eligible to be scavenged and you no longer have to wait until enough data has been written to complete a chunk to scavenge recently-written data.

New scavenge directory

Scavenge accumulates data that it references throughout the current scavenge and subsequent scavenges on the same node. This data is stored in the 'scavenge' directory inside the index directory.

We recommend the scavenge directory is included in backups to save time having to rebuild it next time a scavenge is run after a restore. As before, ensure that scavenge is not running while a backup is taken (this is not necessary when backing up with disk snapshots).

Dev certificates

We have introduced a new dev mode to make running a local dev instance of EventStoreDB easier. You can now run a secure single EventStoreDB node on localhost with the command:

./EventStore.ClusterNode.exe -–dev

This does a few things. It generates a self-signed dev certificate for the node if one isn’t already present, enables AtomPub over HTTP, enables system projections, and starts the secure EventStoreDB instance.

You can then browse to the admin UI or connect a gRPC client with very little hassle.

The benefit to this over insecure mode is that there are no extra configuration changes needed for your clients, and user management is enabled in secure mode.

If you wish to remove the dev certificates created by EventStoreDB, you can run the command:

./EventStore.ClusterNode.exe --remove-dev-certs

Dynamic Stream Info Cache

The Stream Info Cache is the lookup that contains key information about any stream that has recently been read or written to. Having entries in this cache significantly improves write and read performance to cached streams on larger databases.

Previously, this cache size was set to a static value based on the amount of free memory at the time of EventStoreDB starting up. This could result in an unnecessarily large Stream Info Cache, or in too much memory pressure on the node.

As of EventStoreDB 22.10.0, the Stream Info Cache is dynamic by default. This means that it gets resized periodically or under certain conditions based on how much free memory is available.

The dynamic cache deals with the following scenarios more efficiently than the statically-sized one:

• Growth of the database with time
• Heavy operations such as index merges
• Growth in the number of clients connected
• Spike in memory usage of other processes on the system

The StreamInfoCache can still be made static by specifying --stream-info-cache-capacity

New statistics for caches are also available under es.stats.cache.* in the stats log file.

$all position is available when reading streams over gRPC

Since EventStoreDB 22.6.0, the $all position is included in the result for stream reads, subscriptions, and persistent subscriptions. This means that you can now read an event in a stream and find its corresponding position in the $all stream.

In order to get this functionality, you may need to upgrade your gRPC client to the latest version.

The one caveat is that this is not supported on events written through transactions in the legacy TCP client. For these events, the positions in the events will be the same as before.

Check out PR#3459 for more information.

Better support for the Windows cert store

EventStoreDB 22.6.0 introduced the ability to load the Trusted Root Certificate from the Windows certificate store rather than from a folder.

To use this, provide TrustedRootCertificateStoreName and TrustedRootCertificateStoreLocation in the settings when configuring your EventStoreDB, and then provide either the TrustedRootCertificateThumbprint or TrustedRootCertificateSubjectName to specify which certificate to load.

For example, using thumbprint:

TrustedRootCertificateStoreLocation: LocalMachine
TrustedRootCertificateStoreName: Root
TrustedRootCertificateThumbprint: {thumbprint}
CertificateStoreLocation: LocalMachine
CertificateStoreName: My
CertificateThumbprint: {thumbprint}

Or using SubjectName (this will match any certificate that contains the subject name):

TrustedRootCertificateStoreLocation: LocalMachine
TrustedRootCertificateStoreName: Root
TrustedRootCertificateSubjectName: EventStoreDB CA
CertificateStoreLocation: LocalMachine
CertificateStoreName: My
CertificateSubjectName: eventstoredb-node

See PR#3498 for more details.

Better support for Certificates when using DNS discovery 

EventStoreDB 21.10.5 added support for wildcard certificates when using DNS discovery in a cluster.

This means that you don't have to include the IP address in the node's certificate when using DiscoverViaDns: true.

Check out this blog post for more information on how to configure a cluster in this way.

Faster startup times for Large Databases

When EventStoreDB upgraded to NET5.0, a performance regression in Directory.EnumerateFiles made a performance issue in the EventStoreDB code more obvious, which greatly affected startup and truncation times on large databases.

We have reduced the computational complexity of the methods run at startup to lower the impact of the regression and improve startup times.

This fix was introduced in EventStoreDB 21.10.2.

Breaking Changes

There are no breaking changes in terms of the database format, configuration, or rolling upgrades.

However, there are some breaking changes since 21.10.0 that will affect those maintaining third-party gRPC clients.

Proto2 upgraded to Proto3 (TCP)

The server now uses Proto3 for messages sent to the legacy TCP clients. This may impact community clients, especially when it comes to default or required fields as these are no longer supported in Proto3.

EmitEnabled and TrackEmittedStreams for projections (gRPC)

Since 22.6.0, the server supports clients setting EmitEnabled and TrackEmittedStreams when creating a projection.

If you maintain your own client, then you will need to take note of the changes made here:

https://github.com/EventStore/EventStore/pull/3384

https://github.com/EventStore/EventStore/pull/3412

Essentially, the names of EmitEnabled and TrackEmittedStreams have been swapped in the proto because what the server used to refer to as TrackEmittedStreams is, in fact, the correct behavior for EmitEnabled.

Therefore clients that were relying on the old behavior and just sending TrackEmittedStreams=true to enable emitting when creating a projection will continue to work after upgrading the server.

However, the server will now throw when sent a create request with TrackEmittedStreams=true, but EmitEnabled=false. This is because a code change will be needed when a client library is upgraded, so throwing an error will make that code change more obvious.

Documentation and previous release notes

Documentation for EventStoreDB can be found here.
Previous release notes can be found here.

Providing Feedback

If you encounter any issues, please don’t hesitate to open an issue on GitHub if there isn’t one already.

Additionally, there is a fairly active discuss channel, and an #event-store-db channel on the DDD-CQRS-ES community.

If you have any questions that aren't covered in these release notes or the docs, please feel free to reach out.