Skip to content

The search box knows all the secrets -- try it!

Fisher is part of the Critter Stack ecosystem.

JasperFx Logo JasperFx provides formal support for Fisher and other Critter Stack libraries. Please check our Support Plans for more details.

Archiving Streams ​

cs
session.Events.ArchiveStream(streamId);
session.Events.UnArchiveStream(streamId);
await session.SaveChangesAsync();

Archiving sets is_archived on fi_streams. The events stay; the stream is simply marked as no longer live.

What archiving affects ​

  • An archived stream refuses further appends, with JasperFx.Events.ArchivedStreamException — the type Marten and Polecat throw too, so a store-agnostic catch works on all three. Archiving is not a soft delete you can keep writing through; unarchive it first if that is really the intent.
  • A natural key no longer resolves an archived stream. The lookup joins fi_streams, so the flag is read off the join rather than being copied.
  • An archived stream is excluded from the explorer's recent-streams read.
  • Archived events are left out of event reads unless you opt in. The events stay in fi_events, but FetchStreamAsync, QueryEventsAsync, QueryEventData<T>, QueryRawEvents(), live aggregation and the async daemon all read past them. See Reading archived events.
  • LoadAsync(eventId) still returns an archived event, with IsArchived set, because naming one event by its id is asking for it.
  • FetchStreamStateAsync and QueryStreamStates() still answer for the stream, with IsArchived set.

WARNING

Starting a stream over an archived id is still a collision, not an archive refusal — you get ExistingStreamIdCollisionException. An archived id is an id in use, and a caller who reused one needs a different id rather than an unarchive.

Unarchiving ​

UnArchiveStream(Guid) and UnArchiveStream(string) are members of the shared JasperFx.Events.IEventStoreOperations, so store-agnostic code can call them as well as session.Events. Once the unarchive is saved, the stream takes appends again, at the version it had, and its events come back into the default reads. Unarchiving a stream that is not archived, or that does not exist, does nothing. Under conjoined tenancy only the session's tenant's copy is reopened.

WARNING

Save the unarchive before you append. Fisher checks every stream an append touches before it writes the batch, so an unarchive and an append to the same stream in one SaveChangesAsync is refused with ArchivedStreamException, and the unarchive is rolled back with it. The shared contract leaves this case open.

Reading archived events ​

Marten and Polecat filter archived events out of their reads, and Fisher follows the same rule: you have to ask for them. There are two ways to ask, both in a predicate over IEvent:

cs
// Live and archived events together. MaybeArchived() is in Fisher.Events.Archiving.
var everything = await session.Events.QueryEventsAsync(
    x => x.MaybeArchived() && x.StreamId == streamId, token);

// Naming IsArchived replaces the implicit filter, so this finds only archived events...
var archived = await session.Events.QueryEventsAsync(x => x.IsArchived, token);

// ...and this finds only live ones.
var live = await session.Events.QueryEventsAsync(x => !x.IsArchived, token);

snippet source | anchor

QueryRawEvents() takes the same predicates, and EventQuery has no opt-in. FetchStreamAsync has no opt-in either, as on Marten, so read an archived stream through one of the predicates above. Neither do QueryEventData<T> and QueryEventDataAsync<T>, because those predicates are over the event body, which cannot speak for the row. An IsArchived member on the body itself has no effect on archiving.

What this means for code built on those reads:

  • AggregateStreamAsync folds an archived stream as a stream with no events: null, or the state you passed in. AggregateStreamToLastKnownAsync and FetchLatest on a live aggregate return null too.
  • FetchForWriting returns a null Aggregate with the stream's real version, and an append through it is refused with ArchivedStreamException at SaveChangesAsync.
  • RebuildSingleStreamAsync deletes the projected document, as a full rebuild leaves it gone.
  • In Fisher.AspNetCore, StreamEvents and StreamAggregate answer 404, and StreamEventState still answers 200 with isArchived set.

Masking and compacting reach archived events through reads of their own, and TombstoneStream removes them. UnArchiveStream returns them to the default reads. The IEventStore explorer's ReadStreamAsync is a diagnostic read and shows them, as it does on Marten and Polecat.

Archiving through an Archived event ​

A single stream projection that owns the stream archives it when it sees JasperFx.Events.Archived, inline or through the daemon:

cs
session.Events.Append(streamId, new Archived("Closed out"));
await session.SaveChangesAsync();

"Owns" is the operative word: only a projection with a snapshot for that stream — either one it loaded or one this slice produced — archives it, so sibling projections in a composite do not fire phantom archives.

TIP

The direct operation is Fisher's own route and needs no projection at all, which is why its natural key tables carry no is_archived column: Polecat copies the flag and keeps it in sync from a projection watching for the event, which then needs a second, rebuild-time entry point — because a daemon rebuild replays events without appending streams and would otherwise leave the table empty after teardown. Nothing here watches for anything, so there is nothing to repopulate.

Deleting a stream with TombstoneStream ​

Archiving keeps everything. TombstoneStream is the opposite: a hard delete of the stream and every event in it. Use ArchiveStream for a stream that is merely finished, and TombstoneStream when the data has to be gone, for example a stream started in error or a purge that a retention or erasure policy requires.

TIP

A tombstone deletes the stream's rows from the live file and nothing else. Projected documents, backups and the file's free pages keep what they had. For a GDPR erasure request, see Personal Data and GDPR Erasure.

cs
await using var session = store.LightweightSession();

// Queued like any other operation: nothing is deleted until SaveChangesAsync.
session.Events.TombstoneStream(streamId);

// Deletes the stream's tag rows, then its events, then its fi_streams row, in this
// session's tenant and in one transaction. A stream that does not exist is a no-op.
await session.SaveChangesAsync(token);

snippet source | anchor

There is a TombstoneStream(string) twin for string-identified streams. What it does:

  • It is queued until SaveChangesAsync, like an append. Nothing is deleted when you call it, and it commits or rolls back with the rest of the session's unit of work.
  • The tag rows go first. Each DCB tag table (fi_event_tag_*) has a real foreign key to fi_events(seq_id), and the connection profile Fisher uses (Weasel's default) turns SQLite's foreign key enforcement on. So the operation deletes the stream's tag rows, then its events in fi_events, then its row in fi_streams. Deleting the events first would fail the whole unit of work with FOREIGN KEY constraint failed.
  • It is tenant-scoped. Every delete is filtered on the session's tenant, so under conjoined tenancy a stream with the same id in another tenant is untouched.
  • A missing stream is a no-op. Tombstoning an id that does not exist, or no longer exists, deletes nothing and does not throw.
  • Sequence numbers are not reused. fi_events.seq_id is AUTOINCREMENT, so the deleted events' sequence numbers stay spent and the next append continues above them. An async projection's high-water mark never ends up above an event it has not seen. Expect EventSequenceNumber to exceed EventCount in the statistics afterwards.
  • Projected documents are left alone. A snapshot, or a document an inline or async projection built from the stream, stays where it is. Delete it yourself if it must go too, or rebuild the projection.

After the commit, FetchStreamStateAsync returns null and FetchStreamAsync returns nothing for that id. The id is free again, so a later StartStream with it starts a brand new stream.

Store-neutral code ​

TombstoneStream(Guid) and TombstoneStream(string) are members of the shared JasperFx.Events.IEventStoreOperations as of JasperFx 2.90.0 (jasperfx#1014). Code that holds a session only as JasperFx.Events.Documents.IDocumentSessionOperations can therefore call it without knowing which store it is talking to:

cs
// Written against JasperFx.Events alone: IDocumentSessionOperations.Events is the shared
// IEventStoreOperations, so the same purge compiles against a Fisher, Marten or Polecat session.
public static async Task PurgeAsync(IDocumentSessionOperations session, Guid streamId,
    CancellationToken token)
{
    session.Events.TombstoneStream(streamId);
    await session.SaveChangesAsync(token);
}

snippet source | anchor

On the shared contract the members default to throwing NotSupportedException, so a store that has not implemented them fails loudly instead of skipping the delete. Fisher implements both, and runs the shared StreamTombstoningCompliance suite against them.

Archiving is not deletion ​

The events are still there and still occupy space. If you want them gone, the options are:

WantUse
The stream's history collapsed to one snapshot eventStream compacting
Protected information removed from event bodiesEvent data masking
One stream and its events goneTombstoneStream
Everything goneDeleteAllEventDataAsync

WARNING

Deleting events is safe only because fi_events.seq_id is AUTOINCREMENT. A bare INTEGER PRIMARY KEY aliases the rowid, which SQLite reuses after a delete, and a reused sequence below the daemon's high-water mark is an event no async projection would ever see.

Archiving is not erasure

Neither archiving nor any row in the table above erases personal data. Each one leaves a copy somewhere: in projections, in backups, or in the database file's free pages. The Critter Stack's answer to a GDPR erasure request is crypto-shredding with Tayra. See Personal Data and GDPR Erasure.

Archiving and projections ​

An archived stream's events are unchanged, so a projection that already folded them keeps what it derived. Archiving is a statement about the stream, not a correction to anything built from it — if you need a projection to forget it, rebuild the projection.

Statistics ​

Archived and compacted streams are why EventSequenceNumber can exceed EventCount:

cs
var stats = await store.Advanced.FetchEventStoreStatisticsAsync();

See Event Storage.

Released under the MIT License.