@rocicorp/zero 1.11.0-canary.4 → 1.11.0-canary.41

package/out/zero-cache/src/services/change-source/pg/schema/shard.d.ts

@@ -4,6 +4,7 @@ import * as v from '../../../../../../shared/src/valita.ts';
 import type { PostgresDB, PostgresTransaction } from '../../../../types/pg.ts';
 import type { AppID, ShardConfig, ShardID } from '../../../../types/shards.ts';
 import { type PublicationInfo, type PublishedSchema } from './published.ts';
+import { type ReplicaStage } from './replica-stage-enum.ts';
 /**
  * Validates that a publication name is a valid PostgreSQL identifier.
  * This provides defense-in-depth against SQL injection when publication
@@ -38,15 +39,28 @@ declare const internalShardConfigSchema: v.ObjectType<{
     ddlDetection: v.Type<boolean>;
 }, undefined>;
 export type InternalShardConfig = v.Infer<typeof internalShardConfigSchema>;
-declare const replicaSchema: v.Type<{
-    publications: string[];
-    ddlDetection: boolean;
-    id: string;
-    rank: bigint;
-    slot: string;
-    backupPath: string | null;
-    backupV5: boolean;
-    initialSchema: {
+declare const replicaSchema: v.ObjectType<Omit<{
+    publications: v.ArrayType<v.Type<string>>;
+    ddlDetection: v.Type<boolean>;
+}, "backupPath" | "backupV5" | "epoch" | "generation" | "id" | "initialSchema" | "initialSyncContext" | "pgChangeLog" | "rank" | "slot" | "stage" | "subscriberContext"> & Omit<{
+    id: v.Type<string>;
+    rank: v.Type<bigint>;
+    slot: v.Type<string>;
+    epoch: v.Type<number>;
+    generation: v.Type<string>;
+    stage: v.Type<0 | 1 | 2>;
+    backupPath: v.UnionType<[v.Type<null>, v.Type<string>]>;
+    backupV5: v.Type<boolean>;
+    /**
+     * Whether the replication-manager that took over the replica's slot acks it
+     * only after storing transactions in the PG change log (i.e. RMv1.5). The
+     * slot's position past the change log's head then reflects acked
+     * keepalives, rather than transactions missing from the change log.
+     * False if unknown.
+     */
+    pgChangeLog: v.Type<boolean>;
+}, "initialSchema" | "initialSyncContext" | "subscriberContext"> & {
+    initialSchema: v.Type<{
         indexes: {
             readonly name: string;
             readonly tableName: string;
@@ -111,26 +125,38 @@ declare const replicaSchema: v.Type<{
             };
             replicaIdentityColumns: string[];
         }[];
-    };
-    initialSyncContext: Readonly<Record<string, import("../../../../../../shared/src/bigint-json.ts").JSONValue>> | null;
-    subscriberContext: Readonly<Record<string, import("../../../../../../shared/src/bigint-json.ts").JSONValue>> | null;
-    generation: string;
-}>;
+    }>;
+    initialSyncContext: v.UnionType<[v.Type<null>, v.Type<Readonly<Record<string, import("../../../../../../shared/src/bigint-json.ts").JSONValue>>>]>;
+    subscriberContext: v.UnionType<[v.Type<null>, v.Type<Readonly<Record<string, import("../../../../../../shared/src/bigint-json.ts").JSONValue>>>]>;
+}, undefined>;
 export type Replica = v.Infer<typeof replicaSchema>;
-declare const replicaStateSchema: v.Type<{
-    id: string;
-    rank: bigint;
-    slot: string;
-    backupPath: string | null;
-    backupV5: boolean;
-    active: boolean;
-    confirmedFlushLsn: string | null;
-    generation: string;
-}>;
+declare const replicaStateSchema: v.ObjectType<Omit<{
+    id: v.Type<string>;
+    rank: v.Type<bigint>;
+    slot: v.Type<string>;
+    epoch: v.Type<number>;
+    generation: v.Type<string>;
+    stage: v.Type<0 | 1 | 2>;
+    backupPath: v.UnionType<[v.Type<null>, v.Type<string>]>;
+    backupV5: v.Type<boolean>;
+    /**
+     * Whether the replication-manager that took over the replica's slot acks it
+     * only after storing transactions in the PG change log (i.e. RMv1.5). The
+     * slot's position past the change log's head then reflects acked
+     * keepalives, rather than transactions missing from the change log.
+     * False if unknown.
+     */
+    pgChangeLog: v.Type<boolean>;
+}, "active" | "confirmedFlushLsn"> & {
+    active: v.Type<boolean>;
+    confirmedFlushLsn: v.Type<string>;
+}, undefined>;
 export type ReplicaState = v.Infer<typeof replicaStateSchema>;
 export type BackupOptions = {
     backupPath: string | null;
     backupV5: boolean;
+    /** See `pgChangeLog` in {@link ReplicaState}. */
+    pgChangeLog: boolean;
 };
 /**
  * Creates a new replica to mark it as the owner of a specified `slot`.
@@ -138,17 +164,32 @@ export type BackupOptions = {
  * to ensure that the slot does not get dropped by concurrent cleanup
  * logic.
  *
- * Once initial sync is complete, {@link initReplica} should be called to
+ * Once initial sync is complete, {@link initInitialSyncReplica} should be called to
  * make the replica usable for incremental sync.
  */
-export declare function createReplica(sql: PostgresDB, shard: ShardID, id: string, slot: string, replicaVersion: string, { backupPath, backupV5 }: BackupOptions): Promise<void>;
-export declare function initReplica(sql: PostgresDB, shard: ShardID, id: string, { tables, indexes }: PublishedSchema, initialSyncContext: JSONObject): Promise<void>;
+export declare function createReplica(sql: PostgresDB, shard: ShardID, id: string, slot: string, epoch: number, replicaVersion: string, { backupPath, backupV5, pgChangeLog }: BackupOptions, stage: ReplicaStage): Promise<void>;
+export declare function initInitialSyncReplica(sql: PostgresDB, shard: ShardID, id: string, { tables, indexes }: PublishedSchema, initialSyncContext: JSONObject): Promise<void>;
+export declare function initRestoreReplica(sql: PostgresDB, shard: ShardID, { sourceID, destID }: {
+    sourceID: string;
+    destID: string;
+}): Promise<ReplicaState | null>;
 /**
  * Gets at the given version and optional ID. If no ID is specified, gets
  * the latest (i.e. highest rank) replica with that version.
  */
 export declare function getReplicaAtVersion(lc: LogContext, sql: PostgresDB, shard: ShardID, replicaVersion: string, id?: string | null, context?: JSONObject): Promise<Replica | null>;
 export declare function getActiveReplicas(lc: LogContext, sql: PostgresDB, shard: ShardID): Promise<ReplicaState[]>;
