diff --git a/docs/spock_functions/functions/spock_sub_alter_options.md b/docs/spock_functions/functions/spock_sub_alter_options.md new file mode 100644 index 00000000..72dea4f0 --- /dev/null +++ b/docs/spock_functions/functions/spock_sub_alter_options.md @@ -0,0 +1,94 @@ +## NAME + +spock.sub_alter_options() + +### SYNOPSIS + +spock.sub_alter_options (subscription_name name, options jsonb) + +### RETURNS + + - true if the `options` object contained at least one key; the Spock + catalog is updated and the apply worker is signalled to restart. + + - false if the `options` object was empty (`{}`); the catalog is not + touched and the apply worker is not restarted. + + - Raises an ERROR if the subscription does not exist, if `options` is + not a JSON object, if an unrecognised key is supplied, or if any + option value fails validation. + +### DESCRIPTION + +Changes one or more options on an existing subscription in a single +atomic operation. + +Only the keys present in the `options` object are modified; omitted +options retain their current values. If the object is empty (`{}`), the +function returns false without touching the catalog or restarting the +apply worker. + +When at least one key is present in `options`, the function writes the +new values to the Spock catalog and signals the apply worker to restart +so that they take effect. The caller can use `spock.sub_show_status()` +or `spock.sub_wait_for_sync()` to confirm the worker has restarted and +reached `replicating` status. + +### ARGUMENTS + +subscription_name + + The name of an existing subscription. + +options + + A JSON object whose keys are the option names to change. Unrecognised + keys raise an error. Supported keys: + + forward_origins + + A JSON array of origin names whose transactions the subscriber + should apply or receive based on their origin. The only accepted + element is the string "all". Pass an empty array ([]) to disable + origin forwarding. + + apply_delay + + A PostgreSQL interval string (e.g. "2 seconds", "500ms", "0") + that sets how long the apply worker waits before applying each + transaction. The value must be a string; passing a bare number + raises an error. + + skip_schema + + A JSON array of schema names to exclude from apply. Pass an + empty array ([]) to clear the exclusion list. + +### EXAMPLE + +Set a 2-second apply delay: + + postgres=# SELECT spock.sub_alter_options('sub_n2_n1', + '{"apply_delay": "2 seconds"}'); + sub_alter_options + ------------------- + t + (1 row) + +Enable forwarding of all origins and exclude the `audit` schema in a +single call: + + postgres=# SELECT spock.sub_alter_options('sub_n2_n1', + '{"forward_origins": ["all"], "skip_schema": ["audit"]}'); + sub_alter_options + ------------------- + t + (1 row) + +No-op call (empty object); returns false without restarting the worker: + + postgres=# SELECT spock.sub_alter_options('sub_n2_n1', '{}'); + sub_alter_options + ------------------- + f + (1 row) diff --git a/docs/spock_functions/index.md b/docs/spock_functions/index.md index 22a332dd..6dfe1e66 100644 --- a/docs/spock_functions/index.md +++ b/docs/spock_functions/index.md @@ -5,53 +5,54 @@ The following user functions are available via the Spock extension: | Command | Description | |----------|-------------| | **Node Management Functions** | You can add and remove nodes dynamically using Spock interfaces.| -| spock.node_info | Returns information about the node on which the function is invoked. -| [spock.node_create](functions/spock_node_create.md) | Define a node for spock. -| [spock.node_drop](functions/spock_node_drop.md) | Remove a spock node. -| [node_add_interface](functions/spock_node_add_interface.md) | Add a new node interface. -| [spock.node_drop_interface](functions/spock_node_drop_interface.md) | Delete a node interface. -| **Replication Set Management Functions** | Replication sets provide a mechanism to control which tables in the database will be replicated and which actions on those tables will be replicated. Each replicated set can specify individually if `INSERTs`, `UPDATEs`, `DELETEs` and `TRUNCATEs` on the set are replicated. Each table can be in multiple replication sets, and each subscriber can subscribe to multiple replication sets. The resulting set of tables and actions replicated is the union of the sets the table is in. Spock installation creates three replication sets: `default`, `default_insert_only` and `ddl_sql`. The `default` replication set is defined to replicate all changes to tables in it. The `default_insert_only` replication set only replicates `INSERT` statements, and is meant for use by tables that don't have primary key. The `ddl_sql` replication set is defined to replicate schema changes specified by `spock.replicate_ddl`.| -| [spock.repset_create](functions/spock_repset_create.md) | Define a replication set. -| [spock.repset_alter](functions/spock_repset_alter.md) | Modify a replication set. -| [repset_drop](functions/spock_repset_drop.md) | Remove a replication set. -| [spock.repset_add_partition](functions/spock_repset_add_partition.md) | Add a partition to a replication set. -| [spock.repset_remove_partition](functions/spock_repset_remove_partition.md) | Remove a partition from the replication set that the parent table is a part of. -| [spock.repset_add_table](functions/spock_repset_add_table.md) | Add table(s) to replication set. -| [spock.repset_add_all_tables](functions/spock_repset_add_all_tables.md) | Add all existing table(s) to the replication set. -| [spock.repset_remove_table](functions/spock_repset_remove_table.md) | Remove table from replication set. -| spock.repset_show_table | -| [spock.repset_add_seq](functions/spock_repset_add_seq.md) | Adds a sequence to a replication set. -| [spock.repset_add_all_seqs](functions/spock_repset_add_all_seqs.md) | Adds all sequences from the specified schemas to a replication set. -| [spock.repset_remove_seq](functions/spock_repset_remove_seq.md) | Remove a sequence from a replication set. -| spock.sync_seq | Synchronize the specified sequence. +| spock.node_info | Returns information about the node on which the function is invoked. | +| [spock.node_create](functions/spock_node_create.md) | Define a node for spock. | +| [spock.node_drop](functions/spock_node_drop.md) | Remove a spock node. | +| [node_add_interface](functions/spock_node_add_interface.md) | Add a new node interface. | +| [spock.node_drop_interface](functions/spock_node_drop_interface.md) | Delete a node interface. | +| **Replication Set Management Functions** | Replication sets provide a mechanism to control which tables in the database will be replicated and which actions on those tables will be replicated. Each replicated set can specify individually if `INSERTs`, `UPDATEs`, `DELETEs` and `TRUNCATEs` on the set are replicated. Each table can be in multiple replication sets, and each subscriber can subscribe to multiple replication sets. The resulting set of tables and actions replicated is the union of the sets the table is in. Spock installation creates three replication sets: `default`, `default_insert_only` and `ddl_sql`. The `default` replication set is defined to replicate all changes to tables in it. The `default_insert_only` replication set only replicates `INSERT` statements, and is meant for use by tables that don't have primary key. The `ddl_sql` replication set is defined to replicate schema changes specified by `spock.replicate_ddl`. | +| [spock.repset_create](functions/spock_repset_create.md) | Define a replication set. | +| [spock.repset_alter](functions/spock_repset_alter.md) | Modify a replication set. | +| [repset_drop](functions/spock_repset_drop.md) | Remove a replication set. | +| [spock.repset_add_partition](functions/spock_repset_add_partition.md) | Add a partition to a replication set. | +| [spock.repset_remove_partition](functions/spock_repset_remove_partition.md) | Remove a partition from the replication set that the parent table is a part of. | +| [spock.repset_add_table](functions/spock_repset_add_table.md) | Add table(s) to replication set. | +| [spock.repset_add_all_tables](functions/spock_repset_add_all_tables.md) | Add all existing table(s) to the replication set. | +| [spock.repset_remove_table](functions/spock_repset_remove_table.md) | Remove table from replication set. | +| spock.repset_show_table | | +| [spock.repset_add_seq](functions/spock_repset_add_seq.md) | Adds a sequence to a replication set. | +| [spock.repset_add_all_seqs](functions/spock_repset_add_all_seqs.md) | Adds all sequences from the specified schemas to a replication set. | +| [spock.repset_remove_seq](functions/spock_repset_remove_seq.md) | Remove a sequence from a replication set. | +| spock.sync_seq | Synchronize the specified sequence. | | **Subscription Management Functions** | | -| [spock.sub_create](functions/spock_sub_create.md) | Create a subscription. -| [spock.sub_drop](functions/spock_sub_drop.md) | Delete a subscription. -| [spock.sub_disable](functions/spock_sub_disable.md) | Put a subscription on hold, and disconnect from the provider. -| [spock.sub_enable](functions/spock_sub_enable.md) | Make a subscription live. -| [spock.sub_add_repset](functions/spock_sub_add_repset.md) | Add a replication set to a subscription. -| [spock.sub_remove_repset](functions/spock_sub_remove_repset.md) | Drop a replication set from a subscription. -| [spock.sub_show_status](functions/spock_sub_show_status.md) | Display the status of the subcription. -| [spock.sub_show_table](functions/spock_sub_show_table.md) | Show subscription tables. -| [spock.sub_alter_interface](functions/spock_sub_alter_interface.md) | Modify an interface to a subscription. -| [spock.sub_wait_for_sync](functions/spock_sub_wait_for_sync.md) | Pause until the subscription is synchronized. -| spock.sub_alter_skiplsn | Skip transactions until the specified lsn. -| spock.sub_alter_sync | Synchronize all missing tables. -| spock.sub_resync_table | Synchronize a specific table. +| [spock.sub_create](functions/spock_sub_create.md) | Create a subscription. | +| [spock.sub_drop](functions/spock_sub_drop.md) | Delete a subscription. | +| [spock.sub_disable](functions/spock_sub_disable.md) | Put a subscription on hold, and disconnect from the provider. | +| [spock.sub_enable](functions/spock_sub_enable.md) | Make a subscription live. | +| [spock.sub_add_repset](functions/spock_sub_add_repset.md) | Add a replication set to a subscription. | +| [spock.sub_remove_repset](functions/spock_sub_remove_repset.md) | Drop a replication set from a subscription. | +| [spock.sub_show_status](functions/spock_sub_show_status.md) | Display the status of the subcription. | +| [spock.sub_show_table](functions/spock_sub_show_table.md) | Show subscription tables. | +| [spock.sub_alter_interface](functions/spock_sub_alter_interface.md) | Modify an interface to a subscription. | +| [spock.sub_wait_for_sync](functions/spock_sub_wait_for_sync.md) | Pause until the subscription is synchronized. | +| spock.sub_alter_skiplsn | Skip transactions until the specified lsn. | +| spock.sub_alter_sync | Synchronize all missing tables. | +| [spock.sub_alter_options](functions/spock_sub_alter_options.md) | Change one or more subscription options in a single atomic operation. | +| spock.sub_resync_table | Synchronize a specific table. | | **Miscellaneous Management Functions** | | -| [spock.table_wait_for_sync](functions/spock_table_wait_for_sync.md) | Pause until a table finishes synchronizing. -| [spock.replicate_ddl](functions/spock_replicate_ddl.md) | Enable DDL replication. -| spock_version | Returns the Spock version in a major/minor version form: `4.0.10`. Defined in the public schema so invoked without the `spock.` prefix. -| spock_version_num | Returns the Spock version in a single numeric form: `40010`. Defined in the public schema so invoked without the `spock.` prefix. -| spock.get_channel_stats | Returns tuple traffic statistics. -| spock.get_country | Returns the country code if explicitly set; returns `??` if not set. -| spock.lag_tracker | Returns a list of slots, with commit_lsn and commit_timestamp for each. -| spock.repair_mode | Used to manage the state of replication - If set to `true`, stops replicating statements; when `false`, resumes replication. -| spock.replicate_ddl | Replicate a specific statement. -| spock.reset_channel_stats | Reset the channel statistics. -| spock_max_proto_version | The highest Spock native protocol supported by the current binary/build. Defined in the public schema so invoked without the `spock.` prefix. -| spock_min_proto_version | The lowest build for which this Spock binary is backward compatible. Defined in the public schema so invoked without the `spock.` prefix. -| spock.table_data_filtered | Scans the specified table and returns rows that match the row filter from the specified replication set(s). Row filters are added to a replication set when adding a table with `repset_add_table`. -| spock.terminate_active_transactions | Terminates all active transactions. -| spock.wait_slot_confirm_lsn | Wait for the `confirmed_flush_lsn` of the specified slot, or all logical slots if none given. -| spock.xact_commit_timestamp_origin | Returns the commit timestamp and origin of the specified transaction. +| [spock.table_wait_for_sync](functions/spock_table_wait_for_sync.md) | Pause until a table finishes synchronizing. | +| [spock.replicate_ddl](functions/spock_replicate_ddl.md) | Enable DDL replication. | +| spock_version | Returns the Spock version in a major/minor version form: `4.0.10`. Defined in the public schema so invoked without the `spock.` prefix. | +| spock_version_num | Returns the Spock version in a single numeric form: `40010`. Defined in the public schema so invoked without the `spock.` prefix. | +| spock.get_channel_stats | Returns tuple traffic statistics. | +| spock.get_country | Returns the country code if explicitly set; returns `??` if not set. | +| spock.lag_tracker | Returns a list of slots, with commit_lsn and commit_timestamp for each. | +| spock.repair_mode | Used to manage the state of replication - If set to `true`, stops replicating statements; when `false`, resumes replication. | +| spock.replicate_ddl | Replicate a specific statement. | +| spock.reset_channel_stats | Reset the channel statistics. | +| spock_max_proto_version | The highest Spock native protocol supported by the current binary/build. Defined in the public schema so invoked without the `spock.` prefix. | +| spock_min_proto_version | The lowest build for which this Spock binary is backward compatible. Defined in the public schema so invoked without the `spock.` prefix. | +| spock.table_data_filtered | Scans the specified table and returns rows that match the row filter from the specified replication set(s). Row filters are added to a replication set when adding a table with `repset_add_table`. | +| spock.terminate_active_transactions | Terminates all active transactions. | +| spock.wait_slot_confirm_lsn | Wait for the `confirmed_flush_lsn` of the specified slot, or all logical slots if none given. | +| spock.xact_commit_timestamp_origin | Returns the commit timestamp and origin of the specified transaction. | diff --git a/docs/spock_functions/sub_mgmt.md b/docs/spock_functions/sub_mgmt.md index e6cfc7d7..367f1ed2 100644 --- a/docs/spock_functions/sub_mgmt.md +++ b/docs/spock_functions/sub_mgmt.md @@ -13,6 +13,7 @@ the publisher. | [spock.sub_enable](functions/spock_sub_enable.md) | Enables a disabled subscription. | [spock.sub_alter_interface](functions/spock_sub_alter_interface.md) | Switch the subscription to use a different interface to connect to the provider node. | [spock.sub_alter_sync](functions/spock_sub_alter_sync.md) | Synchronize all unsynchronized tables in a single operation. +| [spock.sub_alter_options](functions/spock_sub_alter_options.md) | Change one or more subscription options in a single atomic operation. | [spock.sub_resync_table](functions/spock_sub_resync_table.md) | Resynchronize a single table. | [spock.sub_wait_for_sync](functions/spock_sub_wait_for_sync.md) | Wait for a subscription to finish synchronization after a `spock.sub_create` or `spock.sub_alter_sync`. | [spock.table_wait_for_sync](functions/spock_table_wait_for_sync.md) | Wait only for the subscription's initial sync and a named table. diff --git a/mkdocs.yml b/mkdocs.yml index e14c0d92..fc1181ea 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -115,6 +115,7 @@ nav: - spock.sub_add_repset(): spock_functions/functions/spock_sub_add_repset.md - spock.sub_alter_interface(): spock_functions/functions/spock_sub_alter_interface.md - spock.sub_alter_skiplsn(): spock_functions/functions/spock_sub_alter_skiplsn.md + - spock.sub_alter_options(): spock_functions/functions/spock_sub_alter_options.md - spock.sub_alter_sync(): spock_functions/functions/spock_sub_alter_sync.md - spock.sub_create(): spock_functions/functions/spock_sub_create.md - spock.sub_disable(): spock_functions/functions/spock_sub_disable.md