Skip to content

shoehive/store/postgres

shoehive/store/postgres: the Postgres Store adapter (ADR 0009), built on pg, an optional peer dependency (npm install pg). You construct the pool, so you control pooling, TLS and credentials; the store borrows it and never ends it.

import pg from 'pg';
import { createServer } from 'shoehive/server';
import { postgresStore } from 'shoehive/store/postgres';
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
const server = createServer({ games, secret, store: postgresStore({ pool }) });
await server.listen({ port: 8080 });
// On shutdown: close the server (which closes the store), then end your pool.
await server.close();
await pool.end();

The store creates its tables on first use (CREATE TABLE IF NOT EXISTS, skipped when they already exist). To create them ahead of time, for example from a deploy step with a role that has DDL rights, call migratePostgres with the same options.

Schema, in schema (default public), each table name prefixed with tablePrefix:

  • entries (table_id, seq, data): the append-only logs, primary key (table_id, seq).
  • snapshots (table_id, seq, rev, game, version, data): the latest snapshot per table.
  • sessions (player_id, name, metadata, updated_at): player sessions.
  • open_tables (table_id, open, closed_reason, closed_at): whether a table is open. Closed tables are kept; deleting them is up to you.

JSON is stored as text, not jsonb, so it round-trips exactly (jsonb reorders keys and rejects the \u0000 escape). Postgres text cannot hold a NUL character, so table and player ids must not contain one (JSON text never does: it escapes NUL).

Re-exports SessionRecord


Re-exports Store


Re-exports StoreConflictError


Re-exports StoredEntry


Re-exports StoredSnapshot