Append
Appending is how data gets into KurrentDB. Two things you can do:
- Write to one stream, the common case. One record or many, committed together.
- Write across several streams, as one atomic transaction spanning streams, when an invariant does not fit inside a single one.
Both are transactional: every record in the call lands, or none of them does. Neither needs the stream to exist first, because the first append creates it.
The other half of appending is deciding what happens when someone else writes at the same time. Guarding against concurrent writes covers that, and it is usually the part that matters.
Write to one stream
Section titled “Write to one stream”Name the destination once. Every record in the call inherits it, and the batch commits as a unit.
var record = new AppendRecord { Stream = "order-123", Value = new OrderPlaced("order-123", "Widget", 5)};
var result = await client.Streams.AppendStream(record);
Console.WriteLine("now at revision {0}", result.Revision);Payloads take their wire format from the message type unless you set DataFormat, and the schema
name comes from your catalog. See
Data Formats. The same shape works for events, commands, and
snapshots, because KurrentDB does not distinguish them.
You get back where the write landed: a Position, plus the Stream and Revision read off it.
Several records to the same stream go in one call, and commit together or not at all:
await client.Streams.AppendStream("order-456", new[] { new AppendRecord { Value = new OrderPlaced(…) }, new AppendRecord { Value = new OrderConfirmed(…) }});Guarding against concurrent writes
Section titled “Guarding against concurrent writes”Two services appending to the same stream will eventually collide. ExpectedStreamState tells the
server what the stream must look like for your write to be accepted, and the server rejects it
otherwise. This is optimistic concurrency: you do not lock anything, you state an assumption and find
out if it held.
The usual shape is read-then-write. Read where the stream is, decide, and append against that revision:
var last = await client.Streams.LastRecord("order-123", skipDecoding: true);
// … decide what to do, based on what you read …
await client.Streams.AppendStream(record, last.Revision);If anyone appended in between, the call throws StreamRevisionConflictException rather than writing
on top of a decision made from stale data. The exception carries both revisions, so you can retry
against the new one.
| Expectation | The write succeeds only if |
|---|---|
Any |
always. The default, with no check |
NoStream |
the stream does not exist yet |
Exists |
the stream already has records |
Revision.From(n) |
the stream is at exactly revision n |
NoStream is how you claim a name exactly once. The first writer wins, and everyone else gets
StreamAlreadyExistsException. Revision.From(n) is the strong one, and what you want whenever two
writers can contend.
A Revision converts to an ExpectedStreamState on its own, so last.Revision passes straight in.
A tombstoned stream refuses every append no matter what you expect.
Write across several streams
Section titled “Write across several streams”Sometimes the rule you are enforcing spans two streams: only record this transfer if the inventory stream has not moved since I read it. One append cannot express that, because it can only guard the stream it writes to.
AppendRecords can. Each record names its own destination, and consistency checks assert the state
of any stream the transaction touches, including streams you are not writing to.
var inventory = await client.Streams.LastRecord($"inventory-{sku}", skipDecoding: true);
await client.Streams.AppendRecords( new[] { new AppendRecord { Stream = $"inventory-{sku}", Value = transferred }, new AppendRecord { Stream = "transfer-log", Value = transferred } }, new AppendRecordsOptions { Checks = [ConsistencyCheck.StreamAtRevision($"inventory-{sku}", inventory.Revision)] }, default);The server evaluates every check against the real state at commit time. One failure rejects the whole transaction.
| Check | Asserts that the stream |
|---|---|
StreamAtRevision(stream, revision) |
sits at exactly that revision |
StreamExists(stream) |
has at least one record |
StreamDoesNotExist(stream) |
has no records, or was deleted |
StreamIsDeleted(stream) |
was soft-deleted |
StreamIsTombstoned(stream) |
was tombstoned |
You get back the revision of every stream the transaction touched, plus the log position of the commit.
Because the checks span streams, a failure cannot collapse into one exception the way a single-stream
conflict does. AppendConsistencyViolationException carries every violation, each naming its stream,
what you expected, and what was actually there:
catch (AppendConsistencyViolationException ex) { foreach (var violation in ex.Violations) { var state = violation.AsStreamStateViolation; Console.WriteLine("{0}: expected {1}, was {2}", state.Stream, state.ExpectedState, state.ActualState); }}When things go wrong
Section titled “When things go wrong”| Exception | What happened |
|---|---|
StreamRevisionConflictException |
Someone wrote first. Carries ExpectedRevision and ActualRevision |
StreamAlreadyExistsException |
You expected NoStream, but records were there |
StreamNotFoundException |
You expected Exists, and it does not |
StreamDeletedException |
Your consistency check expected a live stream and the stream was soft-deleted. See below |
StreamTombstonedException |
The stream was tombstoned. No append will ever succeed |
AppendConsistencyViolationException |
One or more consistency checks failed. See Violations |
MaxAppendRecordSizeExceededException |
A single record exceeds the server’s per-record limit. Carries RecordActualSize and RecordMaxSize |
MaxAppendTransactionSizeExceededException |
The whole transaction exceeds the server’s limit. Carries TransactionActualSize and TransactionMaxSize |
Both sizes are measured on the serialized record, not on your payload: the schema name, the record id and any metadata count toward the total. Budget for that headroom rather than treating the ceiling as a payload allowance. The client measures the same unit the server enforces, so an oversized append fails immediately instead of after a round trip.
Appending to a soft-deleted stream revives it
Section titled “Appending to a soft-deleted stream revives it”StreamDeletedException is a concurrency outcome, not a rule about where you may write. An append
that carries no consistency check succeeds against a soft-deleted stream, and the stream comes
back to life with its history truncated away. You only see the exception when you asked for a
specific state and the server found the stream deleted instead.
Tombstoning is the opposite. It is permanent, and no append to a tombstoned stream ever succeeds.
If you need “write only if this stream is alive”, say so with ExpectedStreamState.Exists and handle
StreamDeletedException. Without a check, the next write silently undoes a delete you did not
expect.