diff --git a/changes/unreleased/Added-20260827-140429.yaml b/changes/unreleased/Added-20260827-140429.yaml new file mode 100644 index 00000000..e24f3d42 --- /dev/null +++ b/changes/unreleased/Added-20260827-140429.yaml @@ -0,0 +1,3 @@ +kind: Added +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/docs/prerequisites/concepts.md b/docs/prerequisites/concepts.md index 88c7eac0..fe76ee27 100644 --- a/docs/prerequisites/concepts.md +++ b/docs/prerequisites/concepts.md @@ -37,6 +37,15 @@ 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 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 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..6b2c09b6 100644 --- a/docs/using/image-management.md +++ b/docs/using/image-management.md @@ -264,6 +264,74 @@ 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 as a preview manifest entry (`"stability": "dev"` +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`. To create a new database on the Spock 6 preview +image, set `postgres_version` and `spock_version` to match the +manifest entry: + +=== "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", + "nodes": [ + { "name": "n1", "host_ids": ["host-1"] }, + { "name": "n2", "host_ids": ["host-2"] } + ] + } + }' + ``` + +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 + 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