@syncular/server-dialect-postgres 0.0.1 → 0.0.2-127

package/src/index.ts

@@ -12,52 +12,47 @@
  */
 
 import type { ScopeValues, StoredScopes, SyncOp } from '@syncular/core';
-import type { DbExecutor, ServerSyncDialect } from '@syncular/server';
-import type {
-  SyncChangeRow,
-  SyncCommitRow,
-  SyncCoreDb,
-} from '@syncular/server/schema';
-import type { Kysely, Transaction } from 'kysely';
+import type { DbExecutor } from '@syncular/server';
+import {
+  BaseServerSyncDialect,
+  coerceIsoString,
+  coerceNumber,
+  type IncrementalPullRow,
+  type IncrementalPullRowsArgs,
+  parseScopes,
+} from '@syncular/server';
+import type { SyncChangeRow, SyncCoreDb } from '@syncular/server/schema';
+import type { Kysely, RawBuilder, Transaction } from 'kysely';
 import { sql } from 'kysely';
 
-function coerceNumber(value: unknown): number | null {
-  if (value === null || value === undefined) return null;
-  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
-  if (typeof value === 'bigint')
-    return Number.isFinite(Number(value)) ? Number(value) : null;
-  if (typeof value === 'string') {
-    const n = Number(value);
-    return Number.isFinite(n) ? n : null;
-  }
-  return null;
+function isActiveTransaction<DB extends SyncCoreDb>(
+  db: Kysely<DB>
+): db is Kysely<DB> & Transaction<DB> {
+  return (db as { isTransaction?: boolean }).isTransaction === true;
 }
 
-function coerceIsoString(value: unknown): string {
-  if (typeof value === 'string') return value;
-  if (value instanceof Date) return value.toISOString();
-  return String(value);
+function createSavepointName(): string {
+  const randomPart = Math.floor(Math.random() * 1_000_000_000).toString(36);
+  return `syncular_sp_${Date.now().toString(36)}_${randomPart}`;
 }
 
-function parseScopes(value: unknown): StoredScopes {
-  if (value === null || value === undefined) return {};
-  if (typeof value === 'object' && !Array.isArray(value)) {
-    const result: StoredScopes = {};
-    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-      if (typeof v === 'string') {
-        result[k] = v;
-      }
-    }
-    return result;
-  }
-  return {};
-}
-
-export class PostgresServerSyncDialect implements ServerSyncDialect {
+export class PostgresServerSyncDialect extends BaseServerSyncDialect {
   readonly name = 'postgres' as const;
   readonly supportsForUpdate = true;
   readonly supportsSavepoints = true;
 
+  // ===========================================================================
+  // SQL Fragment Hooks
+  // ===========================================================================
+
+  protected buildNumberListFilter(values: number[]): RawBuilder<unknown> {
+    return sql`= ANY(${values}::bigint[])`;
+  }
+
+  protected buildStringListFilter(values: string[]): RawBuilder<unknown> {
+    return sql`= ANY(${values}::text[])`;
+  }
+
   // ===========================================================================
   // Schema Setup
   // ===========================================================================
@@ -67,6 +62,9 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
       .createTable('sync_commits')
       .ifNotExists()
       .addColumn('commit_seq', 'bigserial', (col) => col.primaryKey())
+      .addColumn('partition_id', 'text', (col) =>
+        col.notNull().defaultTo('default')
+      )
       .addColumn('actor_id', 'text', (col) => col.notNull())
       .addColumn('client_id', 'text', (col) => col.notNull())
       .addColumn('client_commit_id', 'text', (col) => col.notNull())
@@ -90,12 +88,17 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
       ADD COLUMN IF NOT EXISTS affected_tables text[] NOT NULL DEFAULT ARRAY[]::text[]`.execute(
       db
     );
+    await sql`ALTER TABLE sync_commits
+      ADD COLUMN IF NOT EXISTS partition_id text NOT NULL DEFAULT 'default'`.execute(
+      db
+    );
 
+    await sql`DROP INDEX IF EXISTS idx_sync_commits_client_commit`.execute(db);
     await db.schema
       .createIndex('idx_sync_commits_client_commit')
       .ifNotExists()
       .on('sync_commits')
-      .columns(['client_id', 'client_commit_id'])
+      .columns(['partition_id', 'client_id', 'client_commit_id'])
       .unique()
       .execute();
 
@@ -103,18 +106,30 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
     await db.schema
       .createTable('sync_table_commits')
       .ifNotExists()
+      .addColumn('partition_id', 'text', (col) =>
+        col.notNull().defaultTo('default')
+      )
       .addColumn('table', 'text', (col) => col.notNull())
       .addColumn('commit_seq', 'bigint', (col) =>
         col.notNull().references('sync_commits.commit_seq').onDelete('cascade')
       )
-      .addPrimaryKeyConstraint('sync_table_commits_pk', ['table', 'commit_seq'])
+      .addPrimaryKeyConstraint('sync_table_commits_pk', [
+        'partition_id',
+        'table',
+        'commit_seq',
+      ])
       .execute();
 
+    await sql`ALTER TABLE sync_table_commits
+      ADD COLUMN IF NOT EXISTS partition_id text NOT NULL DEFAULT 'default'`.execute(
+      db
+    );
+
     await db.schema
       .createIndex('idx_sync_table_commits_commit_seq')
       .ifNotExists()
       .on('sync_table_commits')
-      .columns(['commit_seq'])
+      .columns(['partition_id', 'commit_seq'])
       .execute();
 
     // Changes table with JSONB scopes
@@ -122,6 +137,9 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
       .createTable('sync_changes')
       .ifNotExists()
       .addColumn('change_id', 'bigserial', (col) => col.primaryKey())
+      .addColumn('partition_id', 'text', (col) =>
+        col.notNull().defaultTo('default')
+      )
       .addColumn('commit_seq', 'bigint', (col) =>
         col.notNull().references('sync_commits.commit_seq').onDelete('cascade')
       )
@@ -133,18 +151,23 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
       .addColumn('scopes', 'jsonb', (col) => col.notNull())
       .execute();
 
+    await sql`ALTER TABLE sync_changes
+      ADD COLUMN IF NOT EXISTS partition_id text NOT NULL DEFAULT 'default'`.execute(
+      db
+    );
+
     await db.schema
       .createIndex('idx_sync_changes_commit_seq')
       .ifNotExists()
       .on('sync_changes')
-      .columns(['commit_seq'])
+      .columns(['partition_id', 'commit_seq'])
       .execute();
 
     await db.schema
       .createIndex('idx_sync_changes_table')
       .ifNotExists()
       .on('sync_changes')
-      .columns(['table'])
+      .columns(['partition_id', 'table'])
       .execute();
 
     await this.ensureIndex(
@@ -156,7 +179,10 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
     await db.schema
       .createTable('sync_client_cursors')
       .ifNotExists()
-      .addColumn('client_id', 'text', (col) => col.primaryKey())
+      .addColumn('partition_id', 'text', (col) =>
+        col.notNull().defaultTo('default')
+      )
+      .addColumn('client_id', 'text', (col) => col.notNull())
       .addColumn('actor_id', 'text', (col) => col.notNull())
       .addColumn('cursor', 'bigint', (col) => col.notNull().defaultTo(0))
       .addColumn('effective_scopes', 'jsonb', (col) =>
@@ -165,8 +191,17 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
       .addColumn('updated_at', 'timestamptz', (col) =>
         col.notNull().defaultTo(sql`now()`)
       )
+      .addPrimaryKeyConstraint('sync_client_cursors_pk', [
+        'partition_id',
+        'client_id',
+      ])
       .execute();
 
+    await sql`ALTER TABLE sync_client_cursors
+      ADD COLUMN IF NOT EXISTS partition_id text NOT NULL DEFAULT 'default'`.execute(
+      db
+    );
+
     await db.schema
       .createIndex('idx_sync_client_cursors_updated_at')
       .ifNotExists()
@@ -178,6 +213,9 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
       .createTable('sync_snapshot_chunks')
       .ifNotExists()
       .addColumn('chunk_id', 'text', (col) => col.primaryKey())
+      .addColumn('partition_id', 'text', (col) =>
+        col.notNull().defaultTo('default')
+      )
       .addColumn('scope_key', 'text', (col) => col.notNull())
       .addColumn('scope', 'text', (col) => col.notNull())
       .addColumn('as_of_commit_seq', 'bigint', (col) => col.notNull())
@@ -195,6 +233,11 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
       .addColumn('expires_at', 'timestamptz', (col) => col.notNull())
       .execute();
 
+    await sql`ALTER TABLE sync_snapshot_chunks
+      ADD COLUMN IF NOT EXISTS partition_id text NOT NULL DEFAULT 'default'`.execute(
+      db
+    );
+
     await db.schema
       .createIndex('idx_sync_snapshot_chunks_expires_at')
       .ifNotExists()
@@ -207,6 +250,7 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
       .ifNotExists()
       .on('sync_snapshot_chunks')
       .columns([
+        'partition_id',
         'scope_key',
         'scope',
         'as_of_commit_seq',
@@ -227,6 +271,19 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
     db: Kysely<DB>,
     fn: (executor: DbExecutor<DB>) => Promise<T>
   ): Promise<T> {
+    if (isActiveTransaction(db)) {
+      const savepoint = createSavepointName();
+      await sql.raw(`SAVEPOINT ${savepoint}`).execute(db);
+      try {
+        const result = await fn(db);
+        await sql.raw(`RELEASE SAVEPOINT ${savepoint}`).execute(db);
+        return result;
+      } catch (error) {
+        await sql.raw(`ROLLBACK TO SAVEPOINT ${savepoint}`).execute(db);
+        await sql.raw(`RELEASE SAVEPOINT ${savepoint}`).execute(db);
+        throw error;
+      }
+    }
     return db.transaction().execute(fn);
   }
 
@@ -237,42 +294,28 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
   }
 
   // ===========================================================================
-  // Commit/Change Log Queries
+  // Overrides (dialect-specific optimizations / casts)
   // ===========================================================================
 
-  async readMaxCommitSeq<DB extends SyncCoreDb>(
-    db: Kysely<DB> | Transaction<DB>
-  ): Promise<number> {
-    const res = await sql<{ max_seq: unknown }>`
-      SELECT max(commit_seq) as max_seq
-      FROM sync_commits
-    `.execute(db);
-
-    return coerceNumber(res.rows[0]?.max_seq) ?? 0;
-  }
-
-  async readMinCommitSeq<DB extends SyncCoreDb>(
-    db: Kysely<DB> | Transaction<DB>
-  ): Promise<number> {
-    const res = await sql<{ min_seq: unknown }>`
-      SELECT min(commit_seq) as min_seq
-      FROM sync_commits
-    `.execute(db);
-
-    return coerceNumber(res.rows[0]?.min_seq) ?? 0;
-  }
-
   async readCommitSeqsForPull<DB extends SyncCoreDb>(
     db: Kysely<DB> | Transaction<DB>,
-    args: { cursor: number; limitCommits: number; tables: string[] }
+    args: {
+      cursor: number;
+      limitCommits: number;
+      tables: string[];
+      partitionId?: string;
+    }
   ): Promise<number[]> {
+    const partitionId = args.partitionId ?? 'default';
     if (args.tables.length === 0) return [];
 
+    // Single-table fast path: skip DISTINCT since (partition_id, table, commit_seq) is PK
     if (args.tables.length === 1) {
       const res = await sql<{ commit_seq: unknown }>`
         SELECT commit_seq
         FROM sync_table_commits
-        WHERE "table" = ${args.tables[0]}
+        WHERE partition_id = ${partitionId}
+          AND "table" = ${args.tables[0]}
           AND commit_seq > ${args.cursor}
         ORDER BY commit_seq ASC
         LIMIT ${args.limitCommits}
@@ -286,61 +329,55 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
         );
     }
 
-    const res = await sql<{ commit_seq: unknown }>`
-      SELECT DISTINCT commit_seq
-      FROM sync_table_commits
-      WHERE "table" = ANY(${args.tables}::text[])
-        AND commit_seq > ${args.cursor}
-      ORDER BY commit_seq ASC
-      LIMIT ${args.limitCommits}
-    `.execute(db);
-
-    return res.rows
-      .map((r) => coerceNumber(r.commit_seq))
-      .filter(
-        (n): n is number =>
-          typeof n === 'number' && Number.isFinite(n) && n > args.cursor
-      );
+    // Multi-table: use ANY() with DISTINCT
+    return super.readCommitSeqsForPull(db, args);
   }
 
