From KurrentDB v1
Kurrent Surge is the successor to the v1 KurrentDB.Client packages. Because v1 was itself a rebrand
of the EventStoreDB client, this migration is the same shape as
From EventStoreDB. Only the names you are replacing differ.
Your kurrentdb:// connection strings keep working unchanged.
Packages
Section titled “Packages”dotnet remove package KurrentDB.Client.Streamsdotnet remove package KurrentDB.Client.PersistentSubscriptionsdotnet remove package KurrentDB.Client.ProjectionManagementdotnet remove package KurrentDB.Client.Operations
dotnet add package Kurrent.SurgeFour packages become one. Kurrent.Surge carries streams, the schema registry, secondary indexes,
connectors, and node administration behind a single KurrentClient.
Namespaces
Section titled “Namespaces”The DB infix is gone.
| Old | New |
|---|---|
KurrentDB.Client |
Kurrent.Surge.Client |
KurrentDB.Client.Streams |
Kurrent.Surge.Client.Streams |
// Oldusing KurrentDB.Client;
// Newusing Kurrent.Surge.Client;using Kurrent.Surge.Client.Streams;One client, five modules
Section titled “One client, five modules”// Oldvar settings = KurrentDBClientSettings.Create("kurrentdb://admin:changeit@localhost:2113?tls=false");var client = new KurrentDBClient(settings);
// Newawait using var client = KurrentClient.Create("kurrentdb://admin:changeit@localhost:2113?tls=false");Note the await using. IKurrentClient is IAsyncDisposable, not IDisposable.
| Module | Reached through | Covers |
|---|---|---|
| Streams | client.Streams |
Append, read, delete, tombstone, truncate, metadata |
| Registry | client.Registry |
Schema registry |
| Indexes | client.Indexes |
Secondary indexes |
| Connectors | client.Connectors |
Connector lifecycle |
| Admin | client.Admin |
Scavenge, shutdown, leader resignation, node priority |
// Oldawait client.AppendToStreamAsync("my-stream", StreamState.Any, events);
// Newawait client.Streams.AppendStream("my-stream", records, ExpectedStreamState.Any);Configuration
Section titled “Configuration”KurrentClientOptions replaces KurrentDBClientSettings. It is a record, so with composes on top
of a parsed connection string.
await using var client = KurrentClient.Create( "kurrentdb://admin:changeit@localhost:2113", opts => opts.Resilience = KurrentClientResilienceOptions.HighAvailability);
var options = KurrentClientOptions.Parse("kurrentdb://admin:changeit@localhost:2113") with { Resilience = KurrentClientResilienceOptions.HighAvailability};Resilience presets: Default, NoResilience, FailFast, HighAvailability, CautiousWrite,
Subscription, RetryForever.
Security presets: Insecure, Tls, Password, MutualTls.
Records replace events
Section titled “Records replace events”// Oldvar eventData = new EventData( Uuid.NewUuid(), "OrderPlaced", JsonSerializer.SerializeToUtf8Bytes(new { OrderId = "123" }));
await client.AppendToStreamAsync("order-123", StreamState.Any, new[] { eventData });
// Newvar record = new AppendRecord { Stream = "order-123", Value = new { OrderId = "123" }};
var result = await client.Streams.AppendStream(record);AppendRecord encodes as JSON by default, and the schema name comes from your message catalog rather
than a hand-written type string. See Catalogs.
Reads interleave records with checkpoints:
await foreach (var item in client.Streams.ReadStream("order-123")) { item.Switch( record => Console.WriteLine("{0} at revision {1}", record.TypeName, record.Revision), checkpoint => { });}The Async suffix is gone; the methods are still async.
Exceptions are typed
Section titled “Exceptions are typed”// Oldcatch (WrongExpectedVersionException ex) { }
// Newcatch (StreamRevisionConflictException ex) { Console.WriteLine("Expected {0}, was {1}", ex.ExpectedRevision, ex.ActualRevision);}Dependency injection
Section titled “Dependency injection”// Oldservices.AddKurrentDBClient("kurrentdb://admin:changeit@localhost:2113?tls=false");
// Newservices.AddKurrentSurge(surge => surge .Connection("kurrentdb://admin:changeit@localhost:2113?tls=false"));Checklist
Section titled “Checklist”-
Packages. Remove all four
KurrentDB.Client.*, and addKurrent.Surge. -
Usings.
KurrentDB.ClientbecomesKurrent.Surge.Client. -
Construction.
new KurrentDBClient(settings)becomesKurrentClient.Create(connectionString), andusingbecomesawait using. -
Calls. Route through the module and drop the
Asyncsuffix:Old New client.AppendToStreamAsync(...)client.Streams.AppendStream(...)client.ReadStreamAsync(...)client.Streams.ReadStream(...)client.DeleteAsync(...)client.Streams.Delete(...)client.TombstoneAsync(...)client.Streams.Tombstone(...) -
Record types.
EventDatabecomesAppendRecord, andResolvedEventorRecordedEventbecomesRecord:Old New resolvedEvent.Event.EventTyperecord.TypeNameresolvedEvent.Event.OriginalEventNumberrecord.RevisionresolvedEvent.Event.Positionrecord.PositionresolvedEvent.OriginalPositionrecord.CheckpointPosition -
Concurrency.
StreamRevisionbecomesRevision, andStreamStatebecomesExpectedStreamState. -
Exceptions. Replace
WrongExpectedVersionExceptionwithStreamRevisionConflictException. -
Registration.
AddKurrentDBClientbecomesAddKurrentSurge, which takes a scope rather than a connection string. See Wiring Up Surge. -
Declare your message types. Kurrent Surge does not infer schema names, so an append of an undeclared type throws. This has no v1 equivalent and is the step most likely to surprise you. See Catalogs.
-
Build, then run your tests.
Breaking changes
Section titled “Breaking changes”| Area | v1 | Kurrent Surge |
|---|---|---|
| Package | Four KurrentDB.Client.* |
One Kurrent.Surge |
| Namespace | KurrentDB.Client |
Kurrent.Surge.Client |
| Client type | KurrentDBClient |
KurrentClient |
| Construction | new KurrentDBClient(settings) |
KurrentClient.Create(...) |
| Settings | KurrentDBClientSettings |
KurrentClientOptions |
| Feature access | Top-level methods | Module properties |
| Append model | EventData |
AppendRecord |
| Read model | ResolvedEvent or RecordedEvent |
Record, with Checkpoint interleaved |
| Link resolution | resolveLinkTos: true |
Automatic on a stream read, never on $all |
| Stream state | StreamState |
ExpectedStreamState |
| Revision | StreamRevision |
Revision |
| Method names | *Async suffix |
No suffix |
| Disposal | IDisposable |
IAsyncDisposable |
| Schema names | Inferred from the event type string | Declared in a catalog |