Table of Contents

Persistence

Keep entities in an in-memory store backed by a durable binary snapshot plus a journal, so state survives a restart.

What you'll build

A standalone demo of SquidStd.Persistence: a Player store that loads existing state on startup, appends every change to a journal, and captures a snapshot. Run it twice - the second run reloads what the first saved.

Prerequisites

  • .NET 10 SDK
  • dotnet add package SquidStd.Persistence (and SquidStd.Persistence.MessagePack for the binary serializer)

Steps

1. Initialize and load existing state

InitializeAsync replays the snapshot and journal from the save directory; GetStore<T, TKey> returns the typed store for an entity registered in the PersistenceEntityRegistry.


var persistence = BuildPersistence();
await persistence.InitializeAsync();

var players = persistence.GetStore<Player, int>();

Console.WriteLine($"Loaded {await players.CountAsync()} player(s) from {saveDir}");

foreach (var existing in await players.GetAllAsync())
{
    Console.WriteLine($"  - #{existing.Id} {existing.Name} (level {existing.Level})");
}

2. Mutate the store

Every UpsertAsync / RemoveAsync is appended to the journal, so the change is durable before the next snapshot.


var nextId = await players.CountAsync() + 1;
await players.UpsertAsync(new() { Id = nextId, Name = $"Hero-{nextId}", Level = nextId * 10 });

Console.WriteLine($"Added player #{nextId}; store now holds {await players.CountAsync()} player(s)");

3. Snapshot and trim the journal

SaveSnapshotAsync captures the full state and trims the journal. Re-run the sample to see the state reload.


await persistence.SaveSnapshotAsync();
Console.WriteLine("Snapshot saved. Re-run this sample to see the state reload.");

Run it

dotnet run --project samples/SquidStd.Samples.Persistence
dotnet run --project samples/SquidStd.Samples.Persistence   # reloads the saved state

Next steps

Edit this page