orez 0.1.21 → 0.1.23

package/src/pglite-ipc.test.ts

@@ -0,0 +1,99 @@
+import { describe, test, expect, beforeAll, afterAll } from 'vitest'
+
+import { PGliteWorkerProxy } from './pglite-ipc.js'
+
+describe('PGliteWorkerProxy', () => {
+  let proxy: PGliteWorkerProxy
+
+  beforeAll(async () => {
+    proxy = new PGliteWorkerProxy({
+      dataDir: 'memory://',
+      name: 'test',
+      withExtensions: false,
+      debug: 0,
+      pgliteOptions: {},
+    })
+    await proxy.waitReady
+  }, 30_000)
+
+  afterAll(async () => {
+    await proxy.close()
+  })
+
+  test('exec creates table', async () => {
+    await proxy.exec(`
+      CREATE TABLE test_items (
+        id SERIAL PRIMARY KEY,
+        name TEXT NOT NULL
+      )
+    `)
+  })
+
+  test('query returns rows', async () => {
+    await proxy.exec(`INSERT INTO test_items (name) VALUES ('hello')`)
+    await proxy.exec(`INSERT INTO test_items (name) VALUES ('world')`)
+
+    const result = await proxy.query<{ id: number; name: string }>(
+      'SELECT * FROM test_items ORDER BY id'
+    )
+    expect(result.rows).toHaveLength(2)
+    expect(result.rows[0].name).toBe('hello')
+    expect(result.rows[1].name).toBe('world')
+  })
+
+  test('query with params', async () => {
+    const result = await proxy.query<{ name: string }>(
+      'SELECT name FROM test_items WHERE name = $1',
+      ['world']
+    )
+    expect(result.rows).toHaveLength(1)
+    expect(result.rows[0].name).toBe('world')
+  })
+
+  test('exec returns affectedRows', async () => {
+    const result = await proxy.exec(`DELETE FROM test_items WHERE name = 'hello'`)
+    expect(result[0].affectedRows).toBe(1)
+  })
+
+  test('execProtocolRaw handles wire protocol', async () => {
+    // simple query message: SELECT 1 as num
+    const query = 'SELECT 1 as num\0'
+    const encoder = new TextEncoder()
+    const queryBytes = encoder.encode(query)
+    const buf = new Uint8Array(5 + queryBytes.length)
+    buf[0] = 0x51 // 'Q' simple query
+    new DataView(buf.buffer).setInt32(1, 4 + queryBytes.length)
+    buf.set(queryBytes, 5)
+
+    const result = await proxy.execProtocolRaw(buf)
+    expect(result).toBeInstanceOf(Uint8Array)
+    expect(result.length).toBeGreaterThan(0)
+    // should contain a ReadyForQuery message (0x5a)
+    let hasRfq = false
+    for (let i = 0; i < result.length; i++) {
+      if (result[i] === 0x5a) {
+        hasRfq = true
+        break
+      }
+    }
+    expect(hasRfq).toBe(true)
+  })
+
+  test('listen receives notifications', async () => {
+    const received: string[] = []
+    const unsub = await proxy.listen('test_channel', (payload) => {
+      received.push(payload)
+    })
+
+    await proxy.exec(`NOTIFY test_channel, 'hello'`)
+    // give notification time to propagate
+    await new Promise((r) => setTimeout(r, 100))
+
+    expect(received).toContain('hello')
+    await unsub()
+  })
+
+  test('error propagation with SQL code', async () => {
+    await expect(proxy.exec('SELECT * FROM nonexistent_table')).rejects.toThrow()
+  })
+})

package/src/pglite-ipc.ts

