orez 0.1.49 → 0.2.0

package/src/config.ts

@@ -1,3 +1,5 @@
+import { availableParallelism } from 'node:os'
+
 import type { PGliteOptions } from '@electric-sql/pglite'
 
 export type LogLevel = 'error' | 'warn' | 'info' | 'debug'
@@ -19,6 +21,7 @@ export interface ZeroLiteConfig {
   forceWasmSqlite: boolean
   useWorkerThreads: boolean
   singleDb: boolean
+  readReplicas: number
   logLevel: LogLevel
   pgliteOptions: Partial<PGliteOptions>
   zeroPublications?: string
@@ -80,6 +83,8 @@ export interface OrezConfig {
   onDbReady?: Hook
   /** command to run once all services healthy */
   onHealthy?: Hook
+  /** number of pglite read replicas for postgres (default: auto, 0 to disable) */
+  readReplicas?: number
   /** pglite options */
   pgliteOptions?: Partial<PGliteOptions>
   /** ZERO_APP_PUBLICATIONS — comma-separated publication names */
@@ -110,6 +115,12 @@ export function getConfig(overrides: Partial<ZeroLiteConfig> = {}): ZeroLiteConf
     forceWasmSqlite: overrides.forceWasmSqlite ?? false,
     useWorkerThreads: overrides.useWorkerThreads ?? true,
     singleDb: overrides.singleDb ?? false,
+    // singleDb shares one pglite instance for all databases — replicas make no sense
+    readReplicas:
+      (overrides.singleDb ?? false)
+        ? 0
+        : (overrides.readReplicas ??
+          Math.min(Math.ceil(availableParallelism() * 0.5), 4)),
     logLevel: overrides.logLevel || (process.env.OREZ_LOG_LEVEL as LogLevel) || 'warn',
     pgliteOptions: overrides.pgliteOptions || {},
     zeroPublications: overrides.zeroPublications,

package/src/index.ts

@@ -37,6 +37,8 @@ import {
 import { installChangeTracking } from './replication/change-tracker.js'
 import { resetReplicationState } from './replication/handler.js'
 import {
+  applySqliteMode,
+  cleanupShim,
   formatNativeBootstrapInstructions,
   hasMissingNativeBinarySignature,
   inspectNativeSqliteBinary,
@@ -310,6 +312,13 @@ export async function startZeroLite(overrides: Partial<ZeroLiteConfig> = {}) {
     await installChangeTracking(db)
   }
 
+  // create read replicas after the primary is fully initialized
+  // (migrations, seed, change tracking, publications all set up)
+  if (config.readReplicas > 0 && config.useWorkerThreads) {
+    const { createReadReplicas } = await import('./pglite-manager.js')
+    instances.postgresReplicas = await createReadReplicas(db, config.readReplicas, config)
+  }
+
   // clean up stale sqlite replica from previous runs
   cleanupStaleReplica(config)
 
@@ -720,115 +729,6 @@ async function seedIfNeeded(db: PGlite, config: ZeroLiteConfig): Promise<void> {
   log.orez('seeded')
 }
 
-// install wasm shim into node_modules/@rocicorp/zero-sqlite3
-// backs up original and writes a conditional loader that switches based on env
-function installWasmShim(bedrockPath: string, zeroEntry: string): void {
-  // find node_modules where @rocicorp/zero is installed
-  const nodeModulesMatch = zeroEntry.match(/^(.+\/node_modules)\/@rocicorp\/zero\//)
-  if (!nodeModulesMatch) {
-    throw new Error(`cannot determine node_modules path from ${zeroEntry}`)
-  }
-  const nodeModules = nodeModulesMatch[1]
-  const shimDir = resolve(nodeModules, '@rocicorp', 'zero-sqlite3')
-  const indexPath = resolve(shimDir, 'index.js')
-  const originalPath = resolve(shimDir, 'index.original.js')
-  const wasmPath = resolve(shimDir, 'index.wasm.js')
-
-  // if directory doesn't exist, create it with just the wasm shim
-  if (!existsSync(shimDir)) {
-    mkdirSync(shimDir, { recursive: true })
-  }
-
-  // backup original if it exists and hasn't been backed up
-  if (existsSync(indexPath) && !existsSync(originalPath)) {
-    const content = readFileSync(indexPath, 'utf-8')
-    // only backup if it's not already our shim
-    if (!content.includes('orez-sqlite-shim')) {
-      writeFileSync(originalPath, content)
-      log.debug.orez('backed up original zero-sqlite3/index.js')
-    }
-  }
-
-  // write wasm implementation
-  writeFileSync(
-    wasmPath,
-    `// orez wasm sqlite implementation
-import bedrockSqlite from '${bedrockPath}';
-const { Database: OrigDatabase, SqliteError } = bedrockSqlite;
-
-function Database(...args) {
-  const db = new OrigDatabase(...args);
-  try {
-    db.pragma('journal_mode = wal2');
-    db.pragma('synchronous = off');
-    db.pragma('temp_store = memory');
-    db.pragma('busy_timeout = 30000');
-  } catch(e) {}
-  return db;
-}
-Database.prototype = OrigDatabase.prototype;
-Database.prototype.constructor = Database;
-Object.keys(OrigDatabase).forEach(k => { Database[k] = OrigDatabase[k]; });
-Database.prototype.unsafeMode = function() { return this; };
-if (!Database.prototype.defaultSafeIntegers) Database.prototype.defaultSafeIntegers = function() { return this; };
-if (!Database.prototype.serialize) Database.prototype.serialize = function() { throw new Error('not supported in wasm'); };
-if (!Database.prototype.backup) Database.prototype.backup = function() { throw new Error('not supported in wasm'); };
-
-const tmpDb = new OrigDatabase(':memory:');
-const tmpStmt = tmpDb.prepare('SELECT 1');
-const SP = Object.getPrototypeOf(tmpStmt);
-if (!SP.safeIntegers) SP.safeIntegers = function() { return this; };
-SP.scanStatus = function() { return undefined; };
-SP.scanStatusV2 = function() { return []; };
-SP.scanStatusReset = function() {};
-tmpDb.close();
-
-Database.SQLITE_SCANSTAT_NLOOP = 0;
-Database.SQLITE_SCANSTAT_NVISIT = 1;
-Database.SQLITE_SCANSTAT_EST = 2;
-Database.SQLITE_SCANSTAT_NAME = 3;
-Database.SQLITE_SCANSTAT_EXPLAIN = 4;
-Database.SQLITE_SCANSTAT_SELECTID = 5;
-Database.SQLITE_SCANSTAT_PARENTID = 6;
-Database.SQLITE_SCANSTAT_NCYCLE = 7;
-Database.SQLITE_SCANSTAT_COMPLEX = 8;
-
-export default Database;
-export { SqliteError };
-`
-  )
-
-  // write esm loader - always uses wasm since native requires compiled binary
-  // users who want native should use --disable-wasm-sqlite flag which skips this
-  writeFileSync(
-    indexPath,
-    `// orez-sqlite-shim: wasm sqlite for zero-cache
-// this file was generated by orez - original backed up to index.original.js
-export * from './index.wasm.js';
-export { default } from './index.wasm.js';
-`
-  )
-
-  // ensure package.json exists with correct config
-  const pkgPath = resolve(shimDir, 'package.json')
-  if (!existsSync(pkgPath)) {
-    writeFileSync(
-      pkgPath,
-      JSON.stringify(
-        {
-          name: '@rocicorp/zero-sqlite3',
-          version: '0.0.0-orez-shim',
-          main: './index.js',
-        },
-        null,
-        2
-      ) + '\n'
-    )
-  }
-
-  log.debug.orez(`installed wasm shim to ${shimDir}`)
-}
-
 async function startZeroCache(
   config: ZeroLiteConfig,
   logStore?: LogStore,
@@ -886,9 +786,12 @@ async function startZeroCache(
     throw new Error('zero-cache cli.js not found. install @rocicorp/zero')
   }
 
-  // install wasm shim into node_modules/@rocicorp/zero-sqlite3
-  if (sqliteMode === 'wasm' && sqliteModeConfig?.bedrockPath) {
-    installWasmShim(sqliteModeConfig.bedrockPath, zeroEntry)
+  // apply sqlite mode shim (wasm: patches lib/index.js, native: restores original)
+  if (sqliteModeConfig) {
+    const shimResult = applySqliteMode(sqliteModeConfig)
+    if (!shimResult.success) {
+      log.orez(`warning: sqlite shim failed: ${shimResult.error}`)
+    }
   }
 
   // preload script to label the zero-cache child process

package/src/mutex.ts

@@ -5,6 +5,11 @@ export class Mutex {
   private queue: Array<() => void> = []
   private head = 0
 
+  /** check if the mutex is currently held (non-blocking, no side effects) */
+  get isLocked(): boolean {
+    return this.locked
+  }
+
   async acquire(): Promise<void> {
     if (!this.locked) {
       this.locked = true

package/src/pg-proxy-browser.ts

@@ -682,7 +682,12 @@ export async function createBrowserProxy(
   const instances: PGliteInstances =
     'postgres' in dbInput
       ? (dbInput as PGliteInstances)
-      : { postgres: dbInput as PGlite, cvr: dbInput as PGlite, cdb: dbInput as PGlite }
+      : {
+          postgres: dbInput as PGlite,
+          cvr: dbInput as PGlite,
+          cdb: dbInput as PGlite,
+          postgresReplicas: [],
+        }
 
   // per-instance mutexes for serializing pglite access.
   // when all instances are the same object (single-db mode), share one mutex

package/src/pg-proxy.ts

@@ -418,24 +418,62 @@ function readInt32BE(data: Uint8Array, offset: number): number {
 }
 
 /**
- * extract ReadyForQuery status byte from a response.
- * returns the status: 'I' (0x49) idle, 'T' (0x54) in transaction, 'E' (0x45) error.
- * returns null if no ReadyForQuery found.
+ * single-pass response processor: extracts ReadyForQuery status AND
+ * optionally strips RFQ messages + benign notices in one scan.
+ * replaces the previous two-function approach that scanned the buffer twice.
  */
-function getReadyForQueryStatus(data: Uint8Array): number | null {
+interface ProcessedResponse {
+  data: Uint8Array
+  rfqStatus: number | null
+}
+
+function processResponse(data: Uint8Array, stripRfq: boolean): ProcessedResponse {
+  if (data.length === 0) return { data, rfqStatus: null }
+
+  let rfqStatus: number | null = null
+  const parts: Uint8Array[] = []
   let offset = 0
-  let lastStatus: number | null = null
+  let stripped = false
+
   while (offset < data.length) {
+    const msgType = data[offset]
     if (offset + 5 > data.length) break
     const msgLen = readInt32BE(data, offset + 1)
     const totalLen = 1 + msgLen
     if (totalLen <= 0 || offset + totalLen > data.length) break
-    if (data[offset] === 0x5a && totalLen >= 6) {
-      lastStatus = data[offset + 5]
+
+    if (msgType === 0x5a && totalLen >= 6) {
+      rfqStatus = data[offset + 5]
+      if (stripRfq) {
+        stripped = true
+        offset += totalLen
+        continue
+      }
+    } else {
+      const code = extractNoticeCode(data, offset, totalLen)
+      if (code && SUPPRESS_NOTICE_CODES.has(code)) {
+        stripped = true
+        offset += totalLen
+        continue
+      }
     }
+
+    parts.push(data.subarray(offset, offset + totalLen))
     offset += totalLen
   }
-  return lastStatus
+
+  if (!stripped) return { data, rfqStatus }
+  if (parts.length === 0) return { data: new Uint8Array(0), rfqStatus }
+  if (parts.length === 1) return { data: parts[0], rfqStatus }
+
+  const total = parts.reduce((sum, p) => sum + p.length, 0)
+  const result = new Uint8Array(total)
+  let pos = 0
+  for (const p of parts) {
+    result.set(p, pos)
+    pos += p.length
+  }
+  return { data: result, rfqStatus }
 }
 
 /**
@@ -492,54 +530,9 @@ function extractNoticeCode(
   return null
 }
 
-/**
- * single-pass response message filter. strips ReadyForQuery messages (when
- * stripRfq=true) and benign transaction state warnings in one scan.
- */
+// legacy wrapper for callers that only need filtering (no RFQ status)
 function stripResponseMessages(data: Uint8Array, stripRfq: boolean): Uint8Array {
-  if (data.length === 0) return data
-
-  const parts: Uint8Array[] = []
-  let offset = 0
-  let stripped = false
-
-  while (offset < data.length) {
-    const msgType = data[offset]
-    if (offset + 5 > data.length) break
-    const msgLen = readInt32BE(data, offset + 1)
-    const totalLen = 1 + msgLen
-
-    if (totalLen <= 0 || offset + totalLen > data.length) break
-
-    // strip ReadyForQuery (0x5a) when requested
-    if (stripRfq && msgType === 0x5a) {
-      stripped = true
-    }
-    // strip benign transaction state notices
-    else {
-      const code = extractNoticeCode(data, offset, totalLen)
-      if (code && SUPPRESS_NOTICE_CODES.has(code)) {
-        stripped = true
-      } else {
-        parts.push(data.subarray(offset, offset + totalLen))
-      }
-    }
-
-    offset += totalLen
-  }
-
-  if (!stripped) return data
-  if (parts.length === 0) return new Uint8Array(0)
-  if (parts.length === 1) return parts[0]
-
-  const total = parts.reduce((sum, p) => sum + p.length, 0)
-  const result = new Uint8Array(total)
-  let pos = 0
-  for (const p of parts) {
-    result.set(p, pos)
-    pos += p.length
-  }
-  return result
+  return processResponse(data, stripRfq).data
 }
 
 export async function startPgProxy(
@@ -550,7 +543,12 @@ export async function startPgProxy(
   const instances: PGliteInstances =
     'postgres' in dbInput
       ? (dbInput as PGliteInstances)
-      : { postgres: dbInput as PGlite, cvr: dbInput as PGlite, cdb: dbInput as PGlite }
+      : {
+          postgres: dbInput as PGlite,
+          cvr: dbInput as PGlite,
+          cdb: dbInput as PGlite,
+          postgresReplicas: [],
+        }
 
   // per-instance mutexes for serializing pglite access.
   // when all instances are the same object (single-db mode), share one mutex
@@ -564,6 +562,24 @@ export async function startPgProxy(
     cdb: sharedInstance ? pgMutex : new Mutex(),
   }
 
+  // replica state: initialized lazily when replicas become available.
+  // instances.postgresReplicas is populated AFTER the proxy starts
+  // (replicas are created after migrations/on-db-ready run via TCP proxy).
+  const replicaMutexes: Mutex[] = []
+  let replicasInitialized = false
+  let nextReplicaIdx = 0
+
+  function ensureReplicaState() {
+    if (replicasInitialized) return
+    const replicas = instances.postgresReplicas
+    if (replicas.length === 0) return
+    replicasInitialized = true
+    for (let i = 0; i < replicas.length; i++) {
+      replicaMutexes.push(new Mutex())
+    }
+    log.proxy(`${replicas.length} postgres read replica(s) active`)
+  }
+
   // per-instance transaction state: tracks which socket owns the current transaction
   // so we can auto-ROLLBACK stale aborted transactions from other connections
   const txStates: Record<string, PgLiteTxState> = {
@@ -585,6 +601,38 @@ export async function startPgProxy(
     return { db: instances.postgres, mutex: mutexes.postgres, txState: txStates.postgres }
   }
 
+  /**
+   * try to acquire a read replica for a postgres SELECT query.
+   * returns null if no replicas are available or all are busy.
+   * used for per-query routing: only non-transactional SELECTs can use replicas.
+   */
+  function tryAcquireReadReplica(): { db: PGlite; mutex: Mutex } | null {
+    ensureReplicaState()
+    const replicas = instances.postgresReplicas
+    if (replicas.length === 0) return null
+    // round-robin with tryAcquire: find the first available replica
+    for (let i = 0; i < replicas.length; i++) {
+      const idx = (nextReplicaIdx + i) % replicas.length
+      if (replicaMutexes[idx].tryAcquire()) {
+        nextReplicaIdx = idx + 1
+        return { db: replicas[idx], mutex: replicaMutexes[idx] }
+      }
+    }
+    return null // all replicas busy, fall back to primary
+  }
+
+  /**
+   * fan-out a write SQL to all postgres replicas.
+   * fire-and-forget — replica staleness is acceptable for a dev tool.
+   */
+  function fanOutWriteToReplicas(sql: string) {
+    const replicas = instances.postgresReplicas
+    if (replicas.length === 0) return
+    for (const replica of replicas) {
+      replica.exec(sql).catch(() => {})
+    }
+  }
+
   // signal replication handler after extended protocol writes complete.
   // 8ms leading-edge debounce: fires exactly 8ms after the FIRST write,
   // subsequent writes within that window are batched (handler polls all
@@ -779,11 +827,13 @@ export async function startPgProxy(
             proxyStats.totalExecMs += t2 - t1
             proxyStats.count++
 
-            // update transaction state
-            const rfqStatus = getReadyForQueryStatus(result)
-            if (rfqStatus !== null) {
-              txState.status = rfqStatus
-              txState.owner = rfqStatus === 0x49 ? null : socket
+            // single-pass: extract tx status + strip RFQ from non-Sync messages
+            const stripRfqFromPipeline = msgType !== 0x53
+            const processed = processResponse(result, stripRfqFromPipeline)
+            result = processed.data
+            if (processed.rfqStatus !== null) {
+              txState.status = processed.rfqStatus
+              txState.owner = processed.rfqStatus === 0x49 ? null : socket
             }
 
             // release mutex on Sync (end of pipeline)
@@ -797,9 +847,6 @@ export async function startPgProxy(
                 extWritePending = false
                 signalWrite()
               }
-            } else {
-              // strip ReadyForQuery from non-Sync pipeline messages
-              result = stripResponseMessages(result, true)
             }
 
             if (proxyStats.count % 200 === 0) {
@@ -853,6 +900,34 @@ export async function startPgProxy(
             }
           }
 
+          // per-query replica spillover: when the primary is busy with another query,
+          // route read-only SELECTs to an available replica instead of waiting.
+          // only for: postgres db, non-write, non-DDL, not in a transaction, primary contended.
+          if (
+            dbName === 'postgres' &&
+            queryNorm &&
+            !isWriteNormalized(queryNorm) &&
+            !isDDLNormalized(queryNorm) &&
+            txState.status === 0x49 &&
+            mutex.isLocked // primary is busy — try spilling to replica
+          ) {
+            const replica = tryAcquireReadReplica()
+            if (replica) {
+              const t1 = performance.now()
+              let result: Uint8Array
+              try {
+                result = await replica.db.execProtocolRaw(data, { syncToFs: false })
+              } catch (err) {
+                replica.mutex.release()
+                throw err
+              }
+              replica.mutex.release()
+              proxyStats.totalExecMs += performance.now() - t1
+              proxyStats.count++
+              return processResponse(result, false).data
+            }
+          }
+
           const execute = async (): Promise<Uint8Array> => {
             const t0 = performance.now()
             await mutex.acquire()
@@ -871,13 +946,17 @@ export async function startPgProxy(
               mutex.release()
               throw err
             }
-            const rfqStatus = getReadyForQueryStatus(result)
-            if (rfqStatus !== null) {
-              txState.status = rfqStatus
-              txState.owner = rfqStatus === 0x49 ? null : socket
-            }
             const t2 = performance.now()
             mutex.release()
+
+            // single-pass: extract tx status + strip messages
+            const doStripRfq = msgType !== 0x53 && msgType !== 0x51
+            const processed = processResponse(result, doStripRfq)
+            if (processed.rfqStatus !== null) {
+              txState.status = processed.rfqStatus
+              txState.owner = processed.rfqStatus === 0x49 ? null : socket
+            }
+
             proxyStats.totalWaitMs += t1 - t0
             proxyStats.totalExecMs += t2 - t1
             proxyStats.count++
@@ -886,7 +965,7 @@ export async function startPgProxy(
                 `perf: ${proxyStats.count} ops (${proxyStats.batches} batches) | mutex ${proxyStats.totalWaitMs.toFixed(0)}ms | pglite ${proxyStats.totalExecMs.toFixed(0)}ms`
               )
             }
-            return result
+            return processed.data
           }
 
           let result: Uint8Array
@@ -909,12 +988,19 @@ export async function startPgProxy(
             }
           }
 
-          const stripRfq = msgType !== 0x53 && msgType !== 0x51
-          result = stripResponseMessages(result, stripRfq)
-
           // signal replication handler on postgres writes for instant sync
           if (dbName === 'postgres' && queryNorm && isWriteNormalized(queryNorm)) {
             signalReplicationChange()
+            if (queryText) fanOutWriteToReplicas(queryText)
+          }
+          // fan-out DDL to replicas so schema stays in sync
+          if (
+            dbName === 'postgres' &&
+            queryNorm &&
+            isDDLNormalized(queryNorm) &&
+            queryText
+          ) {
+            fanOutWriteToReplicas(queryText)
           }
 
           return result

package/src/pglite-ipc.ts

@@ -162,6 +162,29 @@ export class PGliteWorkerProxy {
     return new Uint8Array(result.data)
   }
 
+  /**
+   * execute multiple wire protocol messages in a single IPC round-trip.
+   * each message is executed sequentially in the worker, and all results
+   * are concatenated and returned. eliminates N-1 postMessage round-trips
+   * for extended protocol pipelines (Parse→Bind→Execute→Sync).
+   */
+  async execProtocolRawBatch(
+    messages: Uint8Array[],
+    options?: { syncToFs?: boolean; throwOnError?: boolean }
+  ): Promise<Uint8Array> {
+    const buffers: ArrayBuffer[] = []
+    for (const msg of messages) {
+      const buf = new ArrayBuffer(msg.byteLength)
+      new Uint8Array(buf).set(msg)
+      buffers.push(buf)
+    }
+    const result = await this.send(
+      { type: 'execProtocolRawBatch', buffers, options },
+      buffers
+    )
+    return new Uint8Array(result.data)
+  }
+
   async query<T = any>(
     sql: string,
     params?: any[]
@@ -204,6 +227,15 @@ export class PGliteWorkerProxy {
     }
   }
 
+  /**
+   * dump the PGlite data directory as a tar blob.
+   * used to create read replicas from an existing instance.
+   */
+  async dumpDataDir(): Promise<ArrayBuffer> {
+    const result = await this.send({ type: 'dumpDataDir' })
+    return result.data as ArrayBuffer
+  }
+
   async close(): Promise<void> {
     try {
       await this.send({ type: 'close' })

package/src/pglite-manager.ts

@@ -76,6 +76,8 @@ export interface PGliteInstances {
   postgres: PGlite
   cvr: PGlite
   cdb: PGlite
+  /** read replicas of the postgres instance (empty if disabled) */
+  postgresReplicas: PGlite[]
 }
 
 // shared setup extracted from the 4 factory functions below
@@ -262,7 +264,7 @@ export async function createPGliteInstances(
   ])
 
   await ensurePublication(postgres)
-  return { postgres, cvr, cdb }
+  return { postgres, cvr, cdb, postgresReplicas: [] }
 }
 
 /**
@@ -318,6 +320,7 @@ export async function createPGliteWorkerInstances(
     postgres: pgProxy as unknown as PGlite,
     cvr: cvrProxy as unknown as PGlite,
     cdb: cdbProxy as unknown as PGlite,
+    postgresReplicas: [],
   }
 }
 
@@ -338,7 +341,7 @@ export async function createSinglePGliteInstance(
   await ensurePublication(db)
 
   // same instance for all three — pg-proxy detects this and shares a mutex
-  return { postgres: db, cvr: db, cdb: db }
+  return { postgres: db, cvr: db, cdb: db, postgresReplicas: [] }
 }
 
 /**
@@ -382,7 +385,7 @@ export async function createSinglePGliteWorkerInstance(
   await ensurePublication(proxy)
 
   const db = proxy as unknown as PGlite
-  return { postgres: db, cvr: db, cdb: db }
+  return { postgres: db, cvr: db, cdb: db, postgresReplicas: [] }
 }
 
 /** create a single worker-backed PGlite instance (for CVR/CDB recreation during reset) */
@@ -396,6 +399,60 @@ export function createPGliteWorker(dataDir: string, name: string): PGliteWorkerP
   })
 }
 
+/**
+ * create read replicas of the postgres instance.
+ *
+ * dumps the primary's data directory and initializes N new worker threads
+ * from the dump. each replica is an independent PGlite instance on its own
+ * core, handling read queries concurrently.
+ *
+ * call this AFTER migrations, seed, on-db-ready — the dump captures the
+ * full database state at the time of cloning.
+ */
+export async function createReadReplicas(
+  primary: PGlite,
+  count: number,
+  config: ZeroLiteConfig
+): Promise<PGlite[]> {
+  if (count <= 0) return []
+
+  const proxy = primary as unknown as PGliteWorkerProxy
+  if (typeof proxy.dumpDataDir !== 'function') {
+    log.pglite('read replicas require worker threads (dumpDataDir not available)')
+    return []
+  }
+
+  log.pglite(`creating ${count} read replica(s)...`)
+  const t0 = performance.now()
+
+  const dump = await proxy.dumpDataDir()
+  log.debug.pglite(`primary dump: ${(dump.byteLength / 1024 / 1024).toFixed(1)}MB`)
+
+  const {
+    dataDir: _ud,
+    debug: _dbg,
+    ...userOpts
+  } = config.pgliteOptions as Record<string, any>
+
+  const replicas: PGliteWorkerProxy[] = []
+  for (let i = 0; i < count; i++) {
+    const replica = new PGliteWorkerProxy({
+      dataDir: 'memory://',
+      name: `postgres-replica-${i}`,
+      withExtensions: true,
+      debug: config.logLevel === 'debug' ? 1 : 0,
+      pgliteOptions: userOpts,
+      loadDataDir: dump,
+    })
+    replicas.push(replica)
+  }
+
+  await Promise.all(replicas.map((r) => r.waitReady))
+  log.pglite(`${count} read replica(s) ready in ${(performance.now() - t0).toFixed(0)}ms`)
+
+  return replicas as unknown as PGlite[]
+}
+
 /** run pending migrations, returns count of newly applied migrations */
 export async function runMigrations(db: PGlite, config: ZeroLiteConfig): Promise<number> {
   if (!config.migrationsDir) {