feat(zero-cache): config to turn on SQLite-only change log mode

packages/zero-cache/src/config/normalize.test.ts

@@ -10,6 +10,7 @@ function configWith(litestream: Partial<ZeroConfig['litestream']>): ZeroConfig {
     changeStreamer: {
       port: 4849,
       address: 'localhost',
+      pgChangeLogEnabled: true,
       sqliteChangeLogMode: 'off',
       sqliteChangeLogReadPercent: 0,
       sqliteChangeLogColdReadPercent: 0,
@@ -128,6 +129,46 @@ describe('config/normalize litestream v5 gating', () => {
 });
 
 describe('config/normalize SQLite change log', () => {
+  test('PG change log is enabled by default configuration', () => {
+    const config = configWith({});
+
+    expect(config.changeStreamer.pgChangeLogEnabled).toBe(true);
+    expect(() => assertNormalized(config)).not.toThrow();
+  });
+
+  test('disabling the PG change log requires authoritative SQLite and v5 backup settings', () => {
+    const config = configWith({});
+    config.changeStreamer.pgChangeLogEnabled = false;
+
+    expect(() => assertNormalized(config)).toThrow(
+      'requires --change-streamer-sqlite-change-log-mode=serve',
+    );
+
+    config.changeStreamer.sqliteChangeLogMode = 'serve';
+    expect(() => assertNormalized(config)).toThrow(
+      'requires --change-streamer-sqlite-change-log-read-percent=100',
+    );
+
+    config.changeStreamer.sqliteChangeLogReadPercent = 100;
+    expect(() => assertNormalized(config)).toThrow(
+      'requires --change-streamer-sqlite-change-log-cold-read-percent=100',
+    );
+
+    config.changeStreamer.sqliteChangeLogColdReadPercent = 100;
+    expect(() => assertNormalized(config)).toThrow(
+      'requires a litestream v5 backup',
+    );
+
+    Object.assign(config.litestream, {
+      backupURL: 's3://bucket/replica',
+      backupUsingV5: true,
+      restoreUsingV5: true,
+      executableV5: '/bin/litestream-v5',
+      vfsQueryExecutable: '/bin/vfs-query',
+    });
+    expect(() => assertNormalized(config)).not.toThrow();
+  });
+
   test('read percentage is only allowed in serve mode', () => {
     const config = configWith({});
     config.changeStreamer.sqliteChangeLogMode = 'compare';

packages/zero-cache/src/config/normalize.ts

@@ -53,6 +53,7 @@ export function assertNormalized(
   assert(config.changeStreamer.port, 'missing --change-streamer-port');
   assert(config.changeStreamer.address, 'missing --change-streamer-address');
   const {
+    pgChangeLogEnabled,
     sqliteChangeLogMode,
     sqliteChangeLogReadPercent,
     sqliteChangeLogColdReadPercent,
@@ -97,6 +98,24 @@ export function assertNormalized(
     sqliteChangeLogReadPercent > 0 || sqliteChangeLogColdReadPercent === 0,
     '--change-streamer-sqlite-change-log-cold-read-percent must be 0 when --change-streamer-sqlite-change-log-read-percent is 0',
   );
+  if (!pgChangeLogEnabled) {
+    assert(
+      sqliteChangeLogMode === 'serve',
+      '--change-streamer-pg-change-log-enabled=false requires --change-streamer-sqlite-change-log-mode=serve',
+    );
+    assert(
+      sqliteChangeLogReadPercent === 100,
+      '--change-streamer-pg-change-log-enabled=false requires --change-streamer-sqlite-change-log-read-percent=100',
+    );
+    assert(
+      sqliteChangeLogColdReadPercent === 100,
+      '--change-streamer-pg-change-log-enabled=false requires --change-streamer-sqlite-change-log-cold-read-percent=100',
+    );
+    assert(
+      config.litestream.backupURL && config.litestream.backupUsingV5,
+      '--change-streamer-pg-change-log-enabled=false requires a litestream v5 backup',
+    );
+  }
   for (const [flag, value] of [
     ['retention-ms', sqliteChangeLogRetentionMs],
     ['read-batch-rows', sqliteChangeLogReadBatchRows],

packages/zero-cache/src/config/zero-config.test.ts

@@ -905,6 +905,24 @@ test('--enable-query-covering can be disabled', () => {
   expect(config.enableQueryCovering).toBe(false);
 });
 
+test('PG change log is enabled by default and can be disabled by env', () => {
+  const defaults = parseOptionsAdvanced(zeroOptions, {
+    envNamePrefix: 'ZERO_',
+    allowUnknown: false,
+    allowPartial: true,
+    env: {},
+  }).config;
+  const disabled = parseOptionsAdvanced(zeroOptions, {
+    envNamePrefix: 'ZERO_',
+    allowUnknown: false,
+    allowPartial: true,
+    env: {ZERO_CHANGE_STREAMER_PG_CHANGE_LOG_ENABLED: 'false'},
+  }).config;
+
+  expect(defaults.changeStreamer.pgChangeLogEnabled).toBe(true);
+  expect(disabled.changeStreamer.pgChangeLogEnabled).toBe(false);
+});
+
 test('legacy queries are disabled by default', () => {
   const {config} = parseOptionsAdvanced(zeroOptions, {
     envNamePrefix: 'ZERO_',

packages/zero-cache/src/config/zero-config.ts

@@ -737,6 +737,16 @@ export const zeroOptions = {
       hidden: true,
     },
 
+    pgChangeLogEnabled: {
+      type: v.boolean().default(true),
+      desc: [
+        `Whether the legacy Postgres change log remains authoritative for`,
+        `stream initialization, persistence, catchup, and upstream ACKs.`,
+        `Disabling it requires SQLite serve mode at 100 percent and a v5 backup.`,
+      ],
+      hidden: true,
+    },
+
     sqliteChangeLogReadPercent: {
       type: v.number().default(0),
       desc: [

packages/zero-cache/src/server/change-streamer.ts

@@ -67,6 +67,7 @@ export default async function runWorker(
       backPressureLimitHeapProportion,
       flowControlConsensusTimeoutProportion,
       flowControlSlowSubscriberGracePeriodSeconds,
+      pgChangeLogEnabled,
       sqliteChangeLogMode,
       sqliteChangeLogReadPercent,
       sqliteChangeLogColdReadPercent,
@@ -123,7 +124,7 @@ export default async function runWorker(
   // purges. This ensures that (this) change-streamer will be able to resume
   // from the backup.
   let purgeLock =
-    litestream.backupURL && litestream.executable
+    pgChangeLogEnabled && litestream.backupURL && litestream.executable
       ? await new PurgeLocker(lc, shard, changeDB).acquire()
       : null;
   const restoreOptions = {litestream, constraints: purgeLock ?? undefined};
@@ -220,6 +221,7 @@ export default async function runWorker(
         purgeLock,
         autoReset ?? false,
         {
+          pgChangeLogEnabled,
           backPressureLimitHeapProportion,
           flowControlConsensusTimeoutProportion,
           flowControlSlowSubscriberGracePeriodMs:
@@ -258,14 +260,15 @@ export default async function runWorker(
               }
             : undefined,
           // Compare mode runs both advisory checks. Postgres remains authoritative.
-          sqliteChangeLogCompare: sqliteChangeLogComparing
-            ? {
-                replicaFile: replica.file,
-                comparePercent: sqliteChangeLogComparePercent,
-                retentionMs: sqliteChangeLogRetentionMs,
-                readBatchRows: sqliteChangeLogReadBatchRows,
-              }
-            : undefined,
+          sqliteChangeLogCompare:
+            pgChangeLogEnabled && sqliteChangeLogComparing
+              ? {
+                  replicaFile: replica.file,
+                  comparePercent: sqliteChangeLogComparePercent,
+                  retentionMs: sqliteChangeLogRetentionMs,
+                  readBatchRows: sqliteChangeLogReadBatchRows,
+                }
+              : undefined,
           // Slice 11 lands dark by default: serve mode constructs the stable
           // router, while readPercent=0 keeps every catchup on PG and emits
           // eligibility metrics before any canary traffic is enabled.