# 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.

## Compatibility

EventSourcingDB aims for **long-term compatibility across versions**. Backups created with one version can generally be restored in both newer or older versions of EventSourcingDB, provided the underlying storage format remains compatible. **No manual adjustment of data or configuration is usually required.**

The following versions of the client SDKs and tools run with this version of EventSourcingDB, as their tests show:

| SDK or Tool | Versions that run with EventSourcingDB 1.2 |
|---|---|
| .NET SDK | 1.0 and later |
| Elixir SDK | 1.0 and later |
| Go SDK | 1.0 and later |
| JavaScript SDK | 1.0 and later |
| MCP Server | 1.0 and later |
| PHP SDK | 1.0 and later |
| Python SDK | 1.0 and later |
| Rust SDK | 1.0 and later |

## 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**.