Skip to content

Add docs for spock.sub_alter_options() #495

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mason-sharp merged 3 commits into from
Jun 11, 2026
+145 −48
Merged

Add docs for spock.sub_alter_options() #495

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b2a9faf
Add docs for spock.sub_alter_options()
Jun 9, 2026
3c87498
Add spock.sub_alter_options() to mkdocs.yml nav
Jun 9, 2026
b272808
Updates for feedback on spock_sub_alter_options.md
Jun 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions docs/spock_functions/functions/spock_sub_alter_options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
97 changes: 49 additions & 48 deletions docs/spock_functions/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |

@coderabbitai coderabbitai Bot Jun 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix spelling error: "subcription" → "subscription".

The description contains a typo that should be corrected for documentation quality.

📝 Proposed fix 
-| [spock.sub_show_status](functions/spock_sub_show_status.md) | Display the status of the subcription. |
+| [spock.sub_show_status](functions/spock_sub_show_status.md) | Display the status of the subscription. |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| [spock.sub_show_status](functions/spock_sub_show_status.md) | Display the status of the subcription. |
| [spock.sub_show_status](functions/spock_sub_show_status.md) | Display the status of the subscription. |
🧰 Tools
🪛 LanguageTool

[grammar] ~34-~34: Ensure spelling is correct
Context: ..._status.md) | Display the status of the subcription. | | [spock.sub_show_table](functions/s...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/spock_functions/index.md` at line 34, Fix the spelling error in the
documentation entry for spock.sub_show_status: change the description string
"Display the status of the subcription." to "Display the status of the
subscription." in the docs entry for spock.sub_show_status so the function's
description reads correctly.

Source: Linters/SAST tools

| [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. |
1 change: 1 addition & 0 deletions docs/spock_functions/sub_mgmt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading