Skip to content

Manage

Stream management covers everything outside appending and reading. Four things you can do:

  • Inspect a stream, to find out whether it exists, what state it is in, where it starts and ends.
  • Remove a stream, soft deleting it so the name can be reused, or tombstoning it permanently.
  • Remove events, truncating a stream so old records stop being readable while the stream lives on.
  • Configure a stream, setting retention rules or attaching your own key-value metadata to it.

Retention, access control, and custom metadata all live together on a hidden metadata stream that sits beside the real one. That is why those operations return a revision, and why concurrent edits need care. Concurrency on metadata covers it.

Before you branch on whether a stream exists, ask. GetStreamInfo answers for any stream, including one that has never existed, and it never throws for a missing one. That makes it the safe way to check, and the natural building block for admin views and test assertions.

var info = await client.Streams.GetStreamInfo("order-123");
if (info.State == StreamState.Missing)
Console.WriteLine("nothing here yet");

A stream is in one of four states: Active (readable and writable), Deleted (soft-deleted, and recreatable by appending), Tombstoned (gone for good), or Missing (never existed).

You get back a StreamInfo:

Member Type What it tells you
Stream StreamName The stream you asked about
State StreamState Active, Deleted, Tombstoned, or Missing
InfoRevision Revision Where the metadata stream is. Hand it back to guard a concurrent edit
Retention StreamRetention The retention rules in force: MaxAge, MaxCount, TruncateBefore
Acl StreamAcl Who may read and write
Metadata Metadata Whatever you attached
FirstStreamRevision · FirstStreamPosition · FirstStreamAppendedAt Where the stream starts, and when
LastStreamRevision · LastStreamPosition · LastStreamAppendedAt Where it ends, and when

Deleting a stream hides it from readers while leaving the name free. It is the one you want almost every time: for a lifecycle that has run its course, for data that has expired, or to undo a stream created by mistake.

LogPosition at = await client.Streams.Delete("order-123");

Afterwards the stream reads as though it were never there. Append to the same name and it comes back to life, picking up from where it left off. If the last event was revision 3, the next one is 4, and readers see only 4 onward.

The deletion is itself recorded, so subscribers observe it. The call returns its log position. The old events survive on disk until the next scavenge clears them.

Delete conditionally when it matters that nothing arrived while you were deciding. That is a common shape when tidying up a per-job stream after reading its final state:

LogPosition at = await client.Streams.Delete("order-123", 9);

If someone appended in the meantime, the call throws StreamRevisionConflictException rather than discarding their write. A stream that is already deleted, tombstoned, or was never there throws StreamDeletedException, StreamTombstonedException or StreamNotFoundException instead.

Tombstoning permanently deletes a stream and leaves a tombstone behind. It is not a firmer delete. It is a different operation, and it cannot be undone.

LogPosition at = await client.Streams.Tombstone("order-123");

A tombstone event is appended to the stream, and that event outlives everything else. A scavenge clears the stream’s records, but the tombstone stays forever, which is what keeps the name permanently reserved. Every later read and every later append fails.

Reach for it when the name itself must never come back: a compliance requirement, an abusive tenant, or a name you are deliberately retiring. Reach for delete in every other case.

Delete Tombstone
Can you undo it yes. Append and the stream returns no
Can the name be reused yes never
Reading afterwards StreamNotFoundException StreamTombstonedException
Appending afterwards starts the stream again fails, permanently
After a scavenge records gone records gone, tombstone remains
Reach for it when the lifecycle ended, data expired, undo compliance, abuse, retiring a name

A conditional form exists here too:

LogPosition at = await client.Streams.Tombstone("order-123", 9);

Truncating removes events; deleting and tombstoning remove streams. The stream itself stays active and keeps taking appends. You are declaring that everything before a point no longer matters.

Success ok = await client.Streams.Truncate("order-123", 50);

Revisions 0 to 49 stop being readable. Revision 50 onward is untouched. The hidden records are cleared at the next scavenge.

This is the only way to remove events at all. KurrentDB cannot delete an event from the middle of a stream, only from the start. It is also the same machinery a delete uses: deleting a stream is truncating it at its maximum.

It fits whenever history has served its purpose but the stream has not:

  • trimming work items off a queue stream once they are processed
  • dropping history after snapshotting an aggregate
  • enforcing retention by revision, where count and age do not express the rule

Retention rules let the server decide what to keep, instead of you truncating by hand. Records falling outside the limits become eligible for removal at the next scavenge.

Revision rev = await client.Streams.ConfigureDataRetention("order-123", options => {
options.MaxCount = 500;
options.MaxAge = TimeSpan.FromDays(7);
});
Rule Effect
MaxCount Keep at most this many records
MaxAge Keep records younger than this

Set both and either can retire a record. Zero is rejected for either bound with an ArgumentException — use Truncate to drop everything.

When only one bound matters, a shorter form says so:

await client.Streams.ConfigureDataRetention("order-123", maxCount: 500);
await client.Streams.ConfigureDataRetention("order-123", TimeSpan.FromDays(7));

You can hang arbitrary key-value data off a stream: an owning team, a classification label, a compliance marker, or per-stream configuration your application reads at startup. It travels with the stream and comes back on GetStreamInfo.

Revision rev = await client.Streams.SetCustomMetadata("order-123", Metadata.New
.With("owner", "billing-team")
.With("compliance", "pii"));

That form replaces the whole bag. Any key not in the Metadata you pass is gone.

To add or change keys and keep the rest, use the callback form. It reads the current metadata, hands it to you, and writes the merged result back. It is also how you remove a single key.

await client.Streams.SetCustomMetadata("order-123", meta =>
meta.With("last-reviewed", DateTimeOffset.UtcNow));

Retention, access control, and custom metadata share one hidden metadata stream, and it has its own revision. Two services editing different things are still writing to the same place, so the later write can silently discard the earlier one. One sets retention while the other tags an owner.

Read the current revision and pass it back to prevent that:

var info = await client.Streams.GetStreamInfo("order-123");
await client.Streams.SetCustomMetadata("order-123", metadata, info.InfoRevision);

If anyone wrote first, the call fails with StreamRevisionConflictException instead of overwriting them. Both SetCustomMetadata and ConfigureDataRetention return the metadata stream’s new revision, so you can chain edits without re-reading.

Exception What happened
StreamNotFoundException The stream does not exist
StreamDeletedException It was soft-deleted
StreamTombstonedException It was tombstoned, and nothing will bring it back
StreamRevisionConflictException The stream or its metadata moved before your call landed