+/**
+ * Returns candidates for restoring a new replica from. These include
+ * all replicas in the newest `generation` of the given `epoch`, in order
+ * of earliest available backup:
+ * - An active InitialSync replica, which will be the only replica in
+ *   its generation by definition. Orphaned/inactive initial syncs are skipped.
+ * - Replicas in the Replicate stage, active first.
+ * - Replicas in the Restore stage, potentially available for resumption
+ *   as a last resort.
+ */
+export declare function getRestoreCandidates(sql: PostgresDB, shard: ShardID, epoch: number): Promise<ReplicaState[]>;
 export declare function getReplicaState(sql: PostgresDB, shard: ShardID, id: string): Promise<ReplicaState | null>;
 export declare function getInternalShardConfig(sql: PostgresDB, shard: ShardID): Promise<InternalShardConfig>;
 /**

package/out/zero-cache/src/services/change-source/pg/schema/shard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shard.d.ts","sourceRoot":"","sources":["../../../../../../../../zero-cache/src/services/change-source/pg/schema/shard.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAIjD,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,6CAA6C,CAAC;AACrD,OAAO,KAAK,CAAC,MAAM,wCAAwC,CAAC;AAE5D,OAAO,KAAK,EAAC,UAAU,EAAE,mBAAmB,EAAC,MAAM,yBAAyB,CAAC;AAC7E,OAAO,KAAK,EAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAC,MAAM,6BAA6B,CAAC;AAO7E,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AASxB;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAY1D;AAED,wBAAgB,yBAAyB,CAAC,EAAC,KAAK,EAAC,EAAE,KAAK,UAEvD;AAED,wBAAgB,qBAAqB,CAAC,EAAC,KAAK,EAAE,QAAQ,EAAC,EAAE,OAAO,UAE/D;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,UAGnD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,UAIvD;AAMD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GAAG,MAAM,UAGzB;AAoCD,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,iBAEpE;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,UASvD;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,UASzD;AAED,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAEhD,wBAAgB,UAAU,CACxB,WAAW,EAAE,WAAW,EACxB,mBAAmB,EAAE,MAAM,GAC1B,MAAM,CAmDR;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAYzE;AAED,QAAA,MAAM,yBAAyB;;;aAG7B,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAkB5E,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKf,CAAC;AAEL,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAOpD,QAAA,MAAM,kBAAkB;;;;;;;;;EAKpB,CAAC;AAEL,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAa9D,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,OAAO,EACd,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,EAAC,UAAU,EAAE,QAAQ,EAAC,EAAE,aAAa,iBAYtC;AAGD,wBAAsB,WAAW,CAC/B,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,OAAO,EACd,EAAE,EAAE,MAAM,EACV,EAAC,MAAM,EAAE,OAAO,EAAC,EAAE,eAAe,EAClC,kBAAkB,EAAE,UAAU,iBAM/B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,UAAU,EACd,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,MAAM,EACtB,EAAE,GAAE,MAAM,GAAG,IAAW,EACxB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAkCzB;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,UAAU,EACd,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,YAAY,EAAE,CAAC,CAoBzB;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,OAAO,EACd,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAmB9B;AAED,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,mBAAmB,CAAC,CAU9B;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,UAAU,EACd,GAAG,EAAE,mBAAmB,EACxB,SAAS,EAAE,WAAW,EACtB,qBAAqB,UAAO,iBAyD7B;AAED,wBAAsB,aAAa,CACjC,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,mBAAmB,EACvB,KAAK,EAAE,WAAW,EAClB,qBAAqB,UAAO,iBAmC7B;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,UAAU,EACd,SAAS,EAAE,eAAe,QAkB3B;AAED,KAAK,iBAAiB,GAAG;IACvB,KAAK,CAAC,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD,CAAC;AAEF,wBAAgB,4CAA4C,CAC1D,IAAI,EAAE,eAAe,GACpB,iBAAiB,GAAG,SAAS,CAgD/B"}
+{"version":3,"file":"shard.d.ts","sourceRoot":"","sources":["../../../../../../../../zero-cache/src/services/change-source/pg/schema/shard.ts"],"names":[],"mappings":"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"}

package/out/zero-cache/src/services/change-source/pg/schema/shard.js

@@ -5,6 +5,7 @@ import { appSchema, check, upstreamSchema } from "../../../../types/shards.js";
 import { id } from "../../../../types/sql.js";
 import { getPublicationInfo, publishedSchema } from "./published.js";
 import { createEventFunctionStatements, createEventTriggerStatements } from "./ddl.js";
+import { replicaStageSchema } from "./replica-stage-enum.js";
 import { validate } from "./validation.js";
 import postgres from "postgres";
 import { PG_INSUFFICIENT_PRIVILEGE } from "@drdgvhbh/postgres-error-codes";
@@ -121,10 +122,6 @@ function shardSetup(shardConfig, metadataPublication) {
   ${getClientsTableDefinition(shard)}
   ${getMutationsTableDefinition(shard)}
 
-  DROP PUBLICATION IF EXISTS ${id(metadataPublication)};
-  CREATE PUBLICATION ${id(metadataPublication)}
-    FOR TABLE ${app}."permissions", TABLE ${shard}."clients", ${shard}."mutations";
-
   CREATE TABLE ${shard}."${SHARD_CONFIG_TABLE}" (
     "publications"  TEXT[] NOT NULL,
     "ddlDetection"  BOOL NOT NULL,
@@ -147,14 +144,25 @@ function shardSetup(shardConfig, metadataPublication) {
     "id"                 TEXT PRIMARY KEY DEFAULT replace(gen_random_uuid()::text, '-', ''),
     "rank"               BIGSERIAL,
     "slot"               TEXT NOT NULL,
-    "version"            TEXT NOT NULL,
-    "generation"         TEXT,  -- to replace version, NULL-able in the interim
+    "version"            TEXT,  -- replaced by generation, slated for deletion
+    "epoch"              INT4 DEFAULT 0,
+    "generation"         TEXT NOT NULL,
+    "stage"              INT4 DEFAULT 0,
     "backupPath"         TEXT,  -- subpath within the litestream backup URL
     "backupV5"           BOOL DEFAULT false,
+    -- Whether the slot is acked only after storing in the PG change log.
+    "pgChangeLog"        BOOL DEFAULT false,
     "initialSchema"      JSON,  -- set after initial sync
     "initialSyncContext" JSON,
     "subscriberContext"  JSON
   );
+
+  DROP PUBLICATION IF EXISTS ${id(metadataPublication)};
+  CREATE PUBLICATION ${id(metadataPublication)}
+    FOR TABLE ${app}."permissions", 
+        TABLE ${shard}."clients", 
+              ${shard}."mutations", 
+              ${shard}."replicas" (id);  -- advance the LSN/version with new replicas
   `;
 }
 function dropShard(appID, shardID) {
@@ -174,34 +182,31 @@ var replicaInfoSchema = valita_exports.object({
 	id: valita_exports.string(),
 	rank: valita_exports.bigint(),
 	slot: valita_exports.string(),
-	version: valita_exports.string(),
-	generation: valita_exports.string().nullable(),
+	epoch: valita_exports.number(),
+	generation: valita_exports.string(),
+	stage: replicaStageSchema,
 	backupPath: valita_exports.string().nullable(),
-	backupV5: valita_exports.boolean()
+	backupV5: valita_exports.boolean(),
+	/**
+	* Whether the replication-manager that took over the replica's slot acks it
+	* only after storing transactions in the PG change log (i.e. RMv1.5). The
+	* slot's position past the change log's head then reflects acked
+	* keepalives, rather than transactions missing from the change log.
+	* False if unknown.
+	*/
+	pgChangeLog: valita_exports.boolean()
 });
 var fullReplicaRowSchema = replicaInfoSchema.extend({
 	initialSchema: publishedSchema,
 	initialSyncContext: jsonObjectSchema.nullable(),
 	subscriberContext: jsonObjectSchema.nullable()
 });
-var replicaSchema = internalShardConfigSchema.extend(fullReplicaRowSchema.shape).map((replica) => {
-	const { version, generation, ...r } = replica;
-	return {
-		...r,
-		generation: generation ?? version
-	};
-});
+var replicaSchema = internalShardConfigSchema.extend(fullReplicaRowSchema.shape);
 var replicationSlotStateSchema = valita_exports.object({
 	active: valita_exports.boolean(),
-	confirmedFlushLsn: valita_exports.string().nullable()
-});
-var replicaStateSchema = replicaInfoSchema.extend(replicationSlotStateSchema.shape).map((replica) => {
-	const { version, generation, ...r } = replica;
-	return {
-		...r,
-		generation: generation ?? version
-	};
+	confirmedFlushLsn: valita_exports.string()
 });
