Skip to content

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.

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(…) }
});

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.

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);
}
}
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.