Stores
A store keeps each table's action log, its latest snapshot and guest sessions, so tables survive a restart of the server process (ADR 0009). On startup the server lists the open tables, loads each snapshot and replays the log after it. Players who resume within the reconnect grace period land back in their seats.
Pass one to createServer({ store }). Without one, the server uses memoryStore(), which
keeps everything in process memory and loses it on exit.
| Adapter | Import | Driver (optional peer) | Good for |
|---|---|---|---|
memoryStore() |
shoehive/store/memory |
none | development and tests |
sqliteStore(options) |
shoehive/store/sqlite |
better-sqlite3 |
a single server with a local disk |
postgresStore(options) |
shoehive/store/postgres |
pg |
managed databases, backups, several apps on one DB |
redisStore(options) |
shoehive/store/redis |
ioredis |
an existing Redis with AOF persistence |
Install the driver next to shoehive, for example npm install shoehive better-sqlite3.
Each adapter only loads its driver when you import its subpath.
An ack means durable. The server acknowledges an action only after the store has written its log entry. How durable that write is depends on the adapter's settings, below.
SQLite
Section titled “SQLite”import { createServer } from 'shoehive/server';import { sqliteStore } from 'shoehive/store/sqlite';
const shoehive = createServer({ games, store: sqliteStore({ file: './shoehive.db' }) });- With
{ file }, the store opens the file in WAL mode withsynchronous = FULL: every acknowledged action survives a process crash and a power loss.close()closes the file. - With
{ database }, pass abetter-sqlite3connection you own. Its pragmas are left as you set them (WAL is recommended;synchronous = NORMALwith WAL can lose the last transactions on a power loss, not on a process crash), andclose()leaves it open. - Group commit. better-sqlite3 runs on the server's thread, so every commit waits for its fsync there. Writes made in the same turn of the event loop (log appends, snapshots, closes and sessions, across all tables) are committed in one transaction, and each resolves after that commit, so one fsync covers them all and an ack still means durable. Each table's batch is still all or nothing, and one table's conflict does not fail another table's append. If the transaction itself fails, for example because another process holds the write lock past the busy timeout, every write in that group rejects.
- Capacity. In the Phase 8 load test (4 vCPU, see benchmarks),
1,000 Hold'em tables at 1 action per second each (about 845 actions per second) kept the p95
action-to-patch latency at 9.16 ms with
synchronous = FULL, and 9.61 ms withsynchronous = NORMAL. Past that, the single server thread is the limit, whichever store you use. tablePrefix(default'shoehive_') lets several apps share one file.- Tables:
<prefix>entries,<prefix>snapshots,<prefix>sessions,<prefix>open_tablesand<prefix>meta(schema version).
Postgres
Section titled “Postgres”import pg from 'pg';import { createServer } from 'shoehive/server';import { migratePostgres, postgresStore } from 'shoehive/store/postgres';
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });await migratePostgres(pool); // optional: otherwise the store creates its tables on first useconst shoehive = createServer({ games, store: postgresStore({ pool }) });- You construct the pool, so you control pooling, TLS and credentials.
close()never ends it; end it yourself on shutdown. schema(defaultpublic) andtablePrefix(default none) isolate apps or tenants. The schema can be up to 63 bytes and the prefix up to 52, because Postgres silently truncates longer names (two of the store's tables would become one); the store throws aTypeErrorfor longer names, an empty schema or a NUL character.- Without
migratePostgres, the store creates its schema lazily and idempotently before the first operation (concurrent setups are serialized with an advisory lock). RunmigratePostgresfrom a deploy step if the app's role has no DDL rights. - JSON is stored as
text, notjsonb, so it round-trips byte for byte. Ids must not contain a NUL character (Postgrestextcannot hold one).
import { Redis } from 'ioredis';import { createServer } from 'shoehive/server';import { redisStore } from 'shoehive/store/redis';
const client = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379');const shoehive = createServer({ games, store: redisStore({ client }) });- Run Redis with AOF (
appendonly yes). Withappendfsync alwaysevery acknowledged action is on disk; witheverysec(the usual choice) a crash of the Redis host can lose up to a second of actions; withnoor without AOF, a Redis restart loses tables. Replication is asynchronous and does not replace AOF. prefix(default'shoehive:') namespaces the keys. Do not nest prefixes (app:andapp:log:overlap). Ids are stored as given.- Redis Cluster is not supported (snapshot and close touch several keys).
close()leaves the client connected; quit it yourself on shutdown.
Retries and conflicts
Section titled “Retries and conflicts”appendLog is all or nothing. A table's log starts at seq 0 and every entry must follow the
last stored one. If another writer got there first (for example two server processes on one
database), the append rejects with StoreConflictError and the server faults that table
until shoehive.tables.reload(id). Run one server process per store namespace.
A batch whose entries are all already stored with identical data succeeds without writing, so a driver that re-sends a command after a lost reply (ioredis does by default) does not fault the table.
Writing your own adapter
Section titled “Writing your own adapter”Implement the Store interface (exported from shoehive/server and every adapter) and run
the conformance suite from shoehive/testing with your test runner. Pass a backend that can
reopen the same storage so the suite also checks durability across a restart:
import { describe, expect, it } from 'vitest';import { runStoreConformance } from 'shoehive/testing';import { myStore } from './my-store';
runStoreConformance( async () => { const namespace = await createEmptyNamespace(); return { open: () => myStore({ namespace }), // called again after close(): must see old data destroy: () => dropNamespace(namespace), }; }, { describe, it, expect },);The suite checks ordering, conflicts and their fields, atomic batches, concurrent writers,
idempotent retries, snapshots and tails, open and closed tables (a snapshot saved after
closeTable does not reopen a table), sessions, 1 MiB payloads, exact round-trips of
unusual JSON and ids, and data surviving close and reopen.
