Make the set of reserved schemas and extensions configurable

Spock keeps certain schemas and extensions out of the structure
synchronization dump, and forbids their tables from being added to a
replication set.  This set was fixed and could only be changed by
rebuilding the extension, and the two behaviours were maintained
independently, so they could drift apart.

Keep the set in a catalog instead, seeded with the same defaults as
before: spock and snowflake are both excluded from the dump and blocked
from replication sets, while lolor is excluded from the dump but still
allowed in replication sets so that large objects survive dropping the
extension on every node.  The seeded entries are protected and cannot be
removed, and an operator can now reserve additional schemas or extensions
without rebuilding.  Such additions are preserved across dump and
restore, while the built-in entries are always re-created.

Author: Ibrar Ahmed

docs/spock_functions/repset_mgmt.md

@@ -85,6 +85,47 @@ SELECT spock.repset_add_table('accts', 'payables');
 Adds a table named `payables` to a replication set named `accts`. Since no
 columns are specified, all columns will be replicated.
 
+## Reserved Schemas and Extensions
+
+Some schemas and extensions are reserved and are treated specially by Spock.
+They are listed in the `spock.reserved_object` catalog, which is the single
+source of truth for two behaviours:
+
+- `exclude_from_dump`: the object is left out of the structure-sync dump used
+  when a subscription synchronizes structure. Restoring these on a subscriber
+  that already has them would fail.
+- `block_in_repset`: a table in this schema, or belonging to this extension,
+  may not be added to a replication set.
+
+Spock seeds the following built-in rows, and they cannot be removed or
+modified:
+
+| Object            | exclude_from_dump | block_in_repset |
+|-------------------|-------------------|-----------------|
+| `spock`           | yes               | yes             |
+| `snowflake`       | yes               | yes             |
+| `lolor`           | yes               | no              |
+
+`lolor` is excluded from the dump but is intentionally allowed in replication
+sets: its tables must replicate so that large objects survive a
+`DROP EXTENSION` on every node, not only where the drop was issued.
+
+To reserve an additional schema or extension of your own, use
+`spock.reserved_object_add`:
+
+```sql
+-- keep a custom schema out of structure sync and out of replication sets
+SELECT spock.reserved_object_add('ace', 'schema');
+
+-- exclude an extension from the dump but still allow its tables in repsets
+SELECT spock.reserved_object_add('myext', 'extension', p_block_in_repset := false);
+```
+
+Use `spock.reserved_object_remove('ace', 'schema')` to drop your own entry.
+Reserved objects are node-local configuration: apply the same additions on
+each node of the cluster. Operator-added rows are preserved across
+`pg_dump`/`pg_restore`; the built-in rows are always re-seeded.
+
 ## Removing a Table from a Replication Set
 
 To remove a table from a replication set with Spock, connect to the server
@@ -293,3 +334,34 @@ Parameters:
 
 - `subscription_name` is the name of an existing subscription.
 - `replication_set` is the name of replication set to remove.
