| name | kurrent-upgrade |
| description | Use when migrating an app onto the KurrentDB gRPC client from a legacy EventStoreDB client. Covers both the TCP rewrite and gRPC rebrand paths, plus the esdb to kurrentdb connection-string switch. NOT for code already on the KurrentDB client (use kurrent-docs) or server upgrades. |
KurrentDB client migration
Two flavours of migration land here, both targeting KurrentDB.Client / KurrentDBClient:
- TCP rewrite for projects still on the legacy EventStoreDB TCP client. A real rewrite: package, transport, API shape, and event model all change.
- gRPC rebrand for projects on the intermediate EventStoreDB gRPC client (
EventStore.Client 23.x and equivalents). A mechanical package + symbol rename plus a small number of API breaks.
Pick the flavour first, then the language reference. Each reference is self-contained and walks the migration top-to-bottom.
Routing
Step 1: pick the flavour
| Source state | Flavour | Folder |
|---|
Legacy TCP client (.NET EventStore.ClientAPI / EventStoreConnection, JVM com.geteventstore:eventstore-client / EsConnection) | TCP rewrite | references/tcp-to-grpc/ |
Intermediate gRPC client (EventStore.Client 23.x, EventStore.Client.Grpc.*, com.eventstore:db-client-java, @eventstore/db-client, etc.) | gRPC rebrand | references/rebrand/ |
Already on KurrentDB.Client and kurrentdb:// | none | route to kurrent-docs |
If you cannot tell which flavour applies, run kurrentdb-client-detection first and use its classification.
Step 2: pick the language reference
The TCP JVM reference targets Java consumers of EventStore.JVM (the Scala-based legacy client exposes a Java facade under eventstore.j.*); pure Scala consumers follow the same API mapping but keep scala.concurrent.Future instead of CompletableFuture.
For an ecosystem and flavour combination not in the table, link the official client upgrade docs and do not improvise package names, connection strings, or API shapes. The shape of these renames is not portable across SDKs.
Done-criteria. Every TCP-rewrite reference opens with a ## Required outcomes checklist. Load it first, satisfy each item, and reread before declaring the migration complete. The rebrand references close with an equivalent end-of-page checklist.
Do NOT use for
- Current-SDK usage in a project already on
KurrentDB.Client. Use kurrent-docs.
- Server cluster upgrades (binary, schema, gossip). Defer to the official server upgrade docs; per-version playbooks will land under sibling
kurrent-upgrade-v*-to-v* skills.
- Greenfield SDK adoption. Use
kurrent-docs.
Load order
- Step 1 above: pick the flavour folder.
- Step 2 above: load the matching language reference and work top-to-bottom. Each reference depends on previous sections compiling.
references/grpc-retry-policy.md. The gRPC client has no built-in retries; wire a retry pipeline before declaring done. The file holds the language-neutral contract and a .NET recipe (Polly v8); other languages apply the contract to their idiomatic resilience library. For the rebrand flavour this is only relevant if the project does not already have retry policies wired (the retry contract did not change in the rebrand).
