Skip to content

Moving work into new branch for PR against v5_STABLE #406

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

Open
susan-pgedge wants to merge 13 commits into
base: v5_STABLE
Choose a base branch
from
Open

Moving work into new branch for PR against v5_STABLE #406

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
638851f
Moving work into new branch for PR against v5_STABLE
Apr 3, 2026
0b44163
Update to function example
Apr 3, 2026
04b39fe
Update to function example
Apr 3, 2026
675b332
Removing batch_inserts.md and updating mkdocs for removal (SPOC-493)
Apr 3, 2026
72002de
Update to function example
Apr 3, 2026
ade6bb7
Update to function example
Apr 3, 2026
bb99fb0
Update to function example
Apr 3, 2026
e81a70f
Update to function example
Apr 3, 2026
e0d9b80
sql: reformat C function definitions to consistent multi-line style
danolivo Apr 9, 2026
25f3899
Fix doc filenames and content to match function names exactly
Apr 9, 2026
4b7ac48
This is an old CLI command; documented in another doc section
Apr 9, 2026
cfae422
Updates to functions for feedback from Andrei
Apr 9, 2026
4a1676e
Filled out content in snowflake.md per feedback from Andrei
Apr 9, 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
50 changes: 38 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,49 @@
[![Regression Tests and Spockbench](https://github.com/pgEdge/spock/actions/workflows/spockbench.yml/badge.svg)](https://github.com/pgEdge/spock/actions/workflows/spockbench.yml)

## Table of Contents
- [Building the Spock Extension](README.md#building-the-spock-extension)
- [Building the Spock Documentation](README.md#building-the-spock-documentation)
- [Basic Configuration and Usage](README.md#basic-configuration-and-usage)

- [Introduction](docs/index.md)
- [Installing and Configuring Spock](docs/install_spock.md)
- [Getting Started](docs/getting_started.md)
- [Using Advanced Configuration Options](docs/configuring.md)
- [Upgrading a Spock Installation](docs/upgrading_spock.md)
- [Advanced Configuration Options](docs/configuring.md)
- [Spock Management Features](docs/managing/index.md)
- [Modifying a Cluster](docs/modify/index.md)
- [Monitoring your Cluster](docs/monitoring/index.md)
- [Spock Functions](docs/spock_functions/index.md)
- [Using spockctrl Management Functions](docs/modify/spockctrl/index.md)
- [Release Notes](docs/spock_release_notes.md)
- [Spock's Conflict Avoidance Options](docs/conflicts.md)
- Spock's Management Features
- [Managing a Spock Installation](docs/managing/index.md)
- [Replicating Partitioned Tables](docs/managing/partition_mgmt.md)
- [Using Batch Inserts](docs/managing/batch_inserts.md)
- [Filtering Data](docs/managing/filtering.md)
- [Using Spock in Read-Only Mode](docs/managing/read_only.md)
- [Using a Trigger to Manage Replication Set Membership](docs/managing/repset_trigger.md)
- [Using Snowflake Sequences](docs/managing/snowflake.md)
- [Using Lolor to Manage Large Objects](docs/managing/lolor.md)
- [Using Automatic DDL Replication](docs/managing/spock_autoddl.md)
- Adding or Removing Nodes
- [Modifying a Cluster](docs/modify/index.md)
- Using Z0DAN
- [Modifying your Cluster with Zodan](docs/modify/zodan/index.md)
- [Using Zodan Scripts and Workflows](docs/modify/zodan/zodan_readme.md)
- [Adding a Node with Zero Downtime](docs/modify/zodan/zodan_tutorial.md)
- [Adding a Node with Minimal Downtime with pgBackRest](docs/modify/add_node_pgbackrest.md)
- Monitoring a Cluster
- [Monitoring the Configuration and Health of a Cluster](docs/monitoring/index.md)
- [Finding Cluster Information](docs/monitoring/spock_info.md)
- [Using Lag Tracking to Evaluate your Cluster](docs/monitoring/lag_tracking.md)
- [Using a Sync Event to Monitor Node Content](docs/monitoring/spock_sync_event.md)
- Using Spock Functions
- [Function List](docs/spock_functions/index.md)
- [Node Management Functions](docs/spock_functions/node_mgmt.md)
- [Replication Set Management Functions](docs/spock_functions/repset_mgmt.md)
- [Subscription Management Functions](docs/spock_functions/sub_mgmt.md)
- [Cluster Management Functions](docs/spock_functions/gen_mgmt.md)
- [Limitations](docs/limitations.md)
- [Troubleshooting](docs/troubleshooting.md)
- [FAQ](docs/FAQ.md)
- [Release Notes](docs/spock_release_notes.md)

## Spock Multi-Master Replication for PostgreSQL - Prerequisites and Requirements

The Spock extension provides multi-master replication for PostgreSQL versions 15 and later. Take the following requirements into consideration as you design your cluster:
The Spock extension provides multi-master replication for PostgreSQL versions 15, 16, 17, and 18. Take the following requirements into consideration as you design your cluster:

* You will need to install the `Spock` extension on each node in your cluster. If you're performing a major version upgrade, the old node can be running a recent version of pgLogical2 before upgrading it to become a Spock node.

Expand Down Expand Up @@ -74,7 +100,7 @@ primary key, btree, for table "public.table_a"

* `CHECK` constraints and `NOT NULL` constraints must be the same or more permissive on any standby node that acts only as a subscriber.

For more information about the Spock extension's advanced functionality, visit the [Spock documentation](docs/install_spock.md).
For more information about the Spock extension's advanced functionality, visit [here](docs/features.md).


## Building the Spock Extension
Expand Down
141 changes: 75 additions & 66 deletions docs/configuring.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,46 @@
# Configuring Spock

Add the following `postgresql.conf` settings on each node in your Spock
Add the following `postgresql.conf` settings on each node in your Spock
replication scenario before creating the Spock extension:

```sql
wal_level = 'logical'
max_worker_processes = 10 # one per database needed on provider node
# one per node needed on subscriber node
max_replication_slots = 10 # one per node needed on provider node
max_wal_senders = 10 # one per node needed on provider node
shared_preload_libraries = 'spock'
track_commit_timestamp = on # needed for conflict resolution
wal_level = 'logical'
max_worker_processes = 10 # one per database needed on provider node
# one per node needed on subscriber node
max_replication_slots = 10 # one per node needed on provider node
max_wal_senders = 10 # one per node needed on provider node
shared_preload_libraries = 'spock'
track_commit_timestamp = on # needed for conflict resolution
```

After modifying the parameters and restarting the Postgres server
with your OS-specific restart command, connect with psql and create the Spock
After modifying the parameters and restarting the Postgres server with your
OS-specific restart command, connect with psql and create the Spock
extension:

```sql
CREATE EXTENSION spock;
[pg18]$ sudo -u postgres psql -U postgres -p 5432
psql (18.1)
Type "help" for help.

postgres=# CREATE EXTENSION spock;
CREATE EXTENSION
```

You will also need to modify your
[`pg_hba.conf` file](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html)
[`pg_hba.conf` file](https://www.postgresql.org/docs/18/auth-pg-hba-conf.html)
to allow logical replication connections from localhost and between nodes.
Logical replication connections are treated by `pg_hba.conf` as regular
connections to the provider database.

After modifying the pg_hba.conf file on each node, restart the server to apply
the changes.
After modifying the pg_hba.conf file on each node, restart the server to
apply the changes.


## Advanced Configuration Options for Spock

You can use the following configuration parameters (GUCs) on the psql
command line with a `SET` statement or in a Postgres configuration file
(like `postgresql.conf`) to configure a Spock installation.
(for example, `postgresql.conf`) to configure a Spock installation.

### `spock.allow_ddl_from_functions`

Expand Down Expand Up @@ -68,17 +73,17 @@ option can only be set when the postmaster starts.
your own risk.

This parameter enhances conflict resolution during `INSERT` operations in
scenarios where a row exists that meets unique constraints defined on the
scenarios where a row exists that meets unique constraints defined on the
table (rather than primary keys or replication identity).

If this GUC is `enabled`, Spock will continue to check unique constraint
indexes, after checking the primary key / replica identity index. Only one
conflict will be resolved, using Last-Write-Wins logic. This includes the
primary key / replica identity index. If a second conflict occurs, an
indexes, after checking the primary key or replica identity index. Only one
conflict will be resolved, using Last-Write-Wins logic. This includes the
primary key or replica identity index. If a second conflict occurs, an
exception is recorded in the `spock.exception_log` table.

Partial unique constraints are supported, but nullable unique constraints
are not. Deferable constraints are not supported, are filtered out and are
are not. Deferrable constraints are not supported, are filtered out and are
not checked, and therefore may still cause an exception during the final
commit.

Expand All @@ -93,16 +98,16 @@ inadvertently create orphaned foreign key records.
### `spock.conflict_resolution`

`spock.conflict_resolution` sets the resolution method for any detected
conflicts between local data and incoming changes. Possible values are:
conflicts between local data and incoming changes. Possible values include:

* `error` - the replication will stop on error if conflict is detected and
manual action is needed for resolving
* `apply_remote` - always apply the change that's conflicting with local
data
* `keep_local` - keep the local version of the data and ignore the
conflicting change that is coming from the remote node
* `last_update_wins` - the version of data with newest commit timestamp
will be kept (this can be either local or remote version)
- `error` - the replication will stop on error if conflict is detected and
manual action is needed for resolving.
- `apply_remote` - always apply the change that's conflicting with local
data.
- `keep_local` - keep the local version of the data and ignore the
conflicting change that is coming from the remote node.
- `last_update_wins` - the version of data with newest commit timestamp
will be kept (this can be either local or remote version).

To enable conflict resolution, the `track_commit_timestamp` setting must be
enabled.
Expand All @@ -125,19 +130,19 @@ the `default` replication set.
Use this GUC to specify the commit behavior of Postgres when it encounters
an ERROR within a transaction:

* `transdiscard` (the default) - Set `spock.exception_behaviour` to
- `transdiscard` (the default) - set `spock.exception_behaviour` to
`transdiscard` to instruct the server to discard a transaction if any
operation within that transaction returns an `ERROR`.
* `discard` - Set `spock.exception_behaviour` to `discard` to continue
processing (and replicating) without interrupting server use. The server
- `discard` - set `spock.exception_behaviour` to `discard` to continue
processing (and replicating) without interrupting server use; the server
will commit any operation (any portion of a transaction) that does not
return an `ERROR` statement.
* `sub_disable` - Set `spock.exception_behaviour` to `sub_disable` to
disable the subscription for the node on which the exception was reported.
Transactions for the disabled node will be added to a queue that is
written to the WAL log file; when the subscription is enabled, replication
will resume with the transaction that caused the exception, followed by
the other queued transactions. You can use the
- `sub_disable` - set `spock.exception_behaviour` to `sub_disable` to
disable the subscription for the node on which the exception was
reported; transactions for the disabled node will be added to a queue
that is written to the WAL log file; when the subscription is enabled,
replication will resume with the transaction that caused the exception,
followed by the other queued transactions; you can use the
`spock.alter_sub_skip_lsn` function to skip the transaction that caused
the exception and resume processing with the next transaction in the
queue.
Expand All @@ -148,30 +153,33 @@ accumulate.

### `spock.exception_logging`

Use this GUC to specify which operations/transactions are written to the
Use this GUC to specify which operations or transactions are written to the
exception log table:

* `all` (the default) - Set `spock.exception_logging` to `all` to instruct
- `all` (the default) - set `spock.exception_logging` to `all` to instruct
the server to record all transactions that contain one or more failed
operations in the `spock.exception_log` table. Note that this setting will
log all operations that are part of a transaction if one operation fails.
* `discard` - Add a row to the `spock.exception_log` table for any
operations in the `spock.exception_log` table; note that this setting
will log all operations that are part of a transaction if one operation
fails.
- `discard` - add a row to the `spock.exception_log` table for any
discarded operation; successful transactions are not logged.
* `none` - Instructs the server to not log any operation or transactions to
- `none` - instructs the server to not log any operation or transactions to
the exception log table.

### `spock.exception_replay_queue_size`
### `spock.exception_replay_queue_size` - DEPRECATED

This parameter will not be supported after version 5.X.

When Spock encounters a replication exception, it attempts to resolve the
exception by entering exception-handling mode, based on the value of
`spock.exception_behaviour`. Spock then writes any transaction up to a
`spock.exception_behaviour`. Spock then writes any transaction up to a
default size of `4MB` to memory, and the apply worker replays the
transaction from memory. This provides a massive speed and performance
increase in the handling of the vast majority of exceptions. The memory
transaction from memory. This provides a massive speed and performance
increase in the handling of the vast majority of exceptions. The memory
size is configurable with `spock.exception_replay_queue_size`.

If the transaction exceeds the configured size, Spock performs as specified
by the [`spock.exception_behaviour`](#spock-exception_behaviour) parameter.
Now, Spock performs as specified by the
[`spock.exception_behaviour`](#spock-exception_behaviour) parameter.

### `spock.extra_connection_options`

Expand All @@ -184,14 +192,14 @@ keepalive options, etc.
the upstream server disappears unexpectedly. To disable them add
`keepalives = 0` to `spock.extra_connection_options`.

### `spock.feedback_frequency`
#### `spock.feedback_frequency`

Controls how many WAL messages the apply worker processes before sending
an LSN feedback packet to the provider. Lower values increase feedback
overhead due to synchronous socket flushes; higher values reduce overhead
during bulk catch-up. There is a time-based guard (wal_sender_timeout / 2)
that ensures connection liveness regardless of this setting. The default
is 200.
during bulk catch-up. There is a time-based guard (wal_sender_timeout
divided by 2) that ensures connection liveness regardless of this setting.
The default is 200.

### `spock.include_ddl_repset`

Expand All @@ -218,13 +226,12 @@ occur outside expected patterns.

The following configuration values are possible:

* `none` (the default)- do not log any origin change information
* `remote_only_differs`- only log origin changes when the existing row
was from one remote publisher and was changed by another
remote publisher
* `since_sub_creation`- log origin changes whether a publisher changed
a row that was previously from another publisher or updated it locally,
but only since the time when the subscription was created.
- `none` (the default) - do not log any origin change information.
- `remote_only_differs` - only log origin changes when the existing row was
from one remote publisher and was changed by another remote publisher.
- `since_sub_creation` - log origin changes whether a publisher changed a
row that was previously from another publisher or updated it locally, but
only since the time when the subscription was created.

### `spock.save_resolutions`

Expand All @@ -241,8 +248,10 @@ the postmaster starts. The parameter accepts values from `-1` to `INT_MAX`

### `spock.temp_directory`

`spock.temp_directory` defines the system path where temporary files
needed for schema synchronization are written. This path needs to exist
and be writable by the user running Postgres. The default is `empty`,
which tells Spock to use the default temporary directory based on
environment or operating system settings.
`spock.temp_directory` defines the system path where temporary files needed
for schema synchronization are written. This path needs to exist and be
writable by the user running Postgres. The default is `empty`, which tells
Spock to use the default temporary directory based on environment or
operating system settings.


Loading
Loading