@rocicorp/zero 1.4.0 → 1.5.0-canary.1

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

@@ -45,6 +45,24 @@ export declare const ddlEventSchema: v.ObjectType<Omit<{
         tag: v.Type<string>;
     }, undefined>;
 }, undefined>;
+/**
+ * A {@link DdlStartEvent} message is emitted before every DDL event, containing
+ * the current `schema` and the command `tag`.
+ *
+ * In most cases, the `DdlStartEvent` itself will not be associated with a
+ * schema change, in which case `previousSchema` will be `null`. However, the
+ * message is still emitted, both for backwards compatibility and to provide
+ * the command `tag` context in case an immediately following `DdlStartEvent`
+ * tag is emitted with a schema change (which can happen when another event
+ * trigger results in a nested ddl statement).
+ *
+ * In such cases, the `previousSchema` and `schema` fields of the latter event
+ * are used to determine the necessary schema change operations (as they are
+ * with `ddlUpdate` and `schemaSnapshot` events), and the `tag` of the
+ * preceding start event indicates the command that precipitated the schema
+ * change (e.g. a CREATE vs ALTER) to determine whether a backfill is
+ * necessary.
+ */
 export declare const ddlStartEventSchema: v.ObjectType<Omit<Omit<{
     context: v.ObjectType<{
         query: v.Type<string>;
@@ -88,24 +106,51 @@ export declare const ddlStartEventSchema: v.ObjectType<Omit<Omit<{
     event: v.ObjectType<{
         tag: v.Type<string>;
     }, undefined>;
-}, "type" | "event"> & {
+}, "type" | "event" | "previousSchema"> & {
     type: v.Type<"ddlStart">;
+    previousSchema: v.Optional<{
+        indexes: {
+            isReplicaIdentity?: boolean | undefined;
+            isPrimaryKey?: boolean | undefined;
+            isImmediate?: boolean | undefined;
+            name: string;
+            columns: Record<string, "ASC" | "DESC">;
+            schema: string;
+            tableName: string;
+            unique: boolean;
+        }[];
+        tables: {
+            replicaIdentityColumns: string[];
+            primaryKey?: string[] | undefined;
+            schemaOID?: number | undefined;
+            replicaIdentity?: "n" | "d" | "f" | "i" | undefined;
+            name: string;
+            schema: string;
+            oid: number;
+            columns: Record<string, {
+                pgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | undefined;
+                elemPgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | null | undefined;
+                characterMaximumLength?: number | null | undefined;
+                notNull?: boolean | null | undefined;
+                dflt?: string | null | undefined;
+                pos: number;
+                dataType: string;
+                typeOID: number;
+            }>;
+            publications: Record<string, {
+                rowFilter: string | null;
+            }>;
+        }[];
+    } | null>;
     event: v.Type<{
         tag: string;
     }>;
 }, undefined>;
 export type DdlStartEvent = v.Infer<typeof ddlStartEventSchema>;
 /**
- * The {@link DdlUpdateEvent} contains an updated schema resulting from
- * a particular ddl event. The event type provides information
- * (i.e. constraints) on the difference from the schema of the preceding
- * {@link DdlStartEvent}.
- *
- * Note that in almost all cases (the exception being `CREATE` events),
- * it is possible that there is no relevant difference between the
- * ddl-start schema and the ddl-update schema, as many aspects of the
- * schema (e.g. column constraints) are not relevant to downstream
- * replication.
+ * A {@link DdlUpdateEvent} is emitted if there was a change in the schema.
+ * It always contains `previousSchema` and (current) `schema` fields, leaving
+ * it to the receiver to compute the necessary schema change operations.
  */
 export declare const ddlUpdateEventSchema: v.ObjectType<Omit<Omit<{
     context: v.ObjectType<{
@@ -150,51 +195,65 @@ export declare const ddlUpdateEventSchema: v.ObjectType<Omit<Omit<{
     event: v.ObjectType<{
         tag: v.Type<string>;
     }, undefined>;
-}, "type"> & {
+}, "type" | "previousSchema"> & {
     type: v.Type<"ddlUpdate">;
+    previousSchema: v.Optional<{
+        indexes: {
+            isReplicaIdentity?: boolean | undefined;
+            isPrimaryKey?: boolean | undefined;
+            isImmediate?: boolean | undefined;
+            name: string;
+            columns: Record<string, "ASC" | "DESC">;
+            schema: string;
+            tableName: string;
+            unique: boolean;
+        }[];
+        tables: {
+            replicaIdentityColumns: string[];
+            primaryKey?: string[] | undefined;
+            schemaOID?: number | undefined;
+            replicaIdentity?: "n" | "d" | "f" | "i" | undefined;
+            name: string;
+            schema: string;
+            oid: number;
+            columns: Record<string, {
+                pgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | undefined;
+                elemPgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | null | undefined;
+                characterMaximumLength?: number | null | undefined;
+                notNull?: boolean | null | undefined;
+                dflt?: string | null | undefined;
+                pos: number;
+                dataType: string;
+                typeOID: number;
+            }>;
+            publications: Record<string, {
+                rowFilter: string | null;
+            }>;
+        }[];
+    }>;
 }, undefined>;
 export type DdlUpdateEvent = v.Infer<typeof ddlUpdateEventSchema>;
 /**
  * The `schemaSnapshot` message is a snapshot of a schema taken in response to
  * a `COMMENT ON PUBLICATION` command, which is a hook recognized by zero
- * to manually emit schema snapshots to support detection of schema changes
- * from `ALTER PUBLICATION` commands on supabase, which does not fire event
- * triggers for them (https://github.com/supabase/supautils/issues/123).
+ * to manually emit `previousSchema` and `schema` snapshots when a difference
+ * is detected. This is a workaround provided to support detection of schema
+ * changes from `ALTER PUBLICATION` commands on supabase, which does not fire
+ * event triggers for them (https://github.com/supabase/supautils/issues/123).
  *
- * The hook is exercised by bookmarking the publication change with
- * `COMMENT ON PUBLICATION` statements within e.g.
+ * The hook is exercised by trailing the publication change with a
+ * `COMMENT ON PUBLICATION` statement, e.g.
  *
  * ```sql
  * BEGIN;
- * COMMENT ON PUBLICATION my_publication IS 'whatever';
  * ALTER PUBLICATION my_publication ...;
  * COMMENT ON PUBLICATION my_publication IS 'whatever';
  * COMMIT;
  * ```
  *
- * The `change-source` will perform the diff between a `schemaSnapshot`
- * events and its preceding `schemaSnapshot` (or `ddlUpdate`) within the
- * transaction.
- *
- * In the case where event trigger support is missing, this results in
- * diffing the `schemaSnapshot`s before and after the `ALTER PUBLICATION`
- * statement, thus effecting the same logic that would have been exercised
- * between the `ddlStart` and `ddlEvent` events fired by a database with
- * fully functional event triggers.
- *
- * Note that if the same transaction is run on a database that *does*
- * support event triggers on `ALTER PUBLICATION` statements, the sequence
- * of emitted messages will be:
- *
- * * `schemaSnapshot`
- * * `ddlStart`
- * * `ddlUpdate`
- * * `schemaSnapshot`
- *
- * Since `schemaSnapshot` messages are diffed with the preceding
- * `schemaSnapshot` or `ddlUpdate` event (if any), there will be no schema
- * difference between the `ddlUpdate` and the second `schemaSnapshot`, and
- * thus the extra `COMMENT` statements will effectively be no-ops.
+ * Note that it is fine to invoke `COMMENT ON PUBLICATION` statements
+ * on a database that *does* support event triggers on
+ * `ALTER PUBLICATION` statements, as it will simply be a no-op.
  */
 export declare const schemaSnapshotEventSchema: v.ObjectType<Omit<Omit<{
     context: v.ObjectType<{
@@ -239,8 +298,42 @@ export declare const schemaSnapshotEventSchema: v.ObjectType<Omit<Omit<{
     event: v.ObjectType<{
         tag: v.Type<string>;
     }, undefined>;
-}, "type"> & {
+}, "type" | "previousSchema"> & {
     type: v.Type<"schemaSnapshot">;
+    previousSchema: v.Optional<{
+        indexes: {
+            isReplicaIdentity?: boolean | undefined;
+            isPrimaryKey?: boolean | undefined;
+            isImmediate?: boolean | undefined;
+            name: string;
+            columns: Record<string, "ASC" | "DESC">;
+            schema: string;
+            tableName: string;
+            unique: boolean;
+        }[];
+        tables: {
+            replicaIdentityColumns: string[];
+            primaryKey?: string[] | undefined;
+            schemaOID?: number | undefined;
+            replicaIdentity?: "n" | "d" | "f" | "i" | undefined;
+            name: string;
+            schema: string;
+            oid: number;
+            columns: Record<string, {
+                pgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | undefined;
+                elemPgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | null | undefined;
+                characterMaximumLength?: number | null | undefined;
+                notNull?: boolean | null | undefined;
+                dflt?: string | null | undefined;
+                pos: number;
+                dataType: string;
+                typeOID: number;
+            }>;
+            publications: Record<string, {
+                rowFilter: string | null;
+            }>;
+        }[];
+    }>;
 }, undefined>;
 export type SchemaSnapshotEvent = v.Infer<typeof schemaSnapshotEventSchema>;
 export declare const replicationEventSchema: v.UnionType<[v.ObjectType<Omit<Omit<{
@@ -286,8 +379,42 @@ export declare const replicationEventSchema: v.UnionType<[v.ObjectType<Omit<Omit
     event: v.ObjectType<{
         tag: v.Type<string>;
     }, undefined>;
-}, "type" | "event"> & {
+}, "type" | "event" | "previousSchema"> & {
     type: v.Type<"ddlStart">;
+    previousSchema: v.Optional<{
+        indexes: {
+            isReplicaIdentity?: boolean | undefined;
+            isPrimaryKey?: boolean | undefined;
+            isImmediate?: boolean | undefined;
+            name: string;
+            columns: Record<string, "ASC" | "DESC">;
+            schema: string;
+            tableName: string;
+            unique: boolean;
+        }[];
+        tables: {
+            replicaIdentityColumns: string[];
+            primaryKey?: string[] | undefined;
+            schemaOID?: number | undefined;
+            replicaIdentity?: "n" | "d" | "f" | "i" | undefined;
+            name: string;
+            schema: string;
+            oid: number;
+            columns: Record<string, {
+                pgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | undefined;
+                elemPgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | null | undefined;
+                characterMaximumLength?: number | null | undefined;
+                notNull?: boolean | null | undefined;
+                dflt?: string | null | undefined;
+                pos: number;
+                dataType: string;
+                typeOID: number;
+            }>;
+            publications: Record<string, {
+                rowFilter: string | null;
+            }>;
+        }[];
+    } | null>;
     event: v.Type<{
         tag: string;
     }>;
@@ -334,8 +461,42 @@ export declare const replicationEventSchema: v.UnionType<[v.ObjectType<Omit<Omit
     event: v.ObjectType<{
         tag: v.Type<string>;
     }, undefined>;
-}, "type"> & {
+}, "type" | "previousSchema"> & {
     type: v.Type<"ddlUpdate">;
+    previousSchema: v.Optional<{
+        indexes: {
+            isReplicaIdentity?: boolean | undefined;
+            isPrimaryKey?: boolean | undefined;
+            isImmediate?: boolean | undefined;
+            name: string;
+            columns: Record<string, "ASC" | "DESC">;
+            schema: string;
+            tableName: string;
+            unique: boolean;
+        }[];
+        tables: {
+            replicaIdentityColumns: string[];
+            primaryKey?: string[] | undefined;
+            schemaOID?: number | undefined;
+            replicaIdentity?: "n" | "d" | "f" | "i" | undefined;
+            name: string;
+            schema: string;
+            oid: number;
+            columns: Record<string, {
+                pgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | undefined;
+                elemPgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | null | undefined;
+                characterMaximumLength?: number | null | undefined;
+                notNull?: boolean | null | undefined;
+                dflt?: string | null | undefined;
+                pos: number;
+                dataType: string;
+                typeOID: number;
+            }>;
+            publications: Record<string, {
+                rowFilter: string | null;
+            }>;
+        }[];
+    }>;
 }, undefined>, v.ObjectType<Omit<Omit<{
     context: v.ObjectType<{
         query: v.Type<string>;
@@ -379,10 +540,62 @@ export declare const replicationEventSchema: v.UnionType<[v.ObjectType<Omit<Omit
     event: v.ObjectType<{
         tag: v.Type<string>;
     }, undefined>;
-}, "type"> & {
+}, "type" | "previousSchema"> & {
     type: v.Type<"schemaSnapshot">;
+    previousSchema: v.Optional<{
+        indexes: {
+            isReplicaIdentity?: boolean | undefined;
+            isPrimaryKey?: boolean | undefined;
+            isImmediate?: boolean | undefined;
+            name: string;
+            columns: Record<string, "ASC" | "DESC">;
+            schema: string;
+            tableName: string;
+            unique: boolean;
+        }[];
+        tables: {
+            replicaIdentityColumns: string[];
+            primaryKey?: string[] | undefined;
+            schemaOID?: number | undefined;
+            replicaIdentity?: "n" | "d" | "f" | "i" | undefined;
+            name: string;
+            schema: string;
+            oid: number;
+            columns: Record<string, {
+                pgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | undefined;
+                elemPgTypeClass?: "e" | "d" | "b" | "c" | "p" | "r" | "m" | null | undefined;
+                characterMaximumLength?: number | null | undefined;
+                notNull?: boolean | null | undefined;
+                dflt?: string | null | undefined;
+                pos: number;
+                dataType: string;
+                typeOID: number;
+            }>;
+            publications: Record<string, {
+                rowFilter: string | null;
+            }>;
+        }[];
+    }>;
 }, undefined>]>;
 export type ReplicationEvent = v.Infer<typeof replicationEventSchema>;
+/**
+ * Event trigger functions contain the core logic that are invoked by triggers.
+ *
+ * Note that although many of these functions can theoretically be parameterized and
+ * shared across shards, it is advantageous to keep the functions in each shard
+ * isolated from each other in order to avoid the complexity of shared-function
+ * versioning.
+ *
+ * In a sense, shards (and their triggers and functions) should be thought of as
+ * execution environments that can be updated at different schedules. If per-shard
+ * triggers called into shared functions, we would have to consider versioning the
+ * functions when changing their behavior, backwards compatibility, removal of
+ * unused versions, etc. (not unlike versioning of npm packages).
+ *
+ * Instead, we opt for the simplicity and isolation of having each shard
+ * completely own (and maintain) the entirety of its trigger/function stack.
+ */
+export declare function createEventFunctionStatements(shard: ShardConfig): string;
 export declare const TAGS: readonly ["CREATE TABLE", "ALTER TABLE", "CREATE INDEX", "DROP TABLE", "DROP INDEX", "ALTER PUBLICATION", "ALTER SCHEMA"];
 export declare function createEventTriggerStatements(shard: ShardConfig): string;
 export declare function dropEventTriggerStatements(appID: string, shardID: string | number): string;

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

@@ -1 +1 @@
-{"version":3,"file":"ddl.d.ts","sourceRoot":"","sources":["../../../../../../../../zero-cache/src/services/change-source/pg/schema/ddl.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,CAAC,MAAM,wCAAwC,CAAC;AAC5D,OAAO,EAAiB,KAAK,WAAW,EAAC,MAAM,6BAA6B,CAAC;AAU7E,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAQlC,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAIzB,CAAC;AASH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAO9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAE/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAEpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAIlC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAsMtE,eAAO,MAAM,IAAI,2HAQP,CAAC;AAEX,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,WAAW,UAmC9D;AAGD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GAAG,MAAM,UAMzB"}
+{"version":3,"file":"ddl.d.ts","sourceRoot":"","sources":["../../../../../../../../zero-cache/src/services/change-source/pg/schema/ddl.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,CAAC,MAAM,wCAAwC,CAAC;AAC5D,OAAO,EAAiB,KAAK,WAAW,EAAC,MAAM,6BAA6B,CAAC;AAU7E,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAQlC,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAIzB,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAc9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAQ/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAGpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAIlC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAYtE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,WAAW,UAwM/D;AAGD,eAAO,MAAM,IAAI,2HAQP,CAAC;AAEX,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,WAAW,UAoC9D;AAGD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GAAG,MAAM,UAMzB"}