Persistence and restart recovery
Without a store, tables live in process memory and vanish when the server exits. Give
createServer a store and every table survives a restart: players who come back within the
grace period find their seats as they left them.
Choose a store
Section titled “Choose a store”| Adapter | Use it for |
|---|---|
memoryStore() |
Development and tests. The default. Lost on exit. |
sqliteStore(options) |
One server with a local disk. The simplest durable choice. |
postgresStore(options) |
A managed database, backups, several apps on one database. |
redisStore(options) |
An existing Redis that runs with AOF persistence. |
Install the driver next to shoehive (better-sqlite3, pg or ioredis). Each adapter
loads its driver only when you import its subpath, such as shoehive/store/sqlite. Options,
durability settings and table layouts are on the Stores reference.
const shoehive = createServer({ games: [ticTacToe], store: sqliteStore({ file: './shoehive.db' }), snapshotEvery: 100, // also on every phase change and when a table ends reconnectGraceMs: 60_000, // how long recovered players have to come back});
shoehive.on('table:recovered', ({ table }) => { console.log(`recovered ${table}`);});shoehive.on('table:recovery-failed', ({ table, reason }) => { // The table stays in the store, closed to players. Fix the cause, then restart. console.error(`could not recover ${table}: ${reason}`);});For Postgres, build the pool yourself and run migratePostgres(pool) from a deploy step if
the app's role has no rights to create tables. Otherwise the store creates its schema on
first use. Run one server process per store namespace: two writers on one log conflict.
An action is acknowledged only after the store has written it, so an ack means durable. How hard the write is flushed depends on the adapter's settings (see the reference).
What happens on restart
Section titled “What happens on restart”Before the server accepts connections it recovers every open table:
- It loads the table's latest snapshot and the log entries after it.
- It replays those entries with the same code that powers tests, so the state matches the live run exactly. Your wallet and validators are not called.
- It re-arms timers from their recorded deadlines. A deadline that passed while the server was down fires right away.
- It marks every seated player disconnected and starts a fresh reconnect grace period
(
reconnectGraceMs, 60 seconds by default). Players who reconnect with their resume token in that time are back in their seats. - It re-sends wallet operations that were not confirmed (see Wallets and real-money safety).
shoehive.ready resolves when recovery is done. A table that cannot be recovered is not
opened. The server emits table:recovery-failed with a reason and carries on with the
others. The common reasons are UNKNOWN_GAME (the game is not in games),
VERSION_MISMATCH and REPLAY_DIVERGED.
Snapshots are written every snapshotEvery log entries (100 by default), on every phase
change and when a table ends. They bound how much log is replayed after a crash.
Shut down gracefully
Section titled “Shut down gracefully”close() waits for each table's queue to drain, writes a final snapshot of every table, then
disconnects clients with close code 1001. After a graceful stop there is nothing to replay.
// Graceful by default: queues drain and every table gets a final snapshot.for (const signal of ['SIGINT', 'SIGTERM'] as const) { process.once(signal, () => { void shoehive.close().then(() => process.exit(0)); });}close({ graceful: false }) skips the snapshots and drops everything at once, like a crash.
Use it to test recovery.
Test recovery
Section titled “Test recovery”Start a second server over the same store. Pass the same store object, or a new one pointing at the same storage.
it('brings a table back after a crash', async () => { const store = memoryStore(); // a durable store works the same way const first = createServer({ games: [ticTacToe], store }); const { id } = await first.tables.create('tic-tac-toe'); await first.close({ graceful: false }); // like kill -9: no final snapshot
const second = createServer({ games: [ticTacToe], store }); await second.ready; // recovery finishes before this resolves expect(second.tables.get(id)?.game).toBe('tic-tac-toe'); await second.close();});Change a game that has live tables
Section titled “Change a game that has live tables”defineGame({ version }) is a positive integer (default 1) that snapshots record. Bump it
when a change could make an old log replay differently, such as a new state shape. A table
stored under another version is not recovered: it reports VERSION_MISMATCH, and stays
in the store untouched, so you can deploy the old version again to finish those games.
Plan deploys around this: drain tables (let games end, or close them) before you bump the version.
When a table is faulted
Section titled “When a table is faulted”If the store rejects a write, the server throws away that action's in-memory change, the
player gets an INTERNAL error, and the table rejects further actions with
TABLE_UNAVAILABLE. Fix the cause (a full disk, a lost connection), then reload the table
from the store:
await shoehive.tables.reload('tbl_abc');reload rebuilds the table from its snapshot and log, and sends connected players a fresh
snapshot. If your adapter reports a StoreConflictError, another writer is using the same
namespace, so stop it before reloading.
Related
Section titled “Related”- Stores reference: every option and durability setting.
- Writing a store adapter: support another database.
