@kyneta/postgres-store 1.8.0 → 2.0.0

package/src/index.ts

@@ -1,8 +1,8 @@
 // Postgres Store backend.
 //
 // Why JSONB on meta, not TEXT: operators occasionally need to filter
-// metas by `syncProtocol` or `replicaType` during incident
-// investigations, and JSONB makes `data->>'syncProtocol'` trivial.
+// metas by `syncMode` or `replicaType` during incident
+// investigations, and JSONB makes `data->>'syncMode'` trivial.
 // Cost: JSONB normalizes whitespace and key order at insert time, so
 // `meta.data` bytes don't match SQLite's TEXT-stored meta — but
 // round-trip through `loadAll` still yields a structurally equal
@@ -11,8 +11,12 @@
 
 import {
   type DocId,
+  decideStoreFormat,
+  parseStoreFormat,
   SeqNoTracker,
+  STORE_META_FORMAT_KEY,
   type Store,
+  StoreFormatVersionError,
   type StoreMeta,
   type StoreRecord,
 } from "@kyneta/exchange"
@@ -22,6 +26,7 @@ import {
   planReplace,
   type RowShape,
   resolveTables,
+  STORE_FORMAT_VERSION,
   type TableNames,
 } from "@kyneta/sql-store-core"
 import type { Client, Pool, PoolClient } from "pg"
@@ -32,24 +37,101 @@ import type { Client, Pool, PoolClient } from "pg"
 
 export interface PostgresStoreOptions {
   /**
-   * Override the default table names (`kyneta_meta` and `kyneta_records`).
+   * Override the default table names (`kyneta_doc_meta`, `kyneta_records`,
+   * `kyneta_store_meta`).
    *
    * Use when running multiple isolated Exchange instances against the
-   * same database — each instance owns one `tables` pair.
+   * same database — each instance owns one `tables` set.
    */
   tables?: Partial<TableNames>
 }
 
-type PgConnection = Client | Pool
-
 /**
  * Narrow structural type for the methods we actually call. Keeps the
  * package independent of `pg`'s top-level type changes across versions.
  */