+
+### spock.reserved_object_add
+
+Use `spock.reserved_object_add` to reserve a schema or extension (see
+[Reserved Schemas and Extensions](#reserved-schemas-and-extensions)). If the
+object is already reserved, its flags are updated. Built-in objects cannot be
+changed.
+
+`spock.reserved_object_add(p_name name, p_kind text, p_exclude_from_dump bool
+DEFAULT true, p_block_in_repset bool DEFAULT true)`
+
+Parameters:
+
+- `p_name` is the schema or extension name.
+- `p_kind` is `'schema'` or `'extension'`.
+- `p_exclude_from_dump` keeps the object out of the structure-sync dump; the
+  default is `true`.
+- `p_block_in_repset` blocks the object from replication sets; the default is
+  `true`.
+
+### spock.reserved_object_remove
+
+Use `spock.reserved_object_remove` to remove one of your own reserved objects.
+Built-in objects are protected and cannot be removed.
+
+`spock.reserved_object_remove(p_name name, p_kind text)`
+
+Parameters:
+
+- `p_name` is the schema or extension name.
+- `p_kind` is `'schema'` or `'extension'`.

include/spock_node.h

@@ -60,9 +60,26 @@ typedef struct SpockSubscription
 	TimestampTz	created_at;	/* When this subscription was created */
 } SpockSubscription;
 
-/* NULL-terminated arrays */
-extern const char *const skip_schema[];
-extern const char *const skip_extension[];
+/*
+ * Reserved schemas/extensions are stored in the spock.reserved_object catalog
+ * (the single source of truth, replacing the old hard-coded C arrays).
+ * spock_reserved_object_names() returns the names of one kind of object
+ * reserved for one purpose.
+ */
+typedef enum ReservedObjectKind
+{
+	RESERVED_KIND_SCHEMA,
+	RESERVED_KIND_EXTENSION
+} ReservedObjectKind;
+
+typedef enum ReservedObjectPurpose
+{
+	RESERVED_PURPOSE_DUMP,		/* exclude_from_dump: kept out of structure sync */
+	RESERVED_PURPOSE_REPSET		/* block_in_repset: cannot join a replication set */
+} ReservedObjectPurpose;
+
+extern List *spock_reserved_object_names(ReservedObjectKind kind,
+										 ReservedObjectPurpose purpose);
 
 extern void create_node(SpockNode *node);
 extern void drop_node(Oid nodeid);

sql/spock--5.0.10--6.0.0.sql

@@ -346,3 +346,76 @@ REVOKE ALL ON FUNCTION spock.slot_enable_failover() FROM PUBLIC;
 
 SELECT spock.slot_enable_failover();
 
+-- ----------------------------------------------------------------------------
+-- Reserved objects: schemas and extensions Spock treats specially.
+-- Single source of truth (replacing hard-coded lists in the C code) for
+-- exclude_from_dump (structure-sync dump exclusion) and block_in_repset
+-- (may not be added to a replication set).  Built-in rows are protected.
+-- ----------------------------------------------------------------------------
+CREATE TABLE spock.reserved_object (
+    name              name    NOT NULL,
+    kind              text    NOT NULL CHECK (kind IN ('schema', 'extension')),
+    exclude_from_dump boolean NOT NULL DEFAULT true,
+    block_in_repset   boolean NOT NULL DEFAULT true,
+    builtin           boolean NOT NULL DEFAULT false,
+    PRIMARY KEY (name, kind)
+) WITH (user_catalog_table=true);
+
+-- Preserve operator-added rows across pg_dump/restore; built-ins are re-seeded
+-- by this script, so only non-built-in rows are dumped.
+SELECT pg_catalog.pg_extension_config_dump('spock.reserved_object', 'WHERE NOT builtin');
+
+-- lolor is excluded from the dump but NOT blocked from replication sets: its
+-- tables must replicate so large objects survive a DROP EXTENSION on all nodes.
+INSERT INTO spock.reserved_object (name, kind, exclude_from_dump, block_in_repset, builtin) VALUES
+    ('spock',     'schema',    true, true,  true),
+    ('spock',     'extension', true, true,  true),
+    ('snowflake', 'schema',    true, true,  true),
+    ('snowflake', 'extension', true, true,  true),
+    ('lolor',     'schema',    true, false, true),
+    ('lolor',     'extension', true, false, true);
+
+CREATE FUNCTION spock.reserved_object_guard()
+RETURNS trigger AS $$
+BEGIN
+    IF OLD.builtin THEN
+        RAISE EXCEPTION 'cannot % built-in reserved object "%" (%)',
+            lower(TG_OP), OLD.name, OLD.kind;
+    END IF;
+    IF TG_OP = 'DELETE' THEN
+        RETURN OLD;
+    END IF;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER reserved_object_guard
+    BEFORE UPDATE OR DELETE ON spock.reserved_object
+    FOR EACH ROW EXECUTE FUNCTION spock.reserved_object_guard();
+
+CREATE FUNCTION spock.reserved_object_add(
+    p_name              name,
+    p_kind              text,
+    p_exclude_from_dump boolean DEFAULT true,
+    p_block_in_repset   boolean DEFAULT true)
+RETURNS void
+LANGUAGE plpgsql AS $$
+BEGIN
+    UPDATE spock.reserved_object
+       SET exclude_from_dump = p_exclude_from_dump,
+           block_in_repset   = p_block_in_repset
+     WHERE name = p_name AND kind = p_kind;
+    IF NOT FOUND THEN
+        INSERT INTO spock.reserved_object
+            (name, kind, exclude_from_dump, block_in_repset, builtin)
+        VALUES (p_name, p_kind, p_exclude_from_dump, p_block_in_repset, false);
+    END IF;
+END;
+$$;
+
+CREATE FUNCTION spock.reserved_object_remove(object_name name, object_kind text)
+RETURNS void
+LANGUAGE sql AS $$
+    DELETE FROM spock.reserved_object WHERE name = object_name AND kind = object_kind;
+$$;
+

sql/spock--6.0.0.sql

@@ -319,6 +319,91 @@ CREATE TABLE spock.replication_set_seq (
     PRIMARY KEY(set_id, set_seqoid)
 ) WITH (user_catalog_table=true);
 
+-- ----------------------------------------------------------------------------
+-- Reserved objects: schemas and extensions Spock treats specially.
+--
+-- Single source of truth (replacing hard-coded lists in the C code) for:
+--   * exclude_from_dump - kept out of the structure-sync dump (pg_dump
+--     --exclude-schema / --exclude-extension); restoring these on a subscriber
+--     that already has them would fail.
+--   * block_in_repset   - may not be added to a replication set.
+--
+-- Built-in rows (builtin = true) are seeded by the extension and are protected
+-- from removal/modification.  Add your own with spock.reserved_object_add().
+-- ----------------------------------------------------------------------------
+CREATE TABLE spock.reserved_object (
+    name              name    NOT NULL,
+    kind              text    NOT NULL CHECK (kind IN ('schema', 'extension')),
+    exclude_from_dump boolean NOT NULL DEFAULT true,
+    block_in_repset   boolean NOT NULL DEFAULT true,
+    builtin           boolean NOT NULL DEFAULT false,
+    PRIMARY KEY (name, kind)
+) WITH (user_catalog_table=true);
+
+-- Preserve operator-added rows across pg_dump/restore; built-ins are re-seeded
+-- by this script, so only non-built-in rows are dumped.
+SELECT pg_catalog.pg_extension_config_dump('spock.reserved_object', 'WHERE NOT builtin');
+
+-- lolor is excluded from the dump but NOT blocked from replication sets: its
+-- tables must replicate so large objects survive a DROP EXTENSION on all nodes.
+INSERT INTO spock.reserved_object (name, kind, exclude_from_dump, block_in_repset, builtin) VALUES
+    ('spock',     'schema',    true, true,  true),
+    ('spock',     'extension', true, true,  true),
+    ('snowflake', 'schema',    true, true,  true),
+    ('snowflake', 'extension', true, true,  true),
+    ('lolor',     'schema',    true, false, true),
+    ('lolor',     'extension', true, false, true);
+
+-- Protect built-in rows so replication can't be broken by dropping
+-- spock/snowflake/lolor from the reserved set.
+CREATE FUNCTION spock.reserved_object_guard()
+RETURNS trigger AS $$
+BEGIN
+    IF OLD.builtin THEN
+        RAISE EXCEPTION 'cannot % built-in reserved object "%" (%)',
+            lower(TG_OP), OLD.name, OLD.kind;
+    END IF;
+    IF TG_OP = 'DELETE' THEN
+        RETURN OLD;
+    END IF;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER reserved_object_guard
+    BEFORE UPDATE OR DELETE ON spock.reserved_object
+    FOR EACH ROW EXECUTE FUNCTION spock.reserved_object_guard();
+
+-- Add (or update) a user-defined reserved object.  (ON CONFLICT is not
+-- allowed on a user_catalog_table, so upsert by hand; updating a built-in row
+-- is rejected by the guard trigger.)
+CREATE FUNCTION spock.reserved_object_add(
+    p_name              name,
+    p_kind              text,
+    p_exclude_from_dump boolean DEFAULT true,
+    p_block_in_repset   boolean DEFAULT true)
+RETURNS void
+LANGUAGE plpgsql AS $$
+BEGIN
+    UPDATE spock.reserved_object
+       SET exclude_from_dump = p_exclude_from_dump,
+           block_in_repset   = p_block_in_repset
+     WHERE name = p_name AND kind = p_kind;
+    IF NOT FOUND THEN
+        INSERT INTO spock.reserved_object
+            (name, kind, exclude_from_dump, block_in_repset, builtin)
+        VALUES (p_name, p_kind, p_exclude_from_dump, p_block_in_repset, false);
+    END IF;
+END;
+$$;
+
+-- Remove a user-defined reserved object (built-ins are protected by the guard).
+CREATE FUNCTION spock.reserved_object_remove(object_name name, object_kind text)
+RETURNS void
+LANGUAGE sql AS $$
+    DELETE FROM spock.reserved_object WHERE name = object_name AND kind = object_kind;
+$$;
+
 CREATE TABLE spock.sequence_state (
 	seqoid oid NOT NULL PRIMARY KEY,
 	cache_size integer NOT NULL,