@@ -0,0 +1,214 @@
+/**
+ * PGlite worker proxy — runs in the main thread, proxies calls to a
+ * worker thread running the actual PGlite instance.
+ *
+ * implements the PGlite interface surface used throughout orez:
+ * execProtocolRaw, query, exec, listen, close.
+ *
+ * ArrayBuffers are transferred (not copied) for execProtocolRaw to
+ * keep IPC overhead near-zero for wire protocol data.
+ */
+
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { Worker } from 'node:worker_threads'
+
+import { log } from './log.js'
+import { signalReplicationChange } from './replication/handler.js'
+
+import type { WorkerInitConfig } from './pglite-worker-thread.js'
+
+interface PendingRequest {
+  resolve: (value: any) => void
+  reject: (error: Error) => void
+}
+
+const WRITE_PREFIXES = ['insert', 'update', 'delete', 'copy', 'truncate']
+// shard-internal tables that the replication handler filters out.
+// signaling for these just causes spurious wakeups + mutex contention.
+const SHARD_INTERNAL_TABLES = ['"replicas"', '"mutations"', '"replicationState"']
+function isReplicatedWrite(sql: string): boolean {
+  const q = sql.trimStart().toLowerCase()
+  if (!WRITE_PREFIXES.some((p) => q.startsWith(p))) return false
+  // skip shard-internal writes (zero-cache manages these, not replicated)
+  for (const t of SHARD_INTERNAL_TABLES) {
+    if (q.includes(t.toLowerCase())) return false
+  }
+  return true
+}
+
+// resolve worker file path — .ts in dev/test (vitest), .js when compiled
+function resolveWorkerPath(): string {
+  const dir = import.meta.dirname
+  const tsPath = resolve(dir, 'pglite-worker-thread.ts')
+  if (existsSync(tsPath)) return tsPath
+  return resolve(dir, 'pglite-worker-thread.js')
+}
+
+export class PGliteWorkerProxy {
+  private worker: Worker
+  private pending = new Map<number, PendingRequest>()
+  private nextId = 1
+  private notificationCallbacks = new Map<string, Set<(payload: string) => void>>()
+  readonly name: string
+
+  /** resolves when the worker's PGlite instance is ready */
+  readonly waitReady: Promise<void>
+
+  constructor(config: WorkerInitConfig) {
+    this.name = config.name
+    const workerPath = resolveWorkerPath()
+
+    this.worker = new Worker(workerPath, {
+      workerData: config,
+      name: `pglite-${config.name}`,
+    })
+
+    // set up waitReady promise, then install message handler once ready
+    let onReady: () => void
+    this.waitReady = new Promise<void>((resolveReady, rejectReady) => {
+      onReady = () => {
+        log.debug.pglite(`worker ${config.name} ready`)
+        resolveReady()
+      }
+
+      const onMessage = (msg: { type: string; id?: number; message?: string }) => {
+        if (msg.type === 'ready') {
+          this.worker.off('message', onMessage)
+          this.installMessageHandler()
+          onReady()
+        } else if (msg.type === 'error' && msg.id === 0) {
+          rejectReady(new Error(msg.message))
+        }
+      }
+
+      this.worker.on('message', onMessage)
+      this.worker.once('error', rejectReady)
+    })
+
+    // handle unexpected worker crashes
+    this.worker.on('error', (err) => {
+      log.pglite(`worker ${config.name} error: ${err.message}`)
+      for (const [, req] of this.pending) {
+        req.reject(new Error(`worker crashed: ${err.message}`))
+      }
+      this.pending.clear()
+    })
+
+    this.worker.on('exit', (code) => {
+      if (code !== 0) {
+        log.pglite(`worker ${config.name} exited with code ${code}`)
+        for (const [, req] of this.pending) {
+          req.reject(new Error(`worker exited with code ${code}`))
+        }
+        this.pending.clear()
+      }
+    })
+  }
+
+  private installMessageHandler() {
+    this.worker.on(
+      'message',
+      (msg: { type: string; id?: number; [key: string]: any }) => {
+        if (msg.type === 'notification') {
+          const callbacks = this.notificationCallbacks.get(msg.channel)
+          if (callbacks) {
+            for (const cb of callbacks) {
+              try {
+                cb(msg.payload)
+              } catch {}
+            }
+          }
+          return
+        }
+
+        const req = this.pending.get(msg.id!)
+        if (!req) return
+        this.pending.delete(msg.id!)
+
+        if (msg.type === 'error') {
+          const err = new Error(msg.message) as Error & { code?: string }
+          if (msg.code) err.code = msg.code
+          req.reject(err)
+        } else {
+          req.resolve(msg)
+        }
+      }
+    )
+  }
+
+  private send(msg: Record<string, unknown>, transfer?: ArrayBuffer[]): Promise<any> {
+    const id = this.nextId++
+    msg.id = id
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject })
+      if (transfer?.length) {
+        this.worker.postMessage(msg, transfer)
+      } else {
+        this.worker.postMessage(msg)
+      }
+    })
+  }
+
+  async execProtocolRaw(
+    data: Uint8Array,
+    options?: { syncToFs?: boolean; throwOnError?: boolean }
+  ): Promise<Uint8Array> {
+    // copy to a transferable buffer then transfer (avoids copying in the worker)
+    const buf = new ArrayBuffer(data.byteLength)
+    new Uint8Array(buf).set(data)
+    const result = await this.send({ type: 'execProtocolRaw', data: buf, options }, [buf])
+    return new Uint8Array(result.data)
+  }
+
+  async query<T = any>(
+    sql: string,
+    params?: any[]
+  ): Promise<{ rows: T[]; affectedRows?: number }> {
+    const result = await this.send({ type: 'query', sql, params })
+    if (this.name === 'postgres' && isReplicatedWrite(sql)) {
+      signalReplicationChange()
+    }
+    return { rows: result.rows ?? [], affectedRows: result.affectedRows }
+  }
+
+  async exec(sql: string): Promise<{ affectedRows?: number }[]> {
+    const result = await this.send({ type: 'exec', sql })
+    if (this.name === 'postgres' && isReplicatedWrite(sql)) {
+      signalReplicationChange()
+    }
+    return result.results ?? []
+  }
+
+  async listen(
+    channel: string,
+    callback: (payload: string) => void
+  ): Promise<() => Promise<void>> {
+    let callbacks = this.notificationCallbacks.get(channel)
+    if (!callbacks) {
+      callbacks = new Set()
+      this.notificationCallbacks.set(channel, callbacks)
+    }
+    callbacks.add(callback)
+
+    const result = await this.send({ type: 'listen', channel })
+    const listenId = result.id
+
+    return async () => {
+      callbacks!.delete(callback)
+      if (callbacks!.size === 0) {
+        this.notificationCallbacks.delete(channel)
+      }
+      await this.send({ type: 'unlisten', listenId }).catch(() => {})
+    }
+  }
+
+  async close(): Promise<void> {
+    try {
+      await this.send({ type: 'close' })
+    } catch {
+      // worker may already be gone
+    }
+    await this.worker.terminate()
+  }
+}