-  async readCommits<DB extends SyncCoreDb>(
+  async recordClientCursor<DB extends SyncCoreDb>(
     db: Kysely<DB> | Transaction<DB>,
-    commitSeqs: number[]
-  ): Promise<SyncCommitRow[]> {
-    if (commitSeqs.length === 0) return [];
+    args: {
+      partitionId?: string;
+      clientId: string;
+      actorId: string;
+      cursor: number;
+      effectiveScopes: ScopeValues;
+    }
+  ): Promise<void> {
+    const partitionId = args.partitionId ?? 'default';
+    const now = new Date().toISOString();
+    const scopesJson = JSON.stringify(args.effectiveScopes);
 
-    const res = await sql<{
-      commit_seq: unknown;
-      actor_id: string;
-      created_at: unknown;
-      result_json: unknown | null;
-    }>`
-      SELECT commit_seq, actor_id, created_at, result_json
-      FROM sync_commits
-      WHERE commit_seq = ANY(${commitSeqs}::bigint[])
-      ORDER BY commit_seq ASC
+    await sql`
+      INSERT INTO sync_client_cursors (partition_id, client_id, actor_id, cursor, effective_scopes, updated_at)
+      VALUES (${partitionId}, ${args.clientId}, ${args.actorId}, ${args.cursor}, ${scopesJson}::jsonb, ${now})
+      ON CONFLICT(partition_id, client_id) DO UPDATE SET
+        actor_id = ${args.actorId},
+        cursor = ${args.cursor},
+        effective_scopes = ${scopesJson}::jsonb,
+        updated_at = ${now}
     `.execute(db);
-
-    return res.rows.map((row) => ({
-      commit_seq: coerceNumber(row.commit_seq) ?? 0,
-      actor_id: row.actor_id,
-      created_at: coerceIsoString(row.created_at),
-      result_json: row.result_json ?? null,
-    }));
   }
 
+  // ===========================================================================
+  // Commit/Change Log Queries (dialect-specific)
+  // ===========================================================================
+
   async readChangesForCommits<DB extends SyncCoreDb>(
-    db: Kysely<DB> | Transaction<DB>,
-    args: { commitSeqs: number[]; table: string; scopes: ScopeValues }
+    db: DbExecutor<DB>,
+    args: {
+      commitSeqs: number[];
+      table: string;
+      scopes: ScopeValues;
+      partitionId?: string;
+    }
   ): Promise<SyncChangeRow[]> {
+    const partitionId = args.partitionId ?? 'default';
     if (args.commitSeqs.length === 0) return [];
 
     // Build JSONB containment conditions for scope filtering
-    // For each scope key/value, we need: scopes->>'key' = 'value' OR scopes->>'key' IN (values)
     const scopeConditions: ReturnType<typeof sql>[] = [];
     for (const [key, value] of Object.entries(args.scopes)) {
       if (Array.isArray(value)) {
-        // OR condition for array values
         scopeConditions.push(sql`scopes->>${key} = ANY(${value}::text[])`);
       } else {
         scopeConditions.push(sql`scopes->>${key} = ${value}`);
@@ -359,6 +396,7 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
       SELECT commit_seq, "table", row_id, op, row_json, row_version, scopes
       FROM sync_changes
       WHERE commit_seq = ANY(${args.commitSeqs}::bigint[])
+        AND partition_id = ${partitionId}
         AND "table" = ${args.table}
     `;
 
@@ -376,6 +414,7 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
         SELECT commit_seq, "table", row_id, op, row_json, row_version, scopes
         FROM sync_changes
         WHERE commit_seq = ANY(${args.commitSeqs}::bigint[])
+          AND partition_id = ${partitionId}
           AND "table" = ${args.table}
           AND (${scopeFilter})
         ORDER BY commit_seq ASC, change_id ASC
@@ -395,28 +434,11 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
     }));
   }
 