+var replicaStateSchema = replicaInfoSchema.extend(replicationSlotStateSchema.shape);
 function triggerSetup(shard) {
 	const schema = id(upstreamSchema(shard));
 	return createEventTriggerStatements(shard) + `UPDATE ${schema}."shardConfig" SET "ddlDetection" = true;`;
@@ -212,22 +217,25 @@ function triggerSetup(shard) {
 * to ensure that the slot does not get dropped by concurrent cleanup
 * logic.
 *
-* Once initial sync is complete, {@link initReplica} should be called to
+* Once initial sync is complete, {@link initInitialSyncReplica} should be called to
 * make the replica usable for incremental sync.
 */
-async function createReplica(sql, shard, id, slot, replicaVersion, { backupPath, backupV5 }) {
+async function createReplica(sql, shard, id, slot, epoch, replicaVersion, { backupPath, backupV5, pgChangeLog }, stage) {
 	const schema = upstreamSchema(shard);
 	const values = {
 		id,
 		slot,
-		version: replicaVersion,
+		epoch,
 		generation: replicaVersion,
+		version: replicaVersion,
 		backupPath,
-		backupV5
+		backupV5,
+		pgChangeLog,
+		stage
 	};
 	await sql`INSERT INTO ${sql(schema)}.replicas ${sql(values)}`;
 }
-async function initReplica(sql, shard, id, { tables, indexes }, initialSyncContext) {
+async function initInitialSyncReplica(sql, shard, id, { tables, indexes }, initialSyncContext) {
 	const schema = upstreamSchema(shard);
 	const values = {
 		initialSchema: {
@@ -238,6 +246,19 @@ async function initReplica(sql, shard, id, { tables, indexes }, initialSyncConte
 	};
 	await sql`UPDATE ${sql(schema)}.replicas SET ${sql(values)} WHERE id = ${id}`;
 }
+async function initRestoreReplica(sql, shard, { sourceID, destID }) {
+	const schema = upstreamSchema(shard);
+	await sql`
+    UPDATE ${sql(schema)}.replicas dest 
+      SET "generation"         = source."generation",
+          "version"            = source."generation",
+          "initialSchema"      = source."initialSchema",
+          "initialSyncContext" = source."initialSyncContext"
+      FROM ${sql(schema)}.replicas source
+      WHERE source.id = ${sourceID} AND dest.id = ${destID};
+  `;
+	return getReplicaState(sql, shard, destID);
+}
 /**
 * Gets at the given version and optional ID. If no ID is specified, gets
 * the latest (i.e. highest rank) replica with that version.
@@ -249,23 +270,25 @@ async function getReplicaAtVersion(lc, sql, shard, replicaVersion, id = null, co
       replicas."id",
       replicas."rank",
       replicas."slot",
-      replicas."version",
+      replicas."epoch",
       replicas."generation",
+      replicas."stage",
       replicas."backupPath",
       replicas."backupV5",
+      replicas."pgChangeLog",
       replicas."initialSchema",
       replicas."initialSyncContext",
       replicas."subscriberContext",
       "shardConfig"."publications",
       "shardConfig"."ddlDetection"
     FROM ${schema}.replicas JOIN ${schema}."shardConfig" ON true
-      WHERE version = ${replicaVersion} AND "initialSyncContext" IS NOT NULL
+      WHERE generation = ${replicaVersion} AND "initialSyncContext" IS NOT NULL
       AND id = COALESCE(${id}, id)
       ORDER BY rank DESC LIMIT 1;
   `;
 	if (result.length === 0) {
 		const allReplicas = await sql`
-      SELECT id, slot, version, "initialSyncContext", "subscriberContext" 
+      SELECT id, slot, generation, "initialSyncContext", "subscriberContext" 
         FROM ${schema}.replicas`;
 		lc.info?.(`Replica ${id}@${replicaVersion}` + (context ? `(context: ${stringify(context)}) ` : "") + `not found in: ${stringify(allReplicas)}`);
 		return null;
@@ -278,29 +301,87 @@ async function getActiveReplicas(lc, sql, shard) {
       replicas."id",
       replicas."rank",
       replicas."slot",
-      replicas."version",
+      replicas."epoch",
       replicas."generation",
+      replicas."stage",
       replicas."backupPath",
       replicas."backupV5",
+      replicas."pgChangeLog",
       slots."active",
       slots."confirmed_flush_lsn" as "confirmedFlushLsn"
     FROM ${sql(upstreamSchema(shard))}.replicas JOIN pg_replication_slots slots ON slot = slot_name
       WHERE "initialSyncContext" IS NOT NULL
+        -- Exclude replicas whose slot has been invalidated (e.g. for exceeding
+        -- max_slot_wal_keep_size). Such a replica can never be resumed, and
+        -- restoring it just results in an AutoResetSignal on every attempt.
+        AND slots.restart_lsn IS NOT NULL
+        AND slots.wal_status IS DISTINCT FROM 'lost'
       ORDER BY generation DESC, confirmed_flush_lsn DESC;
   `, valita_exports.array(replicaStateSchema), "passthrough");
 	lc.info?.(`current replicas`, { replicas });
 	return replicas;
 }
+/**
+* Returns candidates for restoring a new replica from. These include
+* all replicas in the newest `generation` of the given `epoch`, in order
+* of earliest available backup:
+* - An active InitialSync replica, which will be the only replica in
+*   its generation by definition. Orphaned/inactive initial syncs are skipped.
+* - Replicas in the Replicate stage, active first.
+* - Replicas in the Restore stage, potentially available for resumption
+*   as a last resort.
+*/
+async function getRestoreCandidates(sql, shard, epoch) {
+	const schema = sql(upstreamSchema(shard));
+	return parse(await sql`
+    SELECT
+      replicas."id",
+      replicas."rank",
+      replicas."slot",
+      replicas."epoch",
+      replicas."generation",
+      replicas."stage",
+      replicas."backupPath",
+      replicas."backupV5",
+      replicas."pgChangeLog",
+      slots."active",
+      slots."confirmed_flush_lsn" as "confirmedFlushLsn"
+    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name
+
+      -- coalesce on the newest generation in the epoch
+      WHERE generation = (
+        SELECT MAX(r.generation)
+          FROM ${schema}.replicas r
+          JOIN pg_replication_slots s ON r.slot = s.slot_name
+         WHERE r."epoch" = ${epoch} AND r."backupV5"
+           -- ignore orphaned InitialSyncs, which cannot be restored from
+           AND (s."active" OR r."stage" != ${0})
+           AND s.restart_lsn IS NOT NULL
+           AND s.wal_status IS DISTINCT FROM 'lost'
+      )
+           AND "epoch" = ${epoch} AND "backupV5"
+           AND (slots.active OR "stage" != ${0})
+           AND slots.restart_lsn IS NOT NULL
+           AND slots.wal_status IS DISTINCT FROM 'lost'
+
+      ORDER BY 
+        stage ASC,                 -- ordered by backup availalibility
+        active DESC,               -- prefer active slots (fork over resume)
+        confirmed_flush_lsn DESC;  -- prefer replicas further ahead
+  `, valita_exports.array(replicaStateSchema), "passthrough");
+}
 async function getReplicaState(sql, shard, id) {
 	const results = await sql`
     SELECT
       replicas."id",
       replicas."rank",
       replicas."slot",
-      replicas."version",
+      replicas."epoch",
       replicas."generation",
+      replicas."stage",
       replicas."backupPath",
       replicas."backupV5",
+      replicas."pgChangeLog",
       slots."active",
       slots."confirmed_flush_lsn" as "confirmedFlushLsn"
     FROM ${sql(upstreamSchema(shard))}.replicas JOIN pg_replication_slots slots ON slot = slot_name
@@ -395,6 +476,6 @@ function replicaIdentitiesForTablesWithoutPrimaryKeys(pubs) {
 	} };
 }
 //#endregion
-export { SHARD_CONFIG_TABLE, createReplica, dropShard, ensureGlobalTables, getActiveReplicas, getInternalShardConfig, getMutationsTableDefinition, getReplicaAtVersion, getReplicaState, initReplica, internalPublicationPrefix, legacyReplicationSlot, metadataPublicationName, replicaIdentitiesForTablesWithoutPrimaryKeys, replicationSlotExpression, replicationSlotPrefix, setupTablesAndReplication, setupTriggers, validatePublications };
+export { SHARD_CONFIG_TABLE, createReplica, dropShard, ensureGlobalTables, getActiveReplicas, getInternalShardConfig, getMutationsTableDefinition, getReplicaAtVersion, getReplicaState, getRestoreCandidates, initInitialSyncReplica, initRestoreReplica, internalPublicationPrefix, legacyReplicationSlot, metadataPublicationName, replicaIdentitiesForTablesWithoutPrimaryKeys, replicationSlotExpression, replicationSlotPrefix, setupTablesAndReplication, setupTriggers, validatePublications };
 
 //# sourceMappingURL=shard.js.map

package/out/zero-cache/src/services/change-source/pg/schema/shard.js.map

@@ -1 +1 @@
-{"version":3,"file":"shard.js","names":[],"sources":["../../../../../../../../zero-cache/src/services/change-source/pg/schema/shard.ts"],"sourcesContent":["import {PG_INSUFFICIENT_PRIVILEGE} from '@drdgvhbh/postgres-error-codes';\nimport type {LogContext} from '@rocicorp/logger';\nimport {literal} from 'pg-format';\nimport postgres from 'postgres';\nimport {assert} from '../../../../../../shared/src/asserts.ts';\nimport {\n  jsonObjectSchema,\n  stringify,\n  type JSONObject,\n} from '../../../../../../shared/src/bigint-json.ts';\nimport * as v from '../../../../../../shared/src/valita.ts';\nimport {Default} from '../../../../db/postgres-replica-identity-enum.ts';\nimport type {PostgresDB, PostgresTransaction} from '../../../../types/pg.ts';\nimport type {AppID, ShardConfig, ShardID} from '../../../../types/shards.ts';\nimport {appSchema, check, upstreamSchema} from '../../../../types/shards.ts';\nimport {id} from '../../../../types/sql.ts';\nimport {\n  createEventFunctionStatements,\n  createEventTriggerStatements,\n} from './ddl.ts';\nimport {\n  getPublicationInfo,\n  publishedSchema,\n  type PublicationInfo,\n  type PublishedSchema,\n} from './published.ts';\nimport {validate} from './validation.ts';\n\n/**\n * PostgreSQL unquoted identifiers must start with a letter or underscore\n * and contain only letters, digits, and underscores.\n */\nconst VALID_PUBLICATION_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;\n\n/**\n * Validates that a publication name is a valid PostgreSQL identifier.\n * This provides defense-in-depth against SQL injection when publication\n * names are used in replication commands.\n */\nexport function validatePublicationName(name: string): void {\n  if (!VALID_PUBLICATION_NAME.test(name)) {\n    throw new Error(\n      `Invalid publication name \"${name}\". Publication names must start with a letter or underscore ` +\n        `and contain only letters, digits, and underscores.`,\n    );\n  }\n  if (name.length > 63) {\n    throw new Error(\n      `Publication name \"${name}\" exceeds PostgreSQL's 63-character identifier limit.`,\n    );\n  }\n}\n\nexport function internalPublicationPrefix({appID}: AppID) {\n  return `_${appID}_`;\n}\n\nexport function legacyReplicationSlot({appID, shardNum}: ShardID) {\n  return `${appID}_${shardNum}`;\n}\n\nexport function replicationSlotPrefix(shard: ShardID) {\n  const {appID, shardNum} = check(shard);\n  return `${appID}_${shardNum}_`;\n}\n\n/**\n * An expression used to match replication slots in the shard\n * in a Postgres `LIKE` operator.\n */\nexport function replicationSlotExpression(shard: ShardID) {\n  // Underscores have a special meaning in LIKE values\n  // so they have to be escaped.\n  return `${replicationSlotPrefix(shard)}%`.replaceAll('_', '\\\\_');\n}\n\nfunction defaultPublicationName(appID: string, shardID: string | number) {\n  return `_${appID}_public_${shardID}`;\n}\n\nexport function metadataPublicationName(\n  appID: string,\n  shardID: string | number,\n) {\n  return `_${appID}_metadata_${shardID}`;\n}\n\n// The GLOBAL_SETUP must be idempotent as it can be run multiple times for different shards.\nfunction globalSetup(appID: AppID): string {\n  const app = id(appSchema(appID));\n\n  return /*sql*/ `\n  CREATE SCHEMA IF NOT EXISTS ${app};\n\n  CREATE TABLE IF NOT EXISTS ${app}.permissions (\n    \"permissions\" JSONB,\n    \"hash\"        TEXT,\n\n    -- Ensure that there is only a single row in the table.\n    -- Application code can be agnostic to this column, and\n    -- simply invoke UPDATE statements on the version columns.\n    \"lock\" BOOL PRIMARY KEY DEFAULT true CHECK (lock)\n  );\n\n  CREATE OR REPLACE FUNCTION ${app}.set_permissions_hash()\n  RETURNS TRIGGER AS $$\n  BEGIN\n      NEW.hash = md5(NEW.permissions::text);\n      RETURN NEW;\n  END;\n  $$ LANGUAGE plpgsql;\n\n  CREATE OR REPLACE TRIGGER on_set_permissions \n    BEFORE INSERT OR UPDATE ON ${app}.permissions\n    FOR EACH ROW\n    EXECUTE FUNCTION ${app}.set_permissions_hash();\n\n  INSERT INTO ${app}.permissions (permissions) VALUES (NULL) ON CONFLICT DO NOTHING;\n`;\n}\n\nexport async function ensureGlobalTables(db: PostgresDB, appID: AppID) {\n  await db.unsafe(globalSetup(appID));\n}\n\nexport function getClientsTableDefinition(schema: string) {\n  return /*sql*/ `\n  CREATE TABLE ${schema}.\"clients\" (\n    \"clientGroupID\"  TEXT NOT NULL,\n    \"clientID\"       TEXT NOT NULL,\n    \"lastMutationID\" BIGINT NOT NULL,\n    \"userID\"         TEXT,\n    PRIMARY KEY(\"clientGroupID\", \"clientID\")\n  );`;\n}\n\n/**\n * Tracks the results of mutations.\n * 1. It is an error for the same mutation ID to be used twice.\n * 2. The result is JSONB to allow for arbitrary results.\n *\n * The tables must be cleaned up as the clients\n * receive the mutation responses and as clients are removed.\n */\nexport function getMutationsTableDefinition(schema: string) {\n  return /*sql*/ `\n  CREATE TABLE ${schema}.\"mutations\" (\n    \"clientGroupID\"  TEXT NOT NULL,\n    \"clientID\"       TEXT NOT NULL,\n    \"mutationID\"     BIGINT NOT NULL,\n    \"result\"         JSON NOT NULL,\n    PRIMARY KEY(\"clientGroupID\", \"clientID\", \"mutationID\")\n  );`;\n}\n\nexport const SHARD_CONFIG_TABLE = 'shardConfig';\n\nexport function shardSetup(\n  shardConfig: ShardConfig,\n  metadataPublication: string,\n): string {\n  const app = id(appSchema(shardConfig));\n  const shard = id(upstreamSchema(shardConfig));\n\n  const pubs = shardConfig.publications.toSorted();\n  assert(\n    pubs.includes(metadataPublication),\n    () => `Publications must include ${metadataPublication}`,\n  );\n\n  return /*sql*/ `\n  CREATE SCHEMA IF NOT EXISTS ${shard};\n\n  ${getClientsTableDefinition(shard)}\n  ${getMutationsTableDefinition(shard)}\n\n  DROP PUBLICATION IF EXISTS ${id(metadataPublication)};\n  CREATE PUBLICATION ${id(metadataPublication)}\n    FOR TABLE ${app}.\"permissions\", TABLE ${shard}.\"clients\", ${shard}.\"mutations\";\n\n  CREATE TABLE ${shard}.\"${SHARD_CONFIG_TABLE}\" (\n    \"publications\"  TEXT[] NOT NULL,\n    \"ddlDetection\"  BOOL NOT NULL,\n\n    -- Ensure that there is only a single row in the table.\n    \"lock\" BOOL PRIMARY KEY DEFAULT true CHECK (lock)\n  );\n\n  INSERT INTO ${shard}.\"${SHARD_CONFIG_TABLE}\" (\n      \"publications\",\n      \"ddlDetection\" \n    ) VALUES (\n      ARRAY[${literal(pubs)}], \n      false  -- set in SAVEPOINT with triggerSetup() statements\n    );\n\n  CREATE TABLE ${shard}.replicas (\n    -- The DEFAULT exists purely for backwards compatibility support.\n    -- New code always specifies a value based on Date.now().\n    \"id\"                 TEXT PRIMARY KEY DEFAULT replace(gen_random_uuid()::text, '-', ''),\n    \"rank\"               BIGSERIAL,\n    \"slot\"               TEXT NOT NULL,\n    \"version\"            TEXT NOT NULL,\n    \"generation\"         TEXT,  -- to replace version, NULL-able in the interim\n    \"backupPath\"         TEXT,  -- subpath within the litestream backup URL\n    \"backupV5\"           BOOL DEFAULT false,\n    \"initialSchema\"      JSON,  -- set after initial sync\n    \"initialSyncContext\" JSON,\n    \"subscriberContext\"  JSON\n  );\n  `;\n}\n\nexport function dropShard(appID: string, shardID: string | number): string {\n  const schema = `${appID}_${shardID}`;\n  const metadataPublication = metadataPublicationName(appID, shardID);\n  const defaultPublication = defaultPublicationName(appID, shardID);\n\n  // DROP SCHEMA ... CASCADE does not drop dependent PUBLICATIONS,\n  // so PUBLICATIONs must be dropped explicitly.\n  return /*sql*/ `\n    DROP PUBLICATION IF EXISTS ${id(defaultPublication)};\n    DROP PUBLICATION IF EXISTS ${id(metadataPublication)};\n    DROP SCHEMA IF EXISTS ${id(schema)} CASCADE;\n  `;\n}\n\nconst internalShardConfigSchema = v.object({\n  publications: v.array(v.string()),\n  ddlDetection: v.boolean(),\n});\n\nexport type InternalShardConfig = v.Infer<typeof internalShardConfigSchema>;\n\nconst replicaInfoSchema = v.object({\n  id: v.string(),\n  rank: v.bigint(),\n  slot: v.string(),\n  version: v.string(),\n  generation: v.string().nullable(),\n  backupPath: v.string().nullable(),\n  backupV5: v.boolean(),\n});\n\nconst fullReplicaRowSchema = replicaInfoSchema.extend({\n  initialSchema: publishedSchema,\n  initialSyncContext: jsonObjectSchema.nullable(),\n  subscriberContext: jsonObjectSchema.nullable(),\n});\n\nconst replicaSchema = internalShardConfigSchema\n  .extend(fullReplicaRowSchema.shape)\n  .map(replica => {\n    const {version, generation, ...r} = replica;\n    return {...r, generation: generation ?? version};\n  });\n\nexport type Replica = v.Infer<typeof replicaSchema>;\n\nconst replicationSlotStateSchema = v.object({\n  active: v.boolean(),\n  confirmedFlushLsn: v.string().nullable(),\n});\n\nconst replicaStateSchema = replicaInfoSchema\n  .extend(replicationSlotStateSchema.shape)\n  .map(replica => {\n    const {version, generation, ...r} = replica;\n    return {...r, generation: generation ?? version};\n  });\n\nexport type ReplicaState = v.Infer<typeof replicaStateSchema>;\n\n// triggerSetup is run separately in a sub-transaction (i.e. SAVEPOINT) so\n// that a failure (e.g. due to lack of superuser permissions) can be handled\n// by continuing in a degraded mode (ddlDetection = false).\nfunction triggerSetup(shard: ShardConfig): string {\n  const schema = id(upstreamSchema(shard));\n  return (\n    createEventTriggerStatements(shard) +\n    /*sql*/ `UPDATE ${schema}.\"shardConfig\" SET \"ddlDetection\" = true;`\n  );\n}\n\nexport type BackupOptions = {\n  backupPath: string | null;\n  backupV5: boolean;\n};\n\n/**\n * Creates a new replica to mark it as the owner of a specified `slot`.\n * This should be done with an advisory lock for replica/slot management\n * to ensure that the slot does not get dropped by concurrent cleanup\n * logic.\n *\n * Once initial sync is complete, {@link initReplica} should be called to\n * make the replica usable for incremental sync.\n */\nexport async function createReplica(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n  slot: string,\n  replicaVersion: string,\n  {backupPath, backupV5}: BackupOptions,\n) {\n  const schema = upstreamSchema(shard);\n  const values: Partial<v.Infer<typeof fullReplicaRowSchema>> = {\n    id,\n    slot,\n    version: replicaVersion,\n    generation: replicaVersion,\n    backupPath,\n    backupV5,\n  };\n  await sql`INSERT INTO ${sql(schema)}.replicas ${sql(values)}`;\n}\n\n// Called in initial-sync to store the exact schema that was initially synced.\nexport async function initReplica(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n  {tables, indexes}: PublishedSchema,\n  initialSyncContext: JSONObject,\n) {\n  const schema = upstreamSchema(shard);\n  const synced: PublishedSchema = {tables, indexes};\n  const values = {initialSchema: synced, initialSyncContext};\n  await sql`UPDATE ${sql(schema)}.replicas SET ${sql(values)} WHERE id = ${id}`;\n}\n\n/**\n * Gets at the given version and optional ID. If no ID is specified, gets\n * the latest (i.e. highest rank) replica with that version.\n */\nexport async function getReplicaAtVersion(\n  lc: LogContext,\n  sql: PostgresDB,\n  shard: ShardID,\n  replicaVersion: string,\n  id: string | null = null,\n  context?: JSONObject,\n): Promise<Replica | null> {\n  const schema = sql(upstreamSchema(shard));\n  const result = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"version\",\n      replicas.\"generation\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      replicas.\"initialSchema\",\n      replicas.\"initialSyncContext\",\n      replicas.\"subscriberContext\",\n      \"shardConfig\".\"publications\",\n      \"shardConfig\".\"ddlDetection\"\n    FROM ${schema}.replicas JOIN ${schema}.\"shardConfig\" ON true\n      WHERE version = ${replicaVersion} AND \"initialSyncContext\" IS NOT NULL\n      AND id = COALESCE(${id}, id)\n      ORDER BY rank DESC LIMIT 1;\n  `;\n  if (result.length === 0) {\n    // log out all the replicas and the joined shardConfig\n    const allReplicas = await sql`\n      SELECT id, slot, version, \"initialSyncContext\", \"subscriberContext\" \n        FROM ${schema}.replicas`;\n    lc.info?.(\n      `Replica ${id}@${replicaVersion}` +\n        (context ? `(context: ${stringify(context)}) ` : '') +\n        `not found in: ${stringify(allReplicas)}`,\n    );\n    return null;\n  }\n  return v.parse(result[0], replicaSchema, 'passthrough');\n}\n\nexport async function getActiveReplicas(\n  lc: LogContext,\n  sql: PostgresDB,\n  shard: ShardID,\n): Promise<ReplicaState[]> {\n  const schema = sql(upstreamSchema(shard));\n  const results = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"version\",\n      replicas.\"generation\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      slots.\"active\",\n      slots.\"confirmed_flush_lsn\" as \"confirmedFlushLsn\"\n    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name\n      WHERE \"initialSyncContext\" IS NOT NULL\n      ORDER BY generation DESC, confirmed_flush_lsn DESC;\n  `;\n  const replicas = v.parse(results, v.array(replicaStateSchema), 'passthrough');\n  lc.info?.(`current replicas`, {replicas});\n  return replicas;\n}\n\nexport async function getReplicaState(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n): Promise<ReplicaState | null> {\n  const schema = sql(upstreamSchema(shard));\n  const results = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"version\",\n      replicas.\"generation\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      slots.\"active\",\n      slots.\"confirmed_flush_lsn\" as \"confirmedFlushLsn\"\n    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name\n      WHERE \"id\" = ${id};\n  `;\n  return results.length\n    ? v.parse(results[0], replicaStateSchema, 'passthrough')\n    : null;\n}\n\nexport async function getInternalShardConfig(\n  sql: PostgresDB,\n  shard: ShardID,\n): Promise<InternalShardConfig> {\n  const result = await sql`\n    SELECT \"publications\", \"ddlDetection\"\n      FROM ${sql(upstreamSchema(shard))}.\"shardConfig\";\n  `;\n  assert(\n    result.length === 1,\n    () => `Expected exactly one shardConfig row, got ${result.length}`,\n  );\n  return v.parse(result[0], internalShardConfigSchema, 'passthrough');\n}\n\n/**\n * Sets up and returns all publications (including internal ones) for\n * the given shard.\n */\nexport async function setupTablesAndReplication(\n  lc: LogContext,\n  sql: PostgresTransaction,\n  requested: ShardConfig,\n  includePartialIndexes = true,\n) {\n  const {publications} = requested;\n  // Validate requested publications.\n  for (const pub of publications) {\n    validatePublicationName(pub);\n    if (pub.startsWith('_')) {\n      throw new Error(\n        `Publication names starting with \"_\" are reserved for internal use.\\n` +\n          `Please use a different name for publication \"${pub}\".`,\n      );\n    }\n  }\n  const allPublications: string[] = [];\n\n  // Setup application publications.\n  if (publications.length) {\n    const results = await sql<{pubname: string}[]>`\n    SELECT pubname from pg_publication WHERE pubname IN ${sql(\n      publications,\n    )}`.values();\n\n    if (results.length !== publications.length) {\n      throw new Error(\n        `Unknown or invalid publications. Specified: [${publications}]. Found: [${results.flat()}]`,\n      );\n    }\n    allPublications.push(...publications);\n  } else {\n    const defaultPublication = defaultPublicationName(\n      requested.appID,\n      requested.shardNum,\n    );\n    await sql`\n      DROP PUBLICATION IF EXISTS ${sql(defaultPublication)}`;\n    await sql`\n      CREATE PUBLICATION ${sql(defaultPublication)} \n        FOR TABLES IN SCHEMA public\n        WITH (publish_via_partition_root = true)`;\n    allPublications.push(defaultPublication);\n  }\n\n  const metadataPublication = metadataPublicationName(\n    requested.appID,\n    requested.shardNum,\n  );\n  allPublications.push(metadataPublication);\n\n  const shard = {...requested, publications: allPublications};\n\n  // Setup the global tables and shard tables / publications.\n  await sql.unsafe(globalSetup(shard) + shardSetup(shard, metadataPublication));\n\n  const pubs = await getPublicationInfo(sql, allPublications);\n  await replicaIdentitiesForTablesWithoutPrimaryKeys(pubs)?.apply(lc, sql);\n\n  await setupTriggers(lc, sql, shard, includePartialIndexes);\n}\n\nexport async function setupTriggers(\n  lc: LogContext,\n  tx: PostgresTransaction,\n  shard: ShardConfig,\n  includePartialIndexes = true,\n) {\n  const schema = upstreamSchema(shard);\n  const [{ddlDetection}] = await tx<InternalShardConfig[]> /*sql*/ `\n    SELECT \"ddlDetection\" FROM ${tx(schema)}.\"shardConfig\"`;\n\n  // The functions invoked by event triggers are installed even if\n  // event triggers are not supported/allowed by the db provider.\n  // This allows users to manually invoke the update_schemas() function\n  // as a workaround.\n  await tx.unsafe(createEventFunctionStatements(shard, includePartialIndexes));\n  try {\n    await tx.savepoint(sub => sub.unsafe(triggerSetup(shard)));\n  } catch (e) {\n    if (ddlDetection) {\n      // If ddlDetection has already been enabled, subsequent failures to\n      // upgrade the trigger should be propagated rather than swallowed.\n      throw e;\n    }\n    if (\n      !(\n        e instanceof postgres.PostgresError &&\n        e.code === PG_INSUFFICIENT_PRIVILEGE\n      )\n    ) {\n      throw e;\n    }\n    // If triggerSetup() fails, replication continues in ddlDetection=false mode.\n    lc.warn?.(\n      `Unable to create event triggers for schema change detection:\\n\\n` +\n        `\"${e.hint ?? e.message}\"\\n\\n` +\n        `Proceeding in degraded mode: schema changes will halt replication,\\n` +\n        `requiring the replica to be reset (manually or with --auto-reset).`,\n    );\n  }\n}\n\nexport function validatePublications(\n  lc: LogContext,\n  published: PublicationInfo,\n) {\n  // Verify that all publications export the proper events.\n  published.publications.forEach(pub => {\n    if (\n      !pub.pubinsert ||\n      !pub.pubupdate ||\n      !pub.pubdelete ||\n      !pub.pubtruncate\n    ) {\n      // TODO: Make APIError?\n      throw new Error(\n        `PUBLICATION ${pub.pubname} must publish insert, update, delete, and truncate`,\n      );\n    }\n  });\n\n  published.tables.forEach(table => validate(lc, table));\n}\n\ntype ReplicaIdentities = {\n  apply(lc: LogContext, db: PostgresDB): Promise<void>;\n};\n\nexport function replicaIdentitiesForTablesWithoutPrimaryKeys(\n  pubs: PublishedSchema,\n): ReplicaIdentities | undefined {\n  const replicaIdentities: {\n    schema: string;\n    tableName: string;\n    indexName: string;\n  }[] = [];\n  for (const table of pubs.tables) {\n    if (!table.primaryKey?.length && table.replicaIdentity === Default) {\n      // Look for an index that can serve as the REPLICA IDENTITY USING INDEX. It must be:\n      // - UNIQUE\n      // - NOT NULL columns\n      // - not deferrable (i.e. isImmediate)\n      // - not partial\n      //\n      // https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY\n      const {schema, name: tableName} = table;\n      for (const {columns, name: indexName} of pubs.indexes.filter(\n        idx =>\n          idx.schema === schema &&\n          idx.tableName === tableName &&\n          idx.unique &&\n          idx.isImmediate &&\n          idx.predicate === undefined,\n      )) {\n        if (Object.keys(columns).some(col => !table.columns[col].notNull)) {\n          continue; // Only indexes with all NOT NULL columns are suitable.\n        }\n        replicaIdentities.push({schema, tableName, indexName});\n        break;\n      }\n    }\n  }\n\n  if (replicaIdentities.length === 0) {\n    return undefined;\n  }\n  return {\n    apply: async (lc: LogContext, sql: PostgresDB) => {\n      for (const {schema, tableName, indexName} of replicaIdentities) {\n        lc.info?.(\n          `setting \"${indexName}\" as the REPLICA IDENTITY for \"${tableName}\"`,\n        );\n        await sql`\n        ALTER TABLE ${sql(schema)}.${sql(tableName)} \n          REPLICA IDENTITY USING INDEX ${sql(indexName)}`;\n      }\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"shard.js","names":[],"sources":["../../../../../../../../zero-cache/src/services/change-source/pg/schema/shard.ts"],"sourcesContent":["import {PG_INSUFFICIENT_PRIVILEGE} from '@drdgvhbh/postgres-error-codes';\nimport type {LogContext} from '@rocicorp/logger';\nimport {literal} from 'pg-format';\nimport postgres from 'postgres';\nimport {assert} from '../../../../../../shared/src/asserts.ts';\nimport {\n  jsonObjectSchema,\n  stringify,\n  type JSONObject,\n} from '../../../../../../shared/src/bigint-json.ts';\nimport * as v from '../../../../../../shared/src/valita.ts';\nimport {Default} from '../../../../db/postgres-replica-identity-enum.ts';\nimport type {PostgresDB, PostgresTransaction} from '../../../../types/pg.ts';\nimport type {AppID, ShardConfig, ShardID} from '../../../../types/shards.ts';\nimport {appSchema, check, upstreamSchema} from '../../../../types/shards.ts';\nimport {id} from '../../../../types/sql.ts';\nimport {\n  createEventFunctionStatements,\n  createEventTriggerStatements,\n} from './ddl.ts';\nimport {\n  getPublicationInfo,\n  publishedSchema,\n  type PublicationInfo,\n  type PublishedSchema,\n} from './published.ts';\nimport {\n  InitialSync,\n  replicaStageSchema,\n  type ReplicaStage,\n} from './replica-stage-enum.ts';\nimport {validate} from './validation.ts';\n\n/**\n * PostgreSQL unquoted identifiers must start with a letter or underscore\n * and contain only letters, digits, and underscores.\n */\nconst VALID_PUBLICATION_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;\n\n/**\n * Validates that a publication name is a valid PostgreSQL identifier.\n * This provides defense-in-depth against SQL injection when publication\n * names are used in replication commands.\n */\nexport function validatePublicationName(name: string): void {\n  if (!VALID_PUBLICATION_NAME.test(name)) {\n    throw new Error(\n      `Invalid publication name \"${name}\". Publication names must start with a letter or underscore ` +\n        `and contain only letters, digits, and underscores.`,\n    );\n  }\n  if (name.length > 63) {\n    throw new Error(\n      `Publication name \"${name}\" exceeds PostgreSQL's 63-character identifier limit.`,\n    );\n  }\n}\n\nexport function internalPublicationPrefix({appID}: AppID) {\n  return `_${appID}_`;\n}\n\nexport function legacyReplicationSlot({appID, shardNum}: ShardID) {\n  return `${appID}_${shardNum}`;\n}\n\nexport function replicationSlotPrefix(shard: ShardID) {\n  const {appID, shardNum} = check(shard);\n  return `${appID}_${shardNum}_`;\n}\n\n/**\n * An expression used to match replication slots in the shard\n * in a Postgres `LIKE` operator.\n */\nexport function replicationSlotExpression(shard: ShardID) {\n  // Underscores have a special meaning in LIKE values\n  // so they have to be escaped.\n  return `${replicationSlotPrefix(shard)}%`.replaceAll('_', '\\\\_');\n}\n\nfunction defaultPublicationName(appID: string, shardID: string | number) {\n  return `_${appID}_public_${shardID}`;\n}\n\nexport function metadataPublicationName(\n  appID: string,\n  shardID: string | number,\n) {\n  return `_${appID}_metadata_${shardID}`;\n}\n\n// The GLOBAL_SETUP must be idempotent as it can be run multiple times for different shards.\nfunction globalSetup(appID: AppID): string {\n  const app = id(appSchema(appID));\n\n  return /*sql*/ `\n  CREATE SCHEMA IF NOT EXISTS ${app};\n\n  CREATE TABLE IF NOT EXISTS ${app}.permissions (\n    \"permissions\" JSONB,\n    \"hash\"        TEXT,\n\n    -- Ensure that there is only a single row in the table.\n    -- Application code can be agnostic to this column, and\n    -- simply invoke UPDATE statements on the version columns.\n    \"lock\" BOOL PRIMARY KEY DEFAULT true CHECK (lock)\n  );\n\n  CREATE OR REPLACE FUNCTION ${app}.set_permissions_hash()\n  RETURNS TRIGGER AS $$\n  BEGIN\n      NEW.hash = md5(NEW.permissions::text);\n      RETURN NEW;\n  END;\n  $$ LANGUAGE plpgsql;\n\n  CREATE OR REPLACE TRIGGER on_set_permissions \n    BEFORE INSERT OR UPDATE ON ${app}.permissions\n    FOR EACH ROW\n    EXECUTE FUNCTION ${app}.set_permissions_hash();\n\n  INSERT INTO ${app}.permissions (permissions) VALUES (NULL) ON CONFLICT DO NOTHING;\n`;\n}\n\nexport async function ensureGlobalTables(db: PostgresDB, appID: AppID) {\n  await db.unsafe(globalSetup(appID));\n}\n\nexport function getClientsTableDefinition(schema: string) {\n  return /*sql*/ `\n  CREATE TABLE ${schema}.\"clients\" (\n    \"clientGroupID\"  TEXT NOT NULL,\n    \"clientID\"       TEXT NOT NULL,\n    \"lastMutationID\" BIGINT NOT NULL,\n    \"userID\"         TEXT,\n    PRIMARY KEY(\"clientGroupID\", \"clientID\")\n  );`;\n}\n\n/**\n * Tracks the results of mutations.\n * 1. It is an error for the same mutation ID to be used twice.\n * 2. The result is JSONB to allow for arbitrary results.\n *\n * The tables must be cleaned up as the clients\n * receive the mutation responses and as clients are removed.\n */\nexport function getMutationsTableDefinition(schema: string) {\n  return /*sql*/ `\n  CREATE TABLE ${schema}.\"mutations\" (\n    \"clientGroupID\"  TEXT NOT NULL,\n    \"clientID\"       TEXT NOT NULL,\n    \"mutationID\"     BIGINT NOT NULL,\n    \"result\"         JSON NOT NULL,\n    PRIMARY KEY(\"clientGroupID\", \"clientID\", \"mutationID\")\n  );`;\n}\n\nexport const SHARD_CONFIG_TABLE = 'shardConfig';\n\nexport function shardSetup(\n  shardConfig: ShardConfig,\n  metadataPublication: string,\n): string {\n  const app = id(appSchema(shardConfig));\n  const shard = id(upstreamSchema(shardConfig));\n\n  const pubs = shardConfig.publications.toSorted();\n  assert(\n    pubs.includes(metadataPublication),\n    () => `Publications must include ${metadataPublication}`,\n  );\n\n  return /*sql*/ `\n  CREATE SCHEMA IF NOT EXISTS ${shard};\n\n  ${getClientsTableDefinition(shard)}\n  ${getMutationsTableDefinition(shard)}\n\n  CREATE TABLE ${shard}.\"${SHARD_CONFIG_TABLE}\" (\n    \"publications\"  TEXT[] NOT NULL,\n    \"ddlDetection\"  BOOL NOT NULL,\n\n    -- Ensure that there is only a single row in the table.\n    \"lock\" BOOL PRIMARY KEY DEFAULT true CHECK (lock)\n  );\n\n  INSERT INTO ${shard}.\"${SHARD_CONFIG_TABLE}\" (\n      \"publications\",\n      \"ddlDetection\" \n    ) VALUES (\n      ARRAY[${literal(pubs)}], \n      false  -- set in SAVEPOINT with triggerSetup() statements\n    );\n\n  CREATE TABLE ${shard}.replicas (\n    -- The DEFAULT exists purely for backwards compatibility support.\n    -- New code always specifies a value based on Date.now().\n    \"id\"                 TEXT PRIMARY KEY DEFAULT replace(gen_random_uuid()::text, '-', ''),\n    \"rank\"               BIGSERIAL,\n    \"slot\"               TEXT NOT NULL,\n    \"version\"            TEXT,  -- replaced by generation, slated for deletion\n    \"epoch\"              INT4 DEFAULT 0,\n    \"generation\"         TEXT NOT NULL,\n    \"stage\"              INT4 DEFAULT ${InitialSync},\n    \"backupPath\"         TEXT,  -- subpath within the litestream backup URL\n    \"backupV5\"           BOOL DEFAULT false,\n    -- Whether the slot is acked only after storing in the PG change log.\n    \"pgChangeLog\"        BOOL DEFAULT false,\n    \"initialSchema\"      JSON,  -- set after initial sync\n    \"initialSyncContext\" JSON,\n    \"subscriberContext\"  JSON\n  );\n\n  DROP PUBLICATION IF EXISTS ${id(metadataPublication)};\n  CREATE PUBLICATION ${id(metadataPublication)}\n    FOR TABLE ${app}.\"permissions\", \n        TABLE ${shard}.\"clients\", \n              ${shard}.\"mutations\", \n              ${shard}.\"replicas\" (id);  -- advance the LSN/version with new replicas\n  `;\n}\n\nexport function dropShard(appID: string, shardID: string | number): string {\n  const schema = `${appID}_${shardID}`;\n  const metadataPublication = metadataPublicationName(appID, shardID);\n  const defaultPublication = defaultPublicationName(appID, shardID);\n\n  // DROP SCHEMA ... CASCADE does not drop dependent PUBLICATIONS,\n  // so PUBLICATIONs must be dropped explicitly.\n  return /*sql*/ `\n    DROP PUBLICATION IF EXISTS ${id(defaultPublication)};\n    DROP PUBLICATION IF EXISTS ${id(metadataPublication)};\n    DROP SCHEMA IF EXISTS ${id(schema)} CASCADE;\n  `;\n}\n\nconst internalShardConfigSchema = v.object({\n  publications: v.array(v.string()),\n  ddlDetection: v.boolean(),\n});\n\nexport type InternalShardConfig = v.Infer<typeof internalShardConfigSchema>;\n\nconst replicaInfoSchema = v.object({\n  id: v.string(),\n  rank: v.bigint(),\n  slot: v.string(),\n  epoch: v.number(),\n  generation: v.string(),\n  stage: replicaStageSchema,\n  backupPath: v.string().nullable(),\n  backupV5: v.boolean(),\n  /**\n   * Whether the replication-manager that took over the replica's slot acks it\n   * only after storing transactions in the PG change log (i.e. RMv1.5). The\n   * slot's position past the change log's head then reflects acked\n   * keepalives, rather than transactions missing from the change log.\n   * False if unknown.\n   */\n  pgChangeLog: v.boolean(),\n});\n\nconst fullReplicaRowSchema = replicaInfoSchema.extend({\n  initialSchema: publishedSchema,\n  initialSyncContext: jsonObjectSchema.nullable(),\n  subscriberContext: jsonObjectSchema.nullable(),\n});\n\nconst replicaSchema = internalShardConfigSchema.extend(\n  fullReplicaRowSchema.shape,\n);\n\nexport type Replica = v.Infer<typeof replicaSchema>;\n\nconst replicationSlotStateSchema = v.object({\n  active: v.boolean(),\n  confirmedFlushLsn: v.string(),\n});\n\nconst replicaStateSchema = replicaInfoSchema.extend(\n  replicationSlotStateSchema.shape,\n);\n\nexport type ReplicaState = v.Infer<typeof replicaStateSchema>;\n\n// triggerSetup is run separately in a sub-transaction (i.e. SAVEPOINT) so\n// that a failure (e.g. due to lack of superuser permissions) can be handled\n// by continuing in a degraded mode (ddlDetection = false).\nfunction triggerSetup(shard: ShardConfig): string {\n  const schema = id(upstreamSchema(shard));\n  return (\n    createEventTriggerStatements(shard) +\n    /*sql*/ `UPDATE ${schema}.\"shardConfig\" SET \"ddlDetection\" = true;`\n  );\n}\n\nexport type BackupOptions = {\n  backupPath: string | null;\n  backupV5: boolean;\n  /** See `pgChangeLog` in {@link ReplicaState}. */\n  pgChangeLog: boolean;\n};\n\n/**\n * Creates a new replica to mark it as the owner of a specified `slot`.\n * This should be done with an advisory lock for replica/slot management\n * to ensure that the slot does not get dropped by concurrent cleanup\n * logic.\n *\n * Once initial sync is complete, {@link initInitialSyncReplica} should be called to\n * make the replica usable for incremental sync.\n */\nexport async function createReplica(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n  slot: string,\n  epoch: number,\n  replicaVersion: string,\n  {backupPath, backupV5, pgChangeLog}: BackupOptions,\n  stage: ReplicaStage,\n) {\n  const schema = upstreamSchema(shard);\n  const values: Partial<v.Infer<typeof fullReplicaRowSchema>> & {\n    version: string;\n  } = {\n    id,\n    slot,\n    epoch,\n    generation: replicaVersion,\n    // No longer read, but zero-cache 1.10 fails to start on a NULL \"version\",\n    // so it is still written for rollbacks to 1.10.\n    version: replicaVersion,\n    backupPath,\n    backupV5,\n    pgChangeLog,\n    stage,\n  };\n  await sql`INSERT INTO ${sql(schema)}.replicas ${sql(values)}`;\n}\n\n// Called in initial-sync to store the exact schema that was initially synced.\nexport async function initInitialSyncReplica(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n  {tables, indexes}: PublishedSchema,\n  initialSyncContext: JSONObject,\n) {\n  const schema = upstreamSchema(shard);\n  const synced: PublishedSchema = {tables, indexes};\n  const values = {initialSchema: synced, initialSyncContext};\n  await sql`UPDATE ${sql(schema)}.replicas SET ${sql(values)} WHERE id = ${id}`;\n}\n\n// Called to initialize a Restore replica (`destID`) with the generation\n// and initial sync context of the `sourceID` replica.\nexport async function initRestoreReplica(\n  sql: PostgresDB,\n  shard: ShardID,\n  {sourceID, destID}: {sourceID: string; destID: string},\n): Promise<ReplicaState | null> {\n  const schema = upstreamSchema(shard);\n  await sql`\n    UPDATE ${sql(schema)}.replicas dest \n      SET \"generation\"         = source.\"generation\",\n          \"version\"            = source.\"generation\",\n          \"initialSchema\"      = source.\"initialSchema\",\n          \"initialSyncContext\" = source.\"initialSyncContext\"\n      FROM ${sql(schema)}.replicas source\n      WHERE source.id = ${sourceID} AND dest.id = ${destID};\n  `;\n  return getReplicaState(sql, shard, destID);\n}\n\n/**\n * Gets at the given version and optional ID. If no ID is specified, gets\n * the latest (i.e. highest rank) replica with that version.\n */\nexport async function getReplicaAtVersion(\n  lc: LogContext,\n  sql: PostgresDB,\n  shard: ShardID,\n  replicaVersion: string,\n  id: string | null = null,\n  context?: JSONObject,\n): Promise<Replica | null> {\n  const schema = sql(upstreamSchema(shard));\n  const result = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"epoch\",\n      replicas.\"generation\",\n      replicas.\"stage\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      replicas.\"pgChangeLog\",\n      replicas.\"initialSchema\",\n      replicas.\"initialSyncContext\",\n      replicas.\"subscriberContext\",\n      \"shardConfig\".\"publications\",\n      \"shardConfig\".\"ddlDetection\"\n    FROM ${schema}.replicas JOIN ${schema}.\"shardConfig\" ON true\n      WHERE generation = ${replicaVersion} AND \"initialSyncContext\" IS NOT NULL\n      AND id = COALESCE(${id}, id)\n      ORDER BY rank DESC LIMIT 1;\n  `;\n  if (result.length === 0) {\n    // log out all the replicas and the joined shardConfig\n    const allReplicas = await sql`\n      SELECT id, slot, generation, \"initialSyncContext\", \"subscriberContext\" \n        FROM ${schema}.replicas`;\n    lc.info?.(\n      `Replica ${id}@${replicaVersion}` +\n        (context ? `(context: ${stringify(context)}) ` : '') +\n        `not found in: ${stringify(allReplicas)}`,\n    );\n    return null;\n  }\n  return v.parse(result[0], replicaSchema, 'passthrough');\n}\n\nexport async function getActiveReplicas(\n  lc: LogContext,\n  sql: PostgresDB,\n  shard: ShardID,\n): Promise<ReplicaState[]> {\n  const schema = sql(upstreamSchema(shard));\n  const results = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"epoch\",\n      replicas.\"generation\",\n      replicas.\"stage\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      replicas.\"pgChangeLog\",\n      slots.\"active\",\n      slots.\"confirmed_flush_lsn\" as \"confirmedFlushLsn\"\n    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name\n      WHERE \"initialSyncContext\" IS NOT NULL\n        -- Exclude replicas whose slot has been invalidated (e.g. for exceeding\n        -- max_slot_wal_keep_size). Such a replica can never be resumed, and\n        -- restoring it just results in an AutoResetSignal on every attempt.\n        AND slots.restart_lsn IS NOT NULL\n        AND slots.wal_status IS DISTINCT FROM 'lost'\n      ORDER BY generation DESC, confirmed_flush_lsn DESC;\n  `;\n  const replicas = v.parse(results, v.array(replicaStateSchema), 'passthrough');\n  lc.info?.(`current replicas`, {replicas});\n  return replicas;\n}\n\n/**\n * Returns candidates for restoring a new replica from. These include\n * all replicas in the newest `generation` of the given `epoch`, in order\n * of earliest available backup:\n * - An active InitialSync replica, which will be the only replica in\n *   its generation by definition. Orphaned/inactive initial syncs are skipped.\n * - Replicas in the Replicate stage, active first.\n * - Replicas in the Restore stage, potentially available for resumption\n *   as a last resort.\n */\nexport async function getRestoreCandidates(\n  sql: PostgresDB,\n  shard: ShardID,\n  epoch: number,\n): Promise<ReplicaState[]> {\n  const schema = sql(upstreamSchema(shard));\n  const results = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"epoch\",\n      replicas.\"generation\",\n      replicas.\"stage\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      replicas.\"pgChangeLog\",\n      slots.\"active\",\n      slots.\"confirmed_flush_lsn\" as \"confirmedFlushLsn\"\n    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name\n\n      -- coalesce on the newest generation in the epoch\n      WHERE generation = (\n        SELECT MAX(r.generation)\n          FROM ${schema}.replicas r\n          JOIN pg_replication_slots s ON r.slot = s.slot_name\n         WHERE r.\"epoch\" = ${epoch} AND r.\"backupV5\"\n           -- ignore orphaned InitialSyncs, which cannot be restored from\n           AND (s.\"active\" OR r.\"stage\" != ${InitialSync})\n           AND s.restart_lsn IS NOT NULL\n           AND s.wal_status IS DISTINCT FROM 'lost'\n      )\n           AND \"epoch\" = ${epoch} AND \"backupV5\"\n           AND (slots.active OR \"stage\" != ${InitialSync})\n           AND slots.restart_lsn IS NOT NULL\n           AND slots.wal_status IS DISTINCT FROM 'lost'\n\n      ORDER BY \n        stage ASC,                 -- ordered by backup availalibility\n        active DESC,               -- prefer active slots (fork over resume)\n        confirmed_flush_lsn DESC;  -- prefer replicas further ahead\n  `;\n  return v.parse(results, v.array(replicaStateSchema), 'passthrough');\n}\n\nexport async function getReplicaState(\n  sql: PostgresDB,\n  shard: ShardID,\n  id: string,\n): Promise<ReplicaState | null> {\n  const schema = sql(upstreamSchema(shard));\n  const results = await sql`\n    SELECT\n      replicas.\"id\",\n      replicas.\"rank\",\n      replicas.\"slot\",\n      replicas.\"epoch\",\n      replicas.\"generation\",\n      replicas.\"stage\",\n      replicas.\"backupPath\",\n      replicas.\"backupV5\",\n      replicas.\"pgChangeLog\",\n      slots.\"active\",\n      slots.\"confirmed_flush_lsn\" as \"confirmedFlushLsn\"\n    FROM ${schema}.replicas JOIN pg_replication_slots slots ON slot = slot_name\n      WHERE \"id\" = ${id};\n  `;\n  return results.length\n    ? v.parse(results[0], replicaStateSchema, 'passthrough')\n    : null;\n}\n\nexport async function getInternalShardConfig(\n  sql: PostgresDB,\n  shard: ShardID,\n): Promise<InternalShardConfig> {\n  const result = await sql`\n    SELECT \"publications\", \"ddlDetection\"\n      FROM ${sql(upstreamSchema(shard))}.\"shardConfig\";\n  `;\n  assert(\n    result.length === 1,\n    () => `Expected exactly one shardConfig row, got ${result.length}`,\n  );\n  return v.parse(result[0], internalShardConfigSchema, 'passthrough');\n}\n\n/**\n * Sets up and returns all publications (including internal ones) for\n * the given shard.\n */\nexport async function setupTablesAndReplication(\n  lc: LogContext,\n  sql: PostgresTransaction,\n  requested: ShardConfig,\n  includePartialIndexes = true,\n) {\n  const {publications} = requested;\n  // Validate requested publications.\n  for (const pub of publications) {\n    validatePublicationName(pub);\n    if (pub.startsWith('_')) {\n      throw new Error(\n        `Publication names starting with \"_\" are reserved for internal use.\\n` +\n          `Please use a different name for publication \"${pub}\".`,\n      );\n    }\n  }\n  const allPublications: string[] = [];\n\n  // Setup application publications.\n  if (publications.length) {\n    const results = await sql<{pubname: string}[]>`\n    SELECT pubname from pg_publication WHERE pubname IN ${sql(\n      publications,\n    )}`.values();\n\n    if (results.length !== publications.length) {\n      throw new Error(\n        `Unknown or invalid publications. Specified: [${publications}]. Found: [${results.flat()}]`,\n      );\n    }\n    allPublications.push(...publications);\n  } else {\n    const defaultPublication = defaultPublicationName(\n      requested.appID,\n      requested.shardNum,\n    );\n    await sql`\n      DROP PUBLICATION IF EXISTS ${sql(defaultPublication)}`;\n    await sql`\n      CREATE PUBLICATION ${sql(defaultPublication)} \n        FOR TABLES IN SCHEMA public\n        WITH (publish_via_partition_root = true)`;\n    allPublications.push(defaultPublication);\n  }\n\n  const metadataPublication = metadataPublicationName(\n    requested.appID,\n    requested.shardNum,\n  );\n  allPublications.push(metadataPublication);\n\n  const shard = {...requested, publications: allPublications};\n\n  // Setup the global tables and shard tables / publications.\n  await sql.unsafe(globalSetup(shard) + shardSetup(shard, metadataPublication));\n\n  const pubs = await getPublicationInfo(sql, allPublications);\n  await replicaIdentitiesForTablesWithoutPrimaryKeys(pubs)?.apply(lc, sql);\n\n  await setupTriggers(lc, sql, shard, includePartialIndexes);\n}\n\nexport async function setupTriggers(\n  lc: LogContext,\n  tx: PostgresTransaction,\n  shard: ShardConfig,\n  includePartialIndexes = true,\n) {\n  const schema = upstreamSchema(shard);\n  const [{ddlDetection}] = await tx<InternalShardConfig[]> /*sql*/ `\n    SELECT \"ddlDetection\" FROM ${tx(schema)}.\"shardConfig\"`;\n\n  // The functions invoked by event triggers are installed even if\n  // event triggers are not supported/allowed by the db provider.\n  // This allows users to manually invoke the update_schemas() function\n  // as a workaround.\n  await tx.unsafe(createEventFunctionStatements(shard, includePartialIndexes));\n  try {\n    await tx.savepoint(sub => sub.unsafe(triggerSetup(shard)));\n  } catch (e) {\n    if (ddlDetection) {\n      // If ddlDetection has already been enabled, subsequent failures to\n      // upgrade the trigger should be propagated rather than swallowed.\n      throw e;\n    }\n    if (\n      !(\n        e instanceof postgres.PostgresError &&\n        e.code === PG_INSUFFICIENT_PRIVILEGE\n      )\n    ) {\n      throw e;\n    }\n    // If triggerSetup() fails, replication continues in ddlDetection=false mode.\n    lc.warn?.(\n      `Unable to create event triggers for schema change detection:\\n\\n` +\n        `\"${e.hint ?? e.message}\"\\n\\n` +\n        `Proceeding in degraded mode: schema changes will halt replication,\\n` +\n        `requiring the replica to be reset (manually or with --auto-reset).`,\n    );\n  }\n}\n\nexport function validatePublications(\n  lc: LogContext,\n  published: PublicationInfo,\n) {\n  // Verify that all publications export the proper events.\n  published.publications.forEach(pub => {\n    if (\n      !pub.pubinsert ||\n      !pub.pubupdate ||\n      !pub.pubdelete ||\n      !pub.pubtruncate\n    ) {\n      // TODO: Make APIError?\n      throw new Error(\n        `PUBLICATION ${pub.pubname} must publish insert, update, delete, and truncate`,\n      );\n    }\n  });\n\n  published.tables.forEach(table => validate(lc, table));\n}\n\ntype ReplicaIdentities = {\n  apply(lc: LogContext, db: PostgresDB): Promise<void>;\n};\n\nexport function replicaIdentitiesForTablesWithoutPrimaryKeys(\n  pubs: PublishedSchema,\n): ReplicaIdentities | undefined {\n  const replicaIdentities: {\n    schema: string;\n    tableName: string;\n    indexName: string;\n  }[] = [];\n  for (const table of pubs.tables) {\n    if (!table.primaryKey?.length && table.replicaIdentity === Default) {\n      // Look for an index that can serve as the REPLICA IDENTITY USING INDEX. It must be:\n      // - UNIQUE\n      // - NOT NULL columns\n      // - not deferrable (i.e. isImmediate)\n      // - not partial\n      //\n      // https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY\n      const {schema, name: tableName} = table;\n      for (const {columns, name: indexName} of pubs.indexes.filter(\n        idx =>\n          idx.schema === schema &&\n          idx.tableName === tableName &&\n          idx.unique &&\n          idx.isImmediate &&\n          idx.predicate === undefined,\n      )) {\n        if (Object.keys(columns).some(col => !table.columns[col].notNull)) {\n          continue; // Only indexes with all NOT NULL columns are suitable.\n        }\n        replicaIdentities.push({schema, tableName, indexName});\n        break;\n      }\n    }\n  }\n\n  if (replicaIdentities.length === 0) {\n    return undefined;\n  }\n  return {\n    apply: async (lc: LogContext, sql: PostgresDB) => {\n      for (const {schema, tableName, indexName} of replicaIdentities) {\n        lc.info?.(\n          `setting \"${indexName}\" as the REPLICA IDENTITY for \"${tableName}\"`,\n        );\n        await sql`\n        ALTER TABLE ${sql(schema)}.${sql(tableName)} \n          REPLICA IDENTITY USING INDEX ${sql(indexName)}`;\n      }\n    },\n  };\n}\n"],"mappings":"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"}

package/out/zero-cache/src/services/change-source/protocol/backfill-progress.d.ts

@@ -0,0 +1,68 @@
+import type { BackfillProgressMark, BackfillRequest } from './current.ts';
+/**
+ * The result of applying a backfill message to a column's tracked progress.
+ * If `accept` is true, `progress` is the column's new progress.
+ */
+export type AcceptResult = {
+    accept: true;
+    progress: BackfillProgressMark | undefined;
+} | {
+    accept: false;
+};
+/**
+ * Applies the continuity policy of `backfill` (and `backfill-completed`)
+ * messages to a column's `own` tracked progress, where `undefined` means that
+ * the column has not received any backfill data (i.e. it needs a backfill
+ * from scratch).
+ *
+ * * Messages without `progressMarks` are from pre-v8 replication-managers
+ *   and are accepted unconditionally (i.e. the legacy behavior), with no
+ *   change to the tracked progress.
+ * * A message without a `previous` mark starts a backfill from scratch (or on
+ *   a new timeline), and is always accepted.
+ * * Otherwise, the message is only accepted if it is on the same timeline as
+ *   `own`, and continues from a position at or before `own` (i.e. it does not
+ *   create a gap).
+ *
+ * `current` is unset for `backfill-completed` messages, which do not advance
+ * the progress.
+ */
+export declare function acceptBackfill(own: BackfillProgressMark | undefined, marks: {
+    previous?: BackfillProgressMark | undefined;
+    current?: BackfillProgressMark;
+} | undefined): AcceptResult;
+/**
+ * Returns whether a stream whose progress (for a column) is at `stream`
+ * will deliver all of the data needed by a subscriber whose progress (for the
+ * same column) is at `subscriber`. A `stream` progress of `undefined` indicates
+ * a backfill that will start from scratch, which covers all subscribers.
+ */
+export declare function covers(stream: BackfillProgressMark | undefined, subscriber: BackfillProgressMark | undefined): boolean;
+/**
+ * Returns the position from which a backfill for the `req` must start
+ * in order to satisfy the progress of all of its columns, i.e. the earliest
+ * progress mark, or `undefined` (i.e. from scratch) if any column has no
+ * progress or if the columns are on different timelines.
+ */
+export declare function resumePoint(req: BackfillRequest): BackfillProgressMark | undefined;
+/**
+ * Returns a copy of the `req` with the progress of every column set to
+ * the request's {@link resumePoint}, i.e. the position from which the
+ * backfill of the request will actually start.
+ */
+export declare function withResumePoint(req: BackfillRequest): BackfillRequest;
+/**
+ * Merges two BackfillRequests for the same table into one that satisfies
+ * both. Both requests are expected to reflect the same (current) upstream
+ * schema. For columns in both requests, the earlier progress mark is chosen,
+ * or no progress mark (i.e. from scratch) if they are on different timelines.
+ * If a column's backfill IDs differ (which is unexpected), the ID of `req1`
+ * is chosen, and the column is backfilled from scratch.
+ */
+export declare function getTableSuperset(req1: BackfillRequest, req2: BackfillRequest): BackfillRequest;
+/**
+ * Merges the BackfillRequests of multiple parties (e.g. subscribers) into
+ * one request per table, using {@link getTableSuperset}.
+ */
+export declare function getSuperset(...requestSets: Iterable<BackfillRequest>[]): BackfillRequest[];
+//# sourceMappingURL=backfill-progress.d.ts.map