From fbe76bc7762d8121d3e922aca21f4fc890202430 Mon Sep 17 00:00:00 2001 From: Siva Date: Wed, 2 Sep 2026 11:07:54 +0530 Subject: [PATCH 1/3] docs: document Spock 6 preview support --- changes/unreleased/Added-20260827-140429.yaml | 3 + changes/unreleased/Fixed-20260821-141322.yaml | 3 + docs/prerequisites/concepts.md | 8 +++ docs/using/image-management.md | 57 +++++++++++++++++++ 4 files changed, 71 insertions(+) create mode 100644 changes/unreleased/Added-20260827-140429.yaml create mode 100644 changes/unreleased/Fixed-20260821-141322.yaml diff --git a/changes/unreleased/Added-20260827-140429.yaml b/changes/unreleased/Added-20260827-140429.yaml new file mode 100644 index 00000000..c17050a4 --- /dev/null +++ b/changes/unreleased/Added-20260827-140429.yaml @@ -0,0 +1,3 @@ +kind: Added +body: Added foundational support for Spock 6, available as a dev-stability preview image via the version manifest. Databases running Spock 6 on Postgres 17 or later automatically use Postgres's native replication slot failover. +time: 2026-08-27T14:04:29.000000+00:00 diff --git a/changes/unreleased/Fixed-20260821-141322.yaml b/changes/unreleased/Fixed-20260821-141322.yaml new file mode 100644 index 00000000..58044ea0 --- /dev/null +++ b/changes/unreleased/Fixed-20260821-141322.yaml @@ -0,0 +1,3 @@ +kind: Fixed +body: Fixed peer subscriptions remaining permanently disabled when adding a node to a database that already had three or more nodes. +time: 2026-08-21T14:13:22.000000+00:00 diff --git a/docs/prerequisites/concepts.md b/docs/prerequisites/concepts.md index 88c7eac0..056bc085 100644 --- a/docs/prerequisites/concepts.md +++ b/docs/prerequisites/concepts.md @@ -37,6 +37,14 @@ Each node is composed of one or more Postgres instances, where one instance is a When a node which has multiple instances is created, the primary instance for the node will be placed on the first host specified for the node in the database spec. After a database is created, the primary instance may change due to a failover or switchover operation. +For a node running Spock 6 on Postgres 17 or later, the Control Plane +automatically configures Postgres's native replication slot failover +(`sync_replication_slots` and `synchronized_standby_slots`) for that +node. This keeps the node's Spock replication slots synchronized to its +read replicas, so a failover or switchover can promote a replica without +Spock needing to re-create replication slots on the new primary. No +configuration is required to use this behavior. + ## Orchestrators The Control Plane is architected to support multiple orchestrators, giving you flexibility in how database instances are deployed and managed. diff --git a/docs/using/image-management.md b/docs/using/image-management.md index ea513c14..5701f372 100644 --- a/docs/using/image-management.md +++ b/docs/using/image-management.md @@ -264,6 +264,63 @@ value in `orchestrator_opts.swarm.image` when creating the database: Digest pinning guarantees that you run a specific immutable image even if the tag is later reassigned to a different image in the registry. +### Spock 6 Preview Images + +Spock 6 is available today as a preview manifest entry (`"stability": +"dev"` in the version manifest), currently paired with Postgres 18.6. +Preview entries are excluded from image upgrades (see below) and are +never chosen for a database that omits `postgres_version` and +`spock_version`, but you can still request one directly by setting +those fields to a matching manifest entry, or by pinning the image +explicitly with `orchestrator_opts.swarm.image`. + +The following request creates a database pinned to the Spock 6 preview +image: + +=== "curl" + + ```sh + curl -X POST http://host-3:3000/v1/databases \ + -H 'Content-Type:application/json' \ + --data '{ + "id": "example", + "spec": { + "database_name": "example", + "database_users": [ + { + "username": "admin", + "db_owner": true, + "attributes": ["SUPERUSER", "LOGIN"] + } + ], + "postgres_version": "18.6", + "spock_version": "6", + "orchestrator_opts": { + "swarm": { + "image": "ghcr.io/pgedge/pgedge-postgres:18-spock6-standard" + } + }, + "nodes": [ + { "name": "n1", "host_ids": ["host-1"] }, + { "name": "n2", "host_ids": ["host-2"] } + ] + } + }' + ``` + +!!! note + + The Spock 6 preview image tracks the latest Spock 6 build against + Postgres 18, so its resolved Postgres minor version can advance ahead + of the manifest entry's declared `postgres_version`. + +!!! warning + + Preview images are for evaluation, not production use. The Control + Plane rejects preview images as targets for the + [image upgrade](./upgrade-db.md#image-upgrades) action, and they are + excluded from `available_upgrades`. + ## Image Validation When `orchestrator_opts.swarm.image` is set, the Control Plane validates the From 01bbb4ec68e599cafe50bfd8a117157b03dddec6 Mon Sep 17 00:00:00 2001 From: Siva Date: Wed, 2 Sep 2026 12:44:13 +0530 Subject: [PATCH 2/3] addressed AI review comments --- docs/prerequisites/concepts.md | 15 ++++++++------- docs/using/image-management.md | 4 ++-- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/prerequisites/concepts.md b/docs/prerequisites/concepts.md index 056bc085..fe76ee27 100644 --- a/docs/prerequisites/concepts.md +++ b/docs/prerequisites/concepts.md @@ -37,13 +37,14 @@ Each node is composed of one or more Postgres instances, where one instance is a When a node which has multiple instances is created, the primary instance for the node will be placed on the first host specified for the node in the database spec. After a database is created, the primary instance may change due to a failover or switchover operation. -For a node running Spock 6 on Postgres 17 or later, the Control Plane -automatically configures Postgres's native replication slot failover -(`sync_replication_slots` and `synchronized_standby_slots`) for that -node. This keeps the node's Spock replication slots synchronized to its -read replicas, so a failover or switchover can promote a replica without -Spock needing to re-create replication slots on the new primary. No -configuration is required to use this behavior. +For a node running Spock 6 or later on Postgres 17 or later, the Control +Plane automatically enables Postgres's native replication slot failover +(`sync_replication_slots`) for that node. When the node also has read +replicas, the Control Plane additionally configures +`synchronized_standby_slots` to keep the node's Spock replication slots +synchronized to those replicas, so a failover or switchover can promote +a replica without Spock needing to re-create replication slots on the +new primary. No configuration is required to use this behavior. ## Orchestrators diff --git a/docs/using/image-management.md b/docs/using/image-management.md index 5701f372..b717ebbf 100644 --- a/docs/using/image-management.md +++ b/docs/using/image-management.md @@ -266,8 +266,8 @@ value in `orchestrator_opts.swarm.image` when creating the database: ### Spock 6 Preview Images -Spock 6 is available today as a preview manifest entry (`"stability": -"dev"` in the version manifest), currently paired with Postgres 18.6. +Spock 6 is available as a preview manifest entry (`"stability": "dev"` +in the version manifest), currently paired with Postgres 18.6. Preview entries are excluded from image upgrades (see below) and are never chosen for a database that omits `postgres_version` and `spock_version`, but you can still request one directly by setting From 6b34df7626b949c5bef0a39feeaf7ee615ce2b45 Mon Sep 17 00:00:00 2001 From: Siva Date: Thu, 3 Sep 2026 16:13:09 +0530 Subject: [PATCH 3/3] addressing review comments --- changes/unreleased/Added-20260827-140429.yaml | 2 +- changes/unreleased/Fixed-20260821-141322.yaml | 3 -- docs/using/image-management.md | 35 ++++++++++++------- 3 files changed, 24 insertions(+), 16 deletions(-) delete mode 100644 changes/unreleased/Fixed-20260821-141322.yaml diff --git a/changes/unreleased/Added-20260827-140429.yaml b/changes/unreleased/Added-20260827-140429.yaml index c17050a4..e24f3d42 100644 --- a/changes/unreleased/Added-20260827-140429.yaml +++ b/changes/unreleased/Added-20260827-140429.yaml @@ -1,3 +1,3 @@ kind: Added -body: Added foundational support for Spock 6, available as a dev-stability preview image via the version manifest. Databases running Spock 6 on Postgres 17 or later automatically use Postgres's native replication slot failover. +body: Added foundational support for Spock 6 on Docker Swarm, available as a preview image via the version manifest. Databases running Spock 6 or later on Postgres 17 or later automatically use Postgres's native replication slot failover. time: 2026-08-27T14:04:29.000000+00:00 diff --git a/changes/unreleased/Fixed-20260821-141322.yaml b/changes/unreleased/Fixed-20260821-141322.yaml deleted file mode 100644 index 58044ea0..00000000 --- a/changes/unreleased/Fixed-20260821-141322.yaml +++ /dev/null @@ -1,3 +0,0 @@ -kind: Fixed -body: Fixed peer subscriptions remaining permanently disabled when adding a node to a database that already had three or more nodes. -time: 2026-08-21T14:13:22.000000+00:00 diff --git a/docs/using/image-management.md b/docs/using/image-management.md index b717ebbf..6b2c09b6 100644 --- a/docs/using/image-management.md +++ b/docs/using/image-management.md @@ -267,15 +267,17 @@ value in `orchestrator_opts.swarm.image` when creating the database: ### Spock 6 Preview Images Spock 6 is available as a preview manifest entry (`"stability": "dev"` -in the version manifest), currently paired with Postgres 18.6. +in the version manifest), currently paired with Postgres 18.6. Spock 6 +itself supports Postgres 15 through 19; the version manifest currently +offers only this one Postgres 18.6 pairing as a preview. This preview +is available for Docker Swarm deployments only; the systemd +orchestrator does not currently support Spock 6 packages. + Preview entries are excluded from image upgrades (see below) and are never chosen for a database that omits `postgres_version` and -`spock_version`, but you can still request one directly by setting -those fields to a matching manifest entry, or by pinning the image -explicitly with `orchestrator_opts.swarm.image`. - -The following request creates a database pinned to the Spock 6 preview -image: +`spock_version`. To create a new database on the Spock 6 preview +image, set `postgres_version` and `spock_version` to match the +manifest entry: === "curl" @@ -295,11 +297,6 @@ image: ], "postgres_version": "18.6", "spock_version": "6", - "orchestrator_opts": { - "swarm": { - "image": "ghcr.io/pgedge/pgedge-postgres:18-spock6-standard" - } - }, "nodes": [ { "name": "n1", "host_ids": ["host-1"] }, { "name": "n2", "host_ids": ["host-2"] } @@ -308,12 +305,26 @@ image: }' ``` +Overriding `orchestrator_opts.swarm.image` is only necessary if you need +an image other than the manifest default for that version pair, such as +pinning a specific build. See +[Using a Custom Image](#using-a-custom-image). + !!! note The Spock 6 preview image tracks the latest Spock 6 build against Postgres 18, so its resolved Postgres minor version can advance ahead of the manifest entry's declared `postgres_version`. +!!! warning + + This preview supports only creating a new database on Spock 6. It + does not support upgrading an existing database from Spock 5.x to + Spock 6. The Control Plane does not validate or block a + `spock_version` change on an existing database's spec, but doing so + is unsupported and can break replication, since a Spock 6 + subscription cannot sync from a Spock 5.x peer. + !!! warning Preview images are for evaluation, not production use. The Control