-  async readIncrementalPullRows<DB extends SyncCoreDb>(
-    db: Kysely<DB> | Transaction<DB>,
-    args: {
-      table: string;
-      scopes: ScopeValues;
-      cursor: number;
-      limitCommits: number;
-    }
-  ): Promise<
-    Array<{
-      commit_seq: number;
-      actor_id: string;
-      created_at: string;
-      change_id: number;
-      table: string;
-      row_id: string;
-      op: SyncOp;
-      row_json: unknown | null;
-      row_version: number | null;
-      scopes: StoredScopes;
-    }>
-  > {
+  protected override async readIncrementalPullRowsBatch<DB extends SyncCoreDb>(
+    db: DbExecutor<DB>,
+    args: Omit<IncrementalPullRowsArgs, 'batchSize'>
+  ): Promise<IncrementalPullRow[]> {
+    const partitionId = args.partitionId ?? 'default';
     const limitCommits = Math.max(1, Math.min(500, args.limitCommits));
 
     // Build scope filter conditions
@@ -450,12 +472,15 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
         SELECT DISTINCT tc.commit_seq
         FROM sync_table_commits tc
         JOIN sync_commits cm ON cm.commit_seq = tc.commit_seq
-        WHERE tc."table" = ${args.table}
+        WHERE tc.partition_id = ${partitionId}
+          AND tc."table" = ${args.table}
+          AND cm.partition_id = ${partitionId}
           AND tc.commit_seq > ${args.cursor}
           AND EXISTS (
             SELECT 1
             FROM sync_changes c
             WHERE c.commit_seq = tc.commit_seq
+              AND c.partition_id = ${partitionId}
               AND c."table" = ${args.table}
               AND (${scopeFilter})
           )
@@ -476,7 +501,9 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
       FROM commit_seqs cs
       JOIN sync_commits cm ON cm.commit_seq = cs.commit_seq
       JOIN sync_changes c ON c.commit_seq = cs.commit_seq
-      WHERE c."table" = ${args.table}
+      WHERE cm.partition_id = ${partitionId}
+        AND c.partition_id = ${partitionId}
+        AND c."table" = ${args.table}
         AND (${scopeFilter})
       ORDER BY cm.commit_seq ASC, c.change_id ASC
     `.execute(db);
@@ -495,51 +522,8 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
     }));
   }
 
-  async *streamIncrementalPullRows<DB extends SyncCoreDb>(
-    db: Kysely<DB> | Transaction<DB>,
-    args: {
-      table: string;
-      scopes: ScopeValues;
-      cursor: number;
-      limitCommits: number;
-      batchSize?: number;
-    }
-  ): AsyncGenerator<{
-    commit_seq: number;
-    actor_id: string;
-    created_at: string;
-    change_id: number;
-    table: string;
-    row_id: string;
-    op: SyncOp;
-    row_json: unknown | null;
-    row_version: number | null;
-    scopes: StoredScopes;
-  }> {
-    // PostgreSQL: use batching approach (could use pg-query-stream for true streaming)
-    const batchSize = Math.min(100, args.batchSize ?? 100);
-    let processed = 0;
-
-    while (processed < args.limitCommits) {
-      const batch = await this.readIncrementalPullRows(db, {
-        ...args,
-        limitCommits: Math.min(batchSize, args.limitCommits - processed),
-        cursor: args.cursor + processed,
-      });
-
-      if (batch.length === 0) break;
-
-      for (const row of batch) {
-        yield row;
-      }
-
-      processed += batch.length;
-      if (batch.length < batchSize) break;
-    }
-  }
-
   async compactChanges<DB extends SyncCoreDb>(
-    db: Kysely<DB> | Transaction<DB>,
+    db: DbExecutor<DB>,
     args: { fullHistoryHours: number }
   ): Promise<number> {
     const cutoffIso = new Date(
@@ -551,7 +535,7 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
         SELECT
           c.change_id,
           row_number() OVER (
-            PARTITION BY c."table", c.row_id, c.scopes
+            PARTITION BY c.partition_id, c."table", c.row_id, c.scopes
             ORDER BY c.commit_seq DESC, c.change_id DESC
           ) AS rn
         FROM sync_changes c
@@ -568,12 +552,14 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
     await sql`
       DELETE FROM sync_table_commits tc
       USING sync_commits cm
-      WHERE cm.commit_seq = tc.commit_seq
-        AND cm.created_at < ${cutoffIso}
+        WHERE cm.commit_seq = tc.commit_seq
+          AND cm.partition_id = tc.partition_id
+          AND cm.created_at < ${cutoffIso}
         AND NOT EXISTS (
           SELECT 1
           FROM sync_changes c
           WHERE c.commit_seq = tc.commit_seq
+            AND c.partition_id = tc.partition_id
             AND c."table" = tc."table"
         )
     `.execute(db);
@@ -581,33 +567,6 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
     return deletedChanges;
   }
 
-  // ===========================================================================
-  // Client Cursor Recording
-  // ===========================================================================
-
-  async recordClientCursor<DB extends SyncCoreDb>(
-    db: Kysely<DB> | Transaction<DB>,
-    args: {
-      clientId: string;
-      actorId: string;
-      cursor: number;
-      effectiveScopes: ScopeValues;
-    }
-  ): Promise<void> {
-    const now = new Date().toISOString();
-    const scopesJson = JSON.stringify(args.effectiveScopes);
-
-    await sql`
-      INSERT INTO sync_client_cursors (client_id, actor_id, cursor, effective_scopes, updated_at)
-      VALUES (${args.clientId}, ${args.actorId}, ${args.cursor}, ${scopesJson}::jsonb, ${now})
-      ON CONFLICT(client_id) DO UPDATE SET
-        actor_id = ${args.actorId},
-        cursor = ${args.cursor},
-        effective_scopes = ${scopesJson}::jsonb,
-        updated_at = ${now}
-    `.execute(db);
-  }
-
   // ===========================================================================
   // Scope Conversion Helpers
   // ===========================================================================
@@ -616,10 +575,6 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
     return scopes;
   }
 
-  dbToScopes(value: unknown): StoredScopes {
-    return parseScopes(value);
-  }
-
   dbToArray(value: unknown): string[] {
     if (Array.isArray(value)) {
       return value.filter((k: unknown): k is string => typeof k === 'string');
@@ -631,21 +586,6 @@ export class PostgresServerSyncDialect implements ServerSyncDialect {
     return values.filter((v) => v.length > 0);
   }
 
-  async readAffectedTablesFromChanges<DB extends SyncCoreDb>(
-    db: Kysely<DB> | Transaction<DB>,
-    commitSeq: number
-  ): Promise<string[]> {
-    const res = await sql<{ table: string }>`
-      SELECT DISTINCT "table"
-      FROM sync_changes
-      WHERE commit_seq = ${commitSeq}
-    `.execute(db);
-
-    return res.rows
-      .map((r) => r.table)
-      .filter((t): t is string => typeof t === 'string' && t.length > 0);
-  }
-
   // ===========================================================================
   // Console Schema (Request Events)
   // ===========================================================================