-interface PgQuerier {
+export interface PgQuerier {
   query<R = unknown>(text: string, values?: unknown[]): Promise<{ rows: R[] }>
 }
 
+/**
+ * The minimal Postgres capability `PostgresStore` needs, decoupled from any
+ * specific pg surface — mirrors `SqliteAdapter`. `fromPool` / `fromClient`
+ * supply it, so `PostgresStore` never discriminates connection types and `pg`
+ * stays a type-only import (no `instanceof`, no runtime class coupling).
+ */
+export interface PgAdapter extends PgQuerier {
+  /**
+   * Run `fn` with a querier whose statements share one connection under
+   * BEGIN/COMMIT; ROLLBACK and rethrow on failure.
+   */
+  transaction<R>(fn: (q: PgQuerier) => Promise<R>): Promise<R>
+}
+
+/**
+ * Adapter over a `Pool`: each transaction checks out a `PoolClient` so
+ * BEGIN..COMMIT share one physical connection (Postgres transactions are
+ * connection-scoped — checking back out for COMMIT would target a different
+ * connection), then releases it. Non-transactional queries go to the pool
+ * directly (the pool checks out/in per query — fine for single reads).
+ */
+export function fromPool(pool: Pool): PgAdapter {
+  const direct = pool as unknown as PgQuerier
+  return {
+    query<R = unknown>(
+      text: string,
+      values?: unknown[],
+    ): Promise<{ rows: R[] }> {
+      return direct.query<R>(text, values)
+    },
+    async transaction<R>(fn: (q: PgQuerier) => Promise<R>): Promise<R> {
+      const poolClient: PoolClient = await pool.connect()
+      const q = poolClient as unknown as PgQuerier
+      try {
+        await q.query("BEGIN")
+        try {
+          const result = await fn(q)
+          await q.query("COMMIT")
+          return result
+        } catch (e) {
+          await q.query("ROLLBACK")
+          throw e
+        }
+      } finally {
+        poolClient.release()
+      }
+    },
+  }
+}
+
+/**
+ * Adapter over a single `Client` (or an already-checked-out `PoolClient`):
+ * transactions run inline on the one connection. Re-throws on rollback so a
+ * caller can place post-commit work lexically after the awaited call.
+ */
+export function fromClient(client: Client | PoolClient): PgAdapter {
+  const q = client as unknown as PgQuerier
+  return {
+    query<R = unknown>(
+      text: string,
+      values?: unknown[],
+    ): Promise<{ rows: R[] }> {
+      return q.query<R>(text, values)
+    },
+    async transaction<R>(fn: (q: PgQuerier) => Promise<R>): Promise<R> {
+      await q.query("BEGIN")
+      try {
+        const result = await fn(q)
+        await q.query("COMMIT")
+        return result
+      } catch (e) {
+        await q.query("ROLLBACK")
+        throw e
+      }
+    },
+  }
+}
+
 // ---------------------------------------------------------------------------
 // PostgresStore
 // ---------------------------------------------------------------------------
@@ -62,64 +144,15 @@ interface PgQuerier {
  * curated error rather than per-method `column does not exist` later.
  */
 export class PostgresStore implements Store {
-  readonly #client: PgConnection
+  readonly #adapter: PgAdapter
   readonly #seqNos = new SeqNoTracker()
   readonly #tables: TableNames
 
-  constructor(client: PgConnection, options: PostgresStoreOptions = {}) {
-    this.#client = client
+  constructor(adapter: PgAdapter, options: PostgresStoreOptions = {}) {
+    this.#adapter = adapter
     this.#tables = resolveTables(options)
   }
 
-  /**
-   * For `Pool`: check out a `PoolClient` so BEGIN..COMMIT all run on
-   * the same physical connection (Postgres transactions are
-   * connection-scoped; checking back out for COMMIT would target a
-   * different connection). For `Client`: run inline.
-   *
-   * Re-throws on rollback so callers can put post-commit work
-   * lexically after the awaited call — a rejection skips the next
-   * statement, mirroring sync `transaction()` + throw.
-   */
-  async #withTransaction<R>(
-    fn: (querier: PgQuerier) => Promise<R>,
-  ): Promise<R> {
-    const isPool = typeof (this.#client as Pool).connect === "function"
-    if (isPool) {
-      const poolClient: PoolClient = await (this.#client as Pool).connect()
-      try {
-        await poolClient.query("BEGIN")
-        try {
-          const result = await fn(poolClient as unknown as PgQuerier)
-          await poolClient.query("COMMIT")
-          return result
-        } catch (e) {
-          await poolClient.query("ROLLBACK")
-          throw e
-        }
-      } finally {
-        poolClient.release()
-      }
-    }
-    const client = this.#client as Client
-    await client.query("BEGIN")
-    try {
-      const result = await fn(client as unknown as PgQuerier)
-      await client.query("COMMIT")
-      return result
-    } catch (e) {
-      await client.query("ROLLBACK")
-      throw e
-    }
-  }
-
-  // Non-transactional reads (currentMeta, loadAll, listDocIds, the
-  // cold-start MAX(seq)) don't need a held connection — issuing them
-  // against the pool/client directly avoids unnecessary checkouts.
-  get #q(): PgQuerier {
-    return this.#client as unknown as PgQuerier
-  }
-
   // -------------------------------------------------------------------------
   // Store interface
   // -------------------------------------------------------------------------
@@ -127,7 +160,7 @@ export class PostgresStore implements Store {
   async append(docId: DocId, record: StoreRecord): Promise<void> {
     const existingMeta = await this.currentMeta(docId)
     const seq = await this.#seqNos.next(docId, async () => {
-      const result = await this.#q.query<{ max_seq: number | null }>(
+      const result = await this.#adapter.query<{ max_seq: number | null }>(
         `SELECT MAX(seq)::int AS max_seq FROM ${this.#tables.records} WHERE doc_id = $1`,
         [docId],
       )
@@ -136,10 +169,10 @@ export class PostgresStore implements Store {
 
     const plan = planAppend(docId, record, existingMeta, seq)
 
-    await this.#withTransaction(async q => {
+    await this.#adapter.transaction(async q => {
       if (plan.upsertMeta !== null) {
         await q.query(
-          `INSERT INTO ${this.#tables.meta} (doc_id, data)
+          `INSERT INTO ${this.#tables.docMeta} (doc_id, data)
            VALUES ($1, $2::jsonb)
            ON CONFLICT (doc_id) DO UPDATE SET data = EXCLUDED.data`,
           [docId, plan.upsertMeta.data],
@@ -156,7 +189,7 @@ export class PostgresStore implements Store {
   }
 
   async *loadAll(docId: DocId): AsyncIterable<StoreRecord> {
-    const result = await this.#q.query<RowShape>(
+    const result = await this.#adapter.query<RowShape>(
       `SELECT kind, payload, blob FROM ${this.#tables.records}
        WHERE doc_id = $1 ORDER BY seq`,
       [docId],
@@ -170,7 +203,7 @@ export class PostgresStore implements Store {
     const existingMeta = await this.currentMeta(docId)
     const plan = planReplace(records, existingMeta)
 
-    await this.#withTransaction(async q => {
+    await this.#adapter.transaction(async q => {
       await q.query(`DELETE FROM ${this.#tables.records} WHERE doc_id = $1`, [
         docId,
       ])
@@ -185,7 +218,7 @@ export class PostgresStore implements Store {
       }
 
       await q.query(
-        `INSERT INTO ${this.#tables.meta} (doc_id, data)
+        `INSERT INTO ${this.#tables.docMeta} (doc_id, data)
          VALUES ($1, $2::jsonb)
          ON CONFLICT (doc_id) DO UPDATE SET data = EXCLUDED.data`,
         [docId, plan.upsertMeta.data],
@@ -200,11 +233,11 @@ export class PostgresStore implements Store {
   }
 
   async delete(docId: DocId): Promise<void> {
-    await this.#withTransaction(async q => {
+    await this.#adapter.transaction(async q => {
       await q.query(`DELETE FROM ${this.#tables.records} WHERE doc_id = $1`, [
         docId,
       ])
-      await q.query(`DELETE FROM ${this.#tables.meta} WHERE doc_id = $1`, [
+      await q.query(`DELETE FROM ${this.#tables.docMeta} WHERE doc_id = $1`, [
         docId,
       ])
     })
@@ -212,8 +245,8 @@ export class PostgresStore implements Store {
   }
 
   async currentMeta(docId: DocId): Promise<StoreMeta | null> {
-    const result = await this.#q.query<{ data: StoreMeta }>(
-      `SELECT data FROM ${this.#tables.meta} WHERE doc_id = $1`,
+    const result = await this.#adapter.query<{ data: StoreMeta }>(
+      `SELECT data FROM ${this.#tables.docMeta} WHERE doc_id = $1`,
       [docId],
     )
     return result.rows[0]?.data ?? null
@@ -221,8 +254,8 @@ export class PostgresStore implements Store {
 
   async *listDocIds(prefix?: string): AsyncIterable<DocId> {
     if (prefix === undefined) {
-      const result = await this.#q.query<{ doc_id: string }>(
-        `SELECT doc_id FROM ${this.#tables.meta}`,
+      const result = await this.#adapter.query<{ doc_id: string }>(
+        `SELECT doc_id FROM ${this.#tables.docMeta}`,
       )
       for (const row of result.rows) yield row.doc_id
       return
@@ -233,12 +266,12 @@ export class PostgresStore implements Store {
     const upper = prefixUpperBound(prefix)
     const result =
       upper === null
-        ? await this.#q.query<{ doc_id: string }>(
-            `SELECT doc_id FROM ${this.#tables.meta} WHERE doc_id >= $1`,
+        ? await this.#adapter.query<{ doc_id: string }>(
+            `SELECT doc_id FROM ${this.#tables.docMeta} WHERE doc_id >= $1`,
             [prefix],
           )
-        : await this.#q.query<{ doc_id: string }>(
-            `SELECT doc_id FROM ${this.#tables.meta}
+        : await this.#adapter.query<{ doc_id: string }>(
+            `SELECT doc_id FROM ${this.#tables.docMeta}
              WHERE doc_id >= $1 AND doc_id < $2`,
             [prefix, upper],
           )
@@ -284,12 +317,60 @@ function prefixUpperBound(prefix: string): string | null {
  * on the next write anyway.
  */
 export async function createPostgresStore(
-  client: PgConnection,
+  adapter: PgAdapter,
   options: PostgresStoreOptions = {},
 ): Promise<Store> {
   const tables = resolveTables(options)
-  await validateSchema(client as unknown as PgQuerier, tables)
-  return new PostgresStore(client, options)
+  await validateSchema(adapter, tables)
+  await assertFormat(adapter, tables)
+  return new PostgresStore(adapter, options)
+}
+
+/**
+ * Bootstrap reader: stamp/accept/refuse the store-format marker on open.
+ * Writes at most one idempotent row (`ON CONFLICT DO NOTHING`) — not DDL,
+ * so the "no auto-DDL" invariant holds; the operator still owns the table.
+ */
+async function assertFormat(q: PgQuerier, tables: TableNames): Promise<void> {
+  const markerResult = await q.query<{ value: unknown }>(
+    `SELECT value FROM ${tables.storeMeta} WHERE key = $1`,
+    [STORE_META_FORMAT_KEY],
+  )
+  const raw = markerResult.rows[0]?.value
+  const parsed = raw === undefined ? null : parseStoreFormat(raw)
+  if (parsed === "malformed") {
+    throw new StoreFormatVersionError({
+      reason: "malformed-version",
+      backend: "postgres",
+      stored: null,
+      current: STORE_FORMAT_VERSION,
+    })
+  }
+
+  const dataResult = await q.query(`SELECT 1 FROM ${tables.docMeta} LIMIT 1`)
+
+  const decision = decideStoreFormat({
+    current: STORE_FORMAT_VERSION,
+    stored: parsed,
+    storeHasData: dataResult.rows.length > 0,
+  })
+
+  if (decision.action === "refuse") {
+    throw new StoreFormatVersionError({
+      reason: decision.reason,
+      backend: "postgres",
+      stored: parsed,
+      current: STORE_FORMAT_VERSION,
+    })
+  }
+  if (decision.action === "stamp") {
+    await q.query(
+      `INSERT INTO ${tables.storeMeta} (key, value)
+       VALUES ($1, $2::jsonb)
+       ON CONFLICT (key) DO NOTHING`,
+      [STORE_META_FORMAT_KEY, JSON.stringify(decision.value)],
+    )
+  }
 }
 
 interface ColumnInfo {
@@ -299,7 +380,7 @@ interface ColumnInfo {
 }
 
 const EXPECTED_COLUMNS = {
-  meta: [
+  docMeta: [
     { name: "doc_id", types: ["text"] },
     { name: "data", types: ["jsonb"] },
   ],
@@ -310,12 +391,17 @@ const EXPECTED_COLUMNS = {
     { name: "payload", types: ["text"] },
     { name: "blob", types: ["bytea"] },
   ],
+  storeMeta: [
+    { name: "key", types: ["text"] },
+    { name: "value", types: ["jsonb"] },
+  ],
 } as const
 
 async function validateSchema(q: PgQuerier, tables: TableNames): Promise<void> {
   for (const [role, expected] of [
-    ["meta", EXPECTED_COLUMNS.meta] as const,
+    ["docMeta", EXPECTED_COLUMNS.docMeta] as const,
     ["records", EXPECTED_COLUMNS.records] as const,
+    ["storeMeta", EXPECTED_COLUMNS.storeMeta] as const,
   ]) {
     const tableName = tables[role]
     const result = await q.query<ColumnInfo>(