package/src/pglite-manager.ts

@@ -23,6 +23,7 @@ import { uuid_ossp } from '@electric-sql/pglite/contrib/uuid_ossp'
 import { vector } from '@electric-sql/pglite/vector'
 
 import { log } from './log.js'
+import { PGliteWorkerProxy } from './pglite-ipc.js'
 
 import type { ZeroLiteConfig } from './config.js'
 
@@ -210,6 +211,98 @@ export async function createPGliteInstances(
   return { postgres, cvr, cdb }
 }
 
+/**
+ * create worker-backed pglite instances.
+ *
+ * each instance runs in its own worker thread with a separate event loop,
+ * so PGlite WASM execution doesn't block the proxy or replication handler.
+ * ArrayBuffers are transferred (not copied) for wire protocol data.
+ */
+export async function createPGliteWorkerInstances(
+  config: ZeroLiteConfig
+): Promise<PGliteInstances> {
+  // migrate from old single-instance layout (pgdata → pgdata-postgres)
+  const pgliteDataDir = (config.pgliteOptions as Record<string, any>)?.dataDir
+  if (!pgliteDataDir || !String(pgliteDataDir).startsWith('memory://')) {
+    const oldDataPath = resolve(config.dataDir, 'pgdata')
+    const newDataPath = resolve(config.dataDir, 'pgdata-postgres')
+    if (existsSync(oldDataPath) && !existsSync(newDataPath)) {
+      renameSync(oldDataPath, newDataPath)
+      log.debug.pglite('migrated pgdata → pgdata-postgres')
+    }
+  }
+
+  const useMemory =
+    typeof pgliteDataDir === 'string' && pgliteDataDir.startsWith('memory://')
+  const {
+    dataDir: _ud,
+    debug: _dbg,
+    ...userOpts
+  } = config.pgliteOptions as Record<string, any>
+
+  function makeWorkerConfig(name: string, withExtensions: boolean) {
+    const dataPath = useMemory ? 'memory://' : resolve(config.dataDir, `pgdata-${name}`)
+    if (!useMemory) {
+      mkdirSync(dataPath, { recursive: true })
+      if (cleanStaleLocks(dataPath)) {
+        log.debug.pglite(`cleaned stale locks in ${name}`)
+      }
+    }
+    return {
+      dataDir: dataPath,
+      name,
+      withExtensions,
+      debug: config.logLevel === 'debug' ? 1 : 0,
+      pgliteOptions: userOpts,
+    }
+  }
+
+  log.pglite('starting worker threads for postgres, cvr, cdb')
+
+  // create all 3 worker proxies in parallel
+  const pgProxy = new PGliteWorkerProxy(makeWorkerConfig('postgres', true))
+  const cvrProxy = new PGliteWorkerProxy(makeWorkerConfig('cvr', false))
+  const cdbProxy = new PGliteWorkerProxy(makeWorkerConfig('cdb', false))
+
+  await Promise.all([pgProxy.waitReady, cvrProxy.waitReady, cdbProxy.waitReady])
+
+  log.pglite('all worker threads ready')
+
+  // postgres-specific setup
+  await pgProxy.exec('CREATE EXTENSION IF NOT EXISTS plpgsql')
+
+  // create publication only when explicitly configured
+  const pubName = process.env.ZERO_APP_PUBLICATIONS?.trim()
+  if (pubName) {
+    const pubs = await pgProxy.query<{ count: string }>(
+      `SELECT count(*) as count FROM pg_publication WHERE pubname = $1`,
+      [pubName]
+    )
+    if (Number(pubs.rows[0].count) === 0) {
+      const quoted = '"' + pubName.replace(/"/g, '""') + '"'
+      await pgProxy.exec(`CREATE PUBLICATION ${quoted}`)
+    }
+  }
+
+  // cast to PGlite — our proxy implements the same interface surface
+  return {
+    postgres: pgProxy as unknown as PGlite,
+    cvr: cvrProxy as unknown as PGlite,
+    cdb: cdbProxy as unknown as PGlite,
+  }
+}
+
+/** create a single worker-backed PGlite instance (for CVR/CDB recreation during reset) */
+export function createPGliteWorker(dataDir: string, name: string): PGliteWorkerProxy {
+  return new PGliteWorkerProxy({
+    dataDir,
+    name,
+    withExtensions: false,
+    debug: 0,
+    pgliteOptions: {},
+  })
+}
+
 /** run pending migrations, returns count of newly applied migrations */
 export async function runMigrations(db: PGlite, config: ZeroLiteConfig): Promise<number> {
   if (!config.migrationsDir) {

package/src/pglite-worker-thread.ts

@@ -0,0 +1,172 @@
+/**
+ * worker thread that runs a single PGlite instance.
+ *
+ * receives commands via parentPort messages, executes them on the PGlite
+ * instance, and sends results back. ArrayBuffers are transferred (not copied)
+ * for execProtocolRaw to minimize overhead.
+ */
+
+import { parentPort, workerData } from 'node:worker_threads'
+
+import { PGlite } from '@electric-sql/pglite'
+import { btree_gin } from '@electric-sql/pglite/contrib/btree_gin'
+import { btree_gist } from '@electric-sql/pglite/contrib/btree_gist'
+import { citext } from '@electric-sql/pglite/contrib/citext'
+import { cube } from '@electric-sql/pglite/contrib/cube'
+import { earthdistance } from '@electric-sql/pglite/contrib/earthdistance'
+import { fuzzystrmatch } from '@electric-sql/pglite/contrib/fuzzystrmatch'
+import { hstore } from '@electric-sql/pglite/contrib/hstore'
+import { ltree } from '@electric-sql/pglite/contrib/ltree'
+import { pg_trgm } from '@electric-sql/pglite/contrib/pg_trgm'
+import { pgcrypto } from '@electric-sql/pglite/contrib/pgcrypto'
+import { uuid_ossp } from '@electric-sql/pglite/contrib/uuid_ossp'
+import { vector } from '@electric-sql/pglite/vector'
+
+export interface WorkerInitConfig {
+  dataDir: string
+  name: string
+  withExtensions: boolean
+  debug: number
+  pgliteOptions?: Record<string, unknown>
+}
+
+const port = parentPort!
+const config = workerData as WorkerInitConfig
+
+// active listen subscriptions
+const listeners = new Map<number, () => Promise<void>>()
+
+let db: PGlite
+
+async function init() {
+  const { dataDir: _userDataDir, debug: _dbg, ...userOpts } = config.pgliteOptions || {}
+
+  db = new PGlite({
+    dataDir: config.dataDir,
+    debug: config.debug,
+    relaxedDurability: true,
+    ...userOpts,
+    extensions: config.withExtensions
+      ? userOpts.extensions || {
+          vector,
+          pg_trgm,
+          pgcrypto,
+          uuid_ossp,
+          citext,
+          hstore,
+          ltree,
+          fuzzystrmatch,
+          btree_gin,
+          btree_gist,
+          cube,
+          earthdistance,
+        }
+      : {},
+  } as any)
+
+  await db.waitReady
+
+  // tune postgres internals
+  await db.exec(`
+    SET work_mem = '64MB';
+    SET maintenance_work_mem = '128MB';
+    SET effective_cache_size = '512MB';
+    SET random_page_cost = 1.1;
+    SET jit = off;
+  `)
+
+  port.postMessage({ type: 'ready' })
+}
+
+port.on('message', async (msg: { type: string; id: number; [key: string]: unknown }) => {
+  const { type, id } = msg
+
+  try {
+    switch (type) {
+      case 'execProtocolRaw': {
+        const input = new Uint8Array(msg.data as ArrayBuffer)
+        const result = await db.execProtocolRaw(input, msg.options as any)
+        // copy result to a transferable buffer (pglite may reuse wasm memory)
+        const buf = new ArrayBuffer(result.byteLength)
+        new Uint8Array(buf).set(result)
+        port.postMessage({ type: 'result', id, data: buf }, [buf])
+        break
+      }
+
+      case 'query': {
+        const result = await db.query(msg.sql as string, msg.params as any[])
+        port.postMessage({
+          type: 'result',
+          id,
+          rows: result.rows,
+          affectedRows: result.affectedRows,
+        })
+        break
+      }
+
+      case 'exec': {
+        const result = await db.exec(msg.sql as string)
+        // serialize exec results (array of { affectedRows })
+        const results = result.map((r) => ({ affectedRows: r.affectedRows ?? 0 }))
+        port.postMessage({ type: 'result', id, results })
+        break
+      }
+
+      case 'listen': {
+        const channel = msg.channel as string
+        const unsub = await db.listen(channel, (payload) => {
+          port.postMessage({ type: 'notification', channel, payload })
+        })
+        listeners.set(id, unsub)
+        port.postMessage({ type: 'result', id })
+        break
+      }
+
+      case 'unlisten': {
+        const listenId = msg.listenId as number
+        const unsub = listeners.get(listenId)
+        if (unsub) {
+          await unsub()
+          listeners.delete(listenId)
+        }
+        port.postMessage({ type: 'result', id })
+        break
+      }
+
+      case 'close': {
+        for (const unsub of listeners.values()) {
+          await unsub().catch(() => {})
+        }
+        listeners.clear()
+        await db.close()
+        port.postMessage({ type: 'result', id })
+        break
+      }
+
+      default:
+        port.postMessage({
+          type: 'error',
+          id,
+          message: `unknown message type: ${type}`,
+        })
+    }
+  } catch (err: unknown) {
+    const error = err as { message?: string; code?: string }
+    port.postMessage({
+      type: 'error',
+      id,
+      message: error?.message || String(err),
+      code: error?.code,
+    })
+  }
+})
+
+init().catch((err: unknown) => {
+  const error = err as { message?: string }
+  port.postMessage({
+    type: 'error',
+    id: 0,
+    message: `worker init failed: ${error?.message || String(err)}`,
+  })
+  process.exit(1)
+})

package/src/process-title.ts

@@ -0,0 +1,9 @@
+export function orezTitle(label = 'orez'): string {
+  const cwd = process.cwd()
+  const home = process.env.HOME || ''
+  const dir =
+    home && cwd.startsWith(home + '/')
+      ? '~' + cwd.slice(home.length)
+      : cwd.split('/').pop()!
+  return `${label} (${dir})`
+}

package/src/recovery.ts

@@ -7,12 +7,13 @@ import { mkdirSync, rmSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 import { log } from './log.js'
+import { createPGliteWorker } from './pglite-manager.js'
 
 import type { PGlite } from '@electric-sql/pglite'
 import type { ChildProcess } from 'node:child_process'
 
 export interface RecoveryContext {
-  config: { dataDir: string }
+  config: { dataDir: string; useWorkerThreads?: boolean }
   instances: {
     postgres: PGlite
     cvr: PGlite
@@ -74,19 +75,27 @@ export async function recoverFromCdcCorruption(ctx: RecoveryContext): Promise<vo
   }
 
   // recreate CVR/CDB instances
-  const { PGlite } = await import('@electric-sql/pglite')
-  mkdirSync(resolve(config.dataDir, 'pgdata-cvr'), { recursive: true })
-  mkdirSync(resolve(config.dataDir, 'pgdata-cdb'), { recursive: true })
-  instances.cvr = new PGlite({
-    dataDir: resolve(config.dataDir, 'pgdata-cvr'),
-    relaxedDurability: true,
-  })
-  instances.cdb = new PGlite({
-    dataDir: resolve(config.dataDir, 'pgdata-cdb'),
-    relaxedDurability: true,
-  })
-  await instances.cvr.waitReady
-  await instances.cdb.waitReady
+  if (config.useWorkerThreads) {
+    const cvrProxy = createPGliteWorker(resolve(config.dataDir, 'pgdata-cvr'), 'cvr')
+    const cdbProxy = createPGliteWorker(resolve(config.dataDir, 'pgdata-cdb'), 'cdb')
+    await Promise.all([cvrProxy.waitReady, cdbProxy.waitReady])
+    instances.cvr = cvrProxy as unknown as PGlite
+    instances.cdb = cdbProxy as unknown as PGlite
+  } else {
+    const { PGlite: PGliteCtor } = await import('@electric-sql/pglite')
+    mkdirSync(resolve(config.dataDir, 'pgdata-cvr'), { recursive: true })
+    mkdirSync(resolve(config.dataDir, 'pgdata-cdb'), { recursive: true })
+    instances.cvr = new PGliteCtor({
+      dataDir: resolve(config.dataDir, 'pgdata-cvr'),
+      relaxedDurability: true,
+    })
+    instances.cdb = new PGliteCtor({
+      dataDir: resolve(config.dataDir, 'pgdata-cdb'),
+      relaxedDurability: true,
+    })
+    await instances.cvr.waitReady
+    await instances.cdb.waitReady
+  }
   log.orez('recreated CVR/CDB instances')
 
   // clear upstream replication tracking

package/src/replication/change-tracker.test.ts

@@ -4,6 +4,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import {
   installChangeTracking,
   installTriggersOnShardTables,
+  resetShardSchemaCache,
   purgeConsumedChanges,
   getChangesSince,
   getCurrentWatermark,
@@ -208,6 +209,7 @@ describe('shard table tracking', () => {
   let db: PGlite
 
   beforeEach(async () => {
+    resetShardSchemaCache()
     db = new PGlite()
     await db.waitReady
     await installChangeTracking(db)

package/src/replication/change-tracker.ts

@@ -153,6 +153,11 @@ async function installTriggersOnAllTables(db: PGlite): Promise<void> {
  */
 const processedShardSchemas = new Set<string>()
 
+/** reset shard schema cache (for tests) */
+export function resetShardSchemaCache(): void {
+  processedShardSchemas.clear()
+}
+
 export async function installTriggersOnShardTables(db: PGlite): Promise<void> {
   const result = await db.query<{ nspname: string }>(
     `SELECT nspname FROM pg_namespace