pg_automergev0.1.0

Updating

On Kubernetes with CloudNativePG, an update is a new extension image tag in the Cluster (a rolling restart) followed by ALTER EXTENSION pg_automerge UPDATE, or a bumped version in the Database resource: see CloudNativePG. The rest of this page is about the full Docker image and source installs.

A new pg_automerge version (a newer image on the same volume): recreate the container from the new image, then in every database that has the extension:

ALTER EXTENSION pg_automerge UPDATE;   -- as a superuser
SELECT extversion FROM pg_extension WHERE extname = 'pg_automerge';

The init script does not run on an existing volume, so this step is yours (a migration, say). Until you run it the new library serves the old SQL definitions, which it keeps supporting (see Versioning and upgrades). What changed in each version, and whether an update needs more than this (a REINDEX, say), is in Changelog.

0.1.0 is the first release, so there is nothing to update from yet. The steps below are how every later version is rolled out; the Changelog entry of each version says whether it needs anything more.

With compose, step by step

For an app whose compose.yaml runs this image as a service, called postgres below, on a named volume. Below, <version> is the new version (e.g. the one after 0.1.0), <user> is the service's POSTGRES_USER, the superuser the image created on first start (e.g. app for an app that sets POSTGRES_USER: app, postgres for this repository's compose.yaml; a cluster has a postgres role only if that was its POSTGRES_USER), and <db> a database with the extension (the service's POSTGRES_DB, e.g. app, and any other you created it in).

  1. Optionally, keep a dump: docker compose exec -T postgres pg_dump -U <user> -Fc <db> >before-<version>.dump.

  2. Get the new image: docker pull ghcr.io/theknarf/pg-automerge:<version> (the published image of the release), or build it in this repository with mise run docker-build (tags pg-automerge:<version> and pg-automerge:dev).

  3. Point the app's service at it: image: ghcr.io/theknarf/pg-automerge:<version> or image: pg-automerge:<version> in its compose.yaml (pin the version tag, not :latest or :dev, so the version changes only when you change it). If the service also has a build: section (e.g. one that builds the image from a checkout of this repository), set its args: PG_AUTOMERGE_VERSION: to the new version too, or remove the section: compose builds when the tag is missing or with --build, and the Dockerfile refuses a version other than Cargo.toml's (versions: PG_AUTOMERGE_VERSION=0.1.0 != <version> (Cargo.toml)).

  4. docker compose up -d: compose recreates the container from the new image on the same volume (the data stays; the init script does not run again). From here on the new library serves every query, even before the next step.

  5. In every database with the extension:

    docker compose exec postgres psql -U <user> -d <db> -c 'ALTER EXTENSION pg_automerge UPDATE'
docker compose exec postgres psql -U <user> -d <db> -Atc "SELECT extversion FROM pg_extension WHERE extname = 'pg_automerge'"   # <version>

    This runs the upgrade scripts from the installed version to the new one, all in one transaction. Unless the Changelog says otherwise, tables, indexes, generated columns, views and automerge_notify() triggers are untouched.

There is no downgrade script: to go back, restore the dump into the old image. mise run docker-upgrade-test rehearses these steps against throwaway containers: a container of the previous release's image (PG_AUTOMERGE_OLD_IMAGE, or built from its release tag) with data, then the new image on the same volume, with a POSTGRES_USER other than postgres, as many apps have. It runs the commands of steps 1 and 5 as written here, and builds a service like step 3's (its build.args updated, and, to show why, not). While 0.1.0 is the only version it has nothing to do and says so.

A new Postgres 18 minor release or Debian security fixes: the base image is pinned by digest in docker/Dockerfile (ARG PG_IMAGE, with how to find the current digest next to it). Update the digest, rebuild, recreate the container on the same volume. Nothing else to do: minor releases keep the data format and the extension ABI. Check for new digests regularly; a pinned image does not get security fixes by itself.

A new Postgres major version (19, ...): pg_automerge supports only 18 so far, and an image of it for 19 does not exist yet. When it does, the 18 volume cannot simply be mounted into it; either dump and restore (the automerge text form is the dump format and is stable across versions; restore with pg_automerge.max_load_memory=-1 as the Configuration section describes), or run pg_upgrade with both majors' binaries and pg_automerge built for both (the /var/lib/postgresql mount lets pg_upgrade --link work within one volume).