feat(postgres): derive version from cloudsync.h, ship upgrade scripts

Before this change, default_version in the control file was frozen at
'1.0' across all 16 releases. Every user's pg_extension.extversion
reported '1.0' regardless of which .so they ran, no per-release upgrade
scripts existed, and no CI check flagged missing ones — so a version
bump could silently leave users unable to reach the new release via
`ALTER EXTENSION cloudsync UPDATE` and force them into a destructive
DROP EXTENSION ... CASCADE; CREATE EXTENSION ... workaround.

Single source of truth: the PG extension version is now derived from
CLOUDSYNC_VERSION in src/cloudsync.h (what the rest of the repo already
tracks). docker/Makefile.postgresql reads it and generates
cloudsync.control and cloudsync--<version>.sql at build time from new
.in templates; the generated files are gitignored.

Per-release upgrade scripts live under src/postgresql/migrations/ as
cloudsync--<from>--<to>.sql and are picked up by postgres-install,
postgres-package, and all three release Dockerfiles via wildcard.
Bootstrap: cloudsync--1.0--1.0.17.sql (comment-only, no SQL surface
changes) lets existing extversion='1.0' deployments upgrade cleanly.

CI gate: scripts/check-postgres-migration.sh + a postgres-check-migration
Make target + a new postgres-migration-check workflow job (both
postgres-test and postgres-build now block on it) resolve the previous
release's extversion from the most recent semver tag's control file (or
CLOUDSYNC_VERSION at that tag for new-scheme tags) and fail the build
if cloudsync--<prev>--<curr>.sql is missing. Sub-second; runs on every PR.

Also: bumped CLOUDSYNC_VERSION to 1.0.17; taught Dockerfile.supabase to
accept CLOUDSYNC_VERSION as a build arg for the image label; swept
version-hardcoded filenames out of docker/README.md,
docs/internal/supabase-flyio.md, and docs/postgresql/quickstarts/postgres.md.

Verified end-to-end: rebuilt the local debug container with a persistent
volume at installed_version='1.0', ran `ALTER EXTENSION cloudsync UPDATE;`,
confirmed installed_version moved to '1.0.17'.

Author: andinux

.github/workflows/main.yml

@@ -239,8 +239,24 @@ jobs:
           path: dist/${{ matrix.name == 'apple-xcframework' && 'CloudSync.*' || 'cloudsync.*'}}
           if-no-files-found: error
 
+  postgres-migration-check:
+    if: ${{ !contains(github.event.head_commit.message, '[auto-update]') }}
+    runs-on: ubuntu-22.04
+    name: postgresql migration script check
+    timeout-minutes: 2
+    steps:
+      - uses: actions/checkout@v4.2.2
+        with:
+          # Need full history + tags so `git describe` can find the previous
+          # release tag that the check script compares against.
+          fetch-depth: 0
+
+      - name: verify migration script for current CLOUDSYNC_VERSION
+        run: make postgres-check-migration
+
   postgres-test:
     if: ${{ !contains(github.event.head_commit.message, '[auto-update]') }}
+    needs: [postgres-migration-check]
     runs-on: ubuntu-22.04
     name: postgresql ${{ matrix.postgres_tag }} build + test
     timeout-minutes: 10
@@ -284,6 +300,7 @@ jobs:
 
   postgres-build:
     if: ${{ !contains(github.event.head_commit.message, '[auto-update]') }}
+    needs: [postgres-migration-check]
     runs-on: ${{ matrix.os }}
     name: postgresql${{ matrix.postgres_version }}-${{ matrix.name }}-${{ matrix.arch }} build
     timeout-minutes: 15

.gitignore

@@ -7,6 +7,11 @@ dist/
 /curl/src
 openssl/
 
+# Generated PostgreSQL extension files (produced from .in templates by
+# docker/Makefile.postgresql; version is derived from src/cloudsync.h)
+/docker/postgresql/cloudsync.control
+/src/postgresql/cloudsync--*.sql
+
 # Test artifacts
 /coverage
 unittest

docker/Makefile.postgresql

@@ -12,7 +12,12 @@ PG_INCLUDEDIR := $(shell $(PG_CONFIG) --includedir-server 2>/dev/null)
 
 # Extension metadata
 EXTENSION = cloudsync
-EXTVERSION = 1.0
+# Read the extension version from src/cloudsync.h (CLOUDSYNC_VERSION) so the
+# PG extension version stays in sync with the rest of the repo on every release.
+EXTVERSION := $(shell sed -n 's/^\#define CLOUDSYNC_VERSION[[:space:]]*"\([^"]*\)".*/\1/p' src/cloudsync.h)
+ifeq ($(strip $(EXTVERSION)),)
+$(error Could not read CLOUDSYNC_VERSION from src/cloudsync.h)
+endif
 
 # Detect OS for platform-specific settings
 ifneq ($(OS),Windows_NT)
@@ -82,17 +87,32 @@ endif
 PG_EXTENSION_SQL = src/postgresql/$(EXTENSION)--$(EXTVERSION).sql
 PG_EXTENSION_CONTROL = docker/postgresql/$(EXTENSION).control
 
+# Input templates (tracked). @EXTVERSION@ is substituted at build time.
+PG_EXTENSION_SQL_IN = src/postgresql/$(EXTENSION).sql.in
+PG_EXTENSION_CONTROL_IN = docker/postgresql/$(EXTENSION).control.in
+
+# Upgrade scripts (cloudsync--<from>--<to>.sql) are hand-written per release.
+PG_MIGRATIONS_DIR = src/postgresql/migrations
+PG_MIGRATION_SQLS = $(wildcard $(PG_MIGRATIONS_DIR)/$(EXTENSION)--*--*.sql)
+
 # ============================================================================
 # PostgreSQL Build Targets
 # ============================================================================
 
-.PHONY: postgres-check postgres-build postgres-install postgres-package postgres-clean postgres-test \
+.PHONY: postgres-check postgres-check-migration postgres-build postgres-install postgres-package postgres-clean postgres-test \
         postgres-docker-build postgres-docker-build-asan postgres-docker-run postgres-docker-run-asan postgres-docker-stop postgres-docker-rebuild \
         postgres-docker-debug-build postgres-docker-debug-run postgres-docker-debug-rebuild \
         postgres-docker-shell postgres-dev-rebuild postgres-help unittest-pg \
         postgres-supabase-build postgres-supabase-rebuild postgres-supabase-run-smoke-test \
         postgres-docker-run-smoke-test
 
+# Verify that a cloudsync--<prev>--<curr>.sql upgrade script exists for the
+# current CLOUDSYNC_VERSION in src/cloudsync.h. Release-blocking: a missing
+# upgrade script silently breaks ALTER EXTENSION cloudsync UPDATE for every
+# existing deployment. Runs in <1s; safe to call on every PR.
+postgres-check-migration:
+	@scripts/check-postgres-migration.sh
+
 # Check if PostgreSQL is available
 postgres-check:
 	@echo "Checking PostgreSQL installation..."
@@ -102,9 +122,19 @@ postgres-check:
 	@echo "Share directory: $(PG_SHAREDIR)"
 	@echo "Include directory: $(PG_INCLUDEDIR)"
 
+# Generate the versioned install script from the template
+$(PG_EXTENSION_SQL): $(PG_EXTENSION_SQL_IN) src/cloudsync.h
+	@echo "Generating $@ (version $(EXTVERSION))"
+	@sed 's/@EXTVERSION@/$(EXTVERSION)/g' $(PG_EXTENSION_SQL_IN) > $@
+
+# Generate the control file from the template
+$(PG_EXTENSION_CONTROL): $(PG_EXTENSION_CONTROL_IN) src/cloudsync.h
+	@echo "Generating $@ (version $(EXTVERSION))"
+	@sed 's/@EXTVERSION@/$(EXTVERSION)/g' $(PG_EXTENSION_CONTROL_IN) > $@
+
 # Build PostgreSQL extension
-postgres-build: postgres-check
-	@echo "Building PostgreSQL extension..."
+postgres-build: postgres-check $(PG_EXTENSION_SQL) $(PG_EXTENSION_CONTROL)
+	@echo "Building PostgreSQL extension (version $(EXTVERSION))..."
 	@echo "Compiling source files..."
 	@for src in $(PG_ALL_SRC); do \
 		echo "  CC $$src"; \
@@ -125,26 +155,37 @@ postgres-install: postgres-build
 	install -m 644 $(PG_EXTENSION_SQL) $(PG_SHAREDIR)/extension/
 	@echo "Installing control file to $(PG_SHAREDIR)/extension/"
 	install -m 644 $(PG_EXTENSION_CONTROL) $(PG_SHAREDIR)/extension/
+	@if [ -n "$(PG_MIGRATION_SQLS)" ]; then \
+		echo "Installing $(words $(PG_MIGRATION_SQLS)) migration script(s) to $(PG_SHAREDIR)/extension/"; \
+		install -m 644 $(PG_MIGRATION_SQLS) $(PG_SHAREDIR)/extension/; \
+	fi
 	@echo ""
 	@echo "Installation complete!"
 	@echo "To use the extension, run in psql:"
 	@echo "  CREATE EXTENSION $(EXTENSION);"
+	@echo "To upgrade an existing installation, run in psql:"
+	@echo "  ALTER EXTENSION $(EXTENSION) UPDATE;"
 
 # Package extension files for distribution
 PG_DIST_DIR = dist/postgresql
 
 postgres-package: postgres-build
-	@echo "Packaging PostgreSQL extension..."
+	@echo "Packaging PostgreSQL extension (version $(EXTVERSION))..."
 	@mkdir -p $(PG_DIST_DIR)
 	cp $(PG_EXTENSION_LIB) $(PG_DIST_DIR)/
 	cp $(PG_EXTENSION_SQL) $(PG_DIST_DIR)/
 	cp $(PG_EXTENSION_CONTROL) $(PG_DIST_DIR)/
+	@if [ -n "$(PG_MIGRATION_SQLS)" ]; then \
+		echo "Including $(words $(PG_MIGRATION_SQLS)) migration script(s)"; \
+		cp $(PG_MIGRATION_SQLS) $(PG_DIST_DIR)/; \
+	fi
 	@echo "Package ready in $(PG_DIST_DIR)/"
 
 # Clean PostgreSQL build artifacts
 postgres-clean:
 	@echo "Cleaning PostgreSQL build artifacts..."
 	rm -f $(PG_OBJS) $(PG_EXTENSION_LIB)
+	rm -f $(PG_EXTENSION_SQL) $(PG_EXTENSION_CONTROL)
 	@echo "Clean complete"
 
 # Test extension (requires running PostgreSQL)
@@ -314,7 +355,7 @@ postgres-supabase-build:
 	echo "Using base image: $$supabase_cli_image"; \
 	echo "Pulling fresh base image to avoid layer accumulation..."; \
 	docker pull "$$supabase_cli_image" 2>/dev/null || true; \
-	docker build --build-arg SUPABASE_POSTGRES_TAG="$(SUPABASE_POSTGRES_TAG)" -f "$$tmp_dockerfile" -t "$$supabase_cli_image" .; \
+	docker build --build-arg SUPABASE_POSTGRES_TAG="$(SUPABASE_POSTGRES_TAG)" --build-arg CLOUDSYNC_VERSION="$(EXTVERSION)" -f "$$tmp_dockerfile" -t "$$supabase_cli_image" .; \
 	rm -f "$$tmp_dockerfile"; \
 	echo "Build complete: $$supabase_cli_image"
 
@@ -361,6 +402,7 @@ postgres-help:
 	@echo ""
 	@echo "Build & Install:"
 	@echo "  postgres-check          - Verify PostgreSQL installation"
+	@echo "  postgres-check-migration - Verify a migration script exists for the current version"
 	@echo "  postgres-build          - Build extension (.so file)"
 	@echo "  postgres-install        - Install extension to PostgreSQL"
 	@echo "  postgres-clean          - Clean build artifacts"

docker/README.md

@@ -10,7 +10,7 @@ docker/
 │   ├── Dockerfile       # Custom PostgreSQL image
 │   ├── docker-compose.yml
 │   ├── init.sql        # CloudSync metadata tables
-│   └── cloudsync.control
+│   └── cloudsync.control.in   # template; cloudsync.control is generated at build time
 ```
 
 ## Option 1: Standalone PostgreSQL

docker/postgresql/Dockerfile.release

@@ -31,7 +31,7 @@ RUN case "${TARGETARCH}" in \
     mkdir -p /tmp/cloudsync && \
     tar -xzf /tmp/cloudsync.tar.gz -C /tmp/cloudsync && \
     install -m 755 /tmp/cloudsync/cloudsync.so "$(pg_config --pkglibdir)/" && \
-    install -m 644 /tmp/cloudsync/cloudsync--1.0.sql "$(pg_config --sharedir)/extension/" && \
+    install -m 644 /tmp/cloudsync/cloudsync--*.sql "$(pg_config --sharedir)/extension/" && \
     install -m 644 /tmp/cloudsync/cloudsync.control "$(pg_config --sharedir)/extension/" && \
     rm -rf /tmp/cloudsync /tmp/cloudsync.tar.gz && \
     apt-get purge -y curl && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*

docker/postgresql/Dockerfile.supabase

@@ -30,13 +30,21 @@ RUN if [ ! -x "$CLOUDSYNC_PG_CONFIG" ]; then \
 # Collect build artifacts (avoid installing into the Nix store)
 RUN mkdir -p /tmp/cloudsync-artifacts/lib /tmp/cloudsync-artifacts/extension && \
     cp /tmp/cloudsync/cloudsync.so /tmp/cloudsync-artifacts/lib/ && \
-    cp /tmp/cloudsync/src/postgresql/cloudsync--1.0.sql /tmp/cloudsync-artifacts/extension/ && \
-    cp /tmp/cloudsync/docker/postgresql/cloudsync.control /tmp/cloudsync-artifacts/extension/
+    cp /tmp/cloudsync/src/postgresql/cloudsync--*.sql /tmp/cloudsync-artifacts/extension/ && \
+    cp /tmp/cloudsync/docker/postgresql/cloudsync.control /tmp/cloudsync-artifacts/extension/ && \
+    # Include per-release upgrade scripts so ALTER EXTENSION ... UPDATE works
+    if ls /tmp/cloudsync/src/postgresql/migrations/cloudsync--*--*.sql 1>/dev/null 2>&1; then \
+        cp /tmp/cloudsync/src/postgresql/migrations/cloudsync--*--*.sql /tmp/cloudsync-artifacts/extension/; \
+    fi
 
 # Runtime image based on Supabase Postgres
 ARG SUPABASE_POSTGRES_TAG=17.6.1.071
 FROM public.ecr.aws/supabase/postgres:${SUPABASE_POSTGRES_TAG}
 
+# Extension version (derived from src/cloudsync.h by the Makefile and passed in
+# as a build arg); used only for the image label.
+ARG CLOUDSYNC_VERSION=unknown
+
 # Match builder pg_config path
 ENV CLOUDSYNC_PG_CONFIG=/root/.nix-profile/bin/pg_config
 
@@ -85,5 +93,5 @@ EXPOSE 5432
 WORKDIR /
 
 # Add label with extension version
-LABEL org.sqliteai.cloudsync.version="1.0" \
+LABEL org.sqliteai.cloudsync.version="${CLOUDSYNC_VERSION}" \
       org.sqliteai.cloudsync.description="PostgreSQL with CloudSync CRDT extension"

docker/postgresql/Dockerfile.supabase.release

@@ -42,10 +42,10 @@ RUN case "${TARGETARCH}" in \
     SHAREDIR_STD="/usr/share/postgresql" && \
     install -d "$PKGLIBDIR" "$SHAREDIR_PGCONFIG/extension" && \
     install -m 755 /tmp/cloudsync/cloudsync.so "$PKGLIBDIR/" && \
-    install -m 644 /tmp/cloudsync/cloudsync--1.0.sql /tmp/cloudsync/cloudsync.control "$SHAREDIR_PGCONFIG/extension/" && \
+    install -m 644 /tmp/cloudsync/cloudsync--*.sql /tmp/cloudsync/cloudsync.control "$SHAREDIR_PGCONFIG/extension/" && \
     if [ "$SHAREDIR_STD" != "$SHAREDIR_PGCONFIG" ]; then \
         install -d "$SHAREDIR_STD/extension" && \
-        install -m 644 /tmp/cloudsync/cloudsync--1.0.sql /tmp/cloudsync/cloudsync.control "$SHAREDIR_STD/extension/"; \
+        install -m 644 /tmp/cloudsync/cloudsync--*.sql /tmp/cloudsync/cloudsync.control "$SHAREDIR_STD/extension/"; \
     fi && \
     rm -rf /tmp/cloudsync /tmp/cloudsync.tar.gz && \
     apt-get purge -y curl && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*

docker/postgresql/cloudsync.control

@@ -0,0 +1,13 @@
+# CloudSync PostgreSQL Extension Control File
+#
+# Generated from cloudsync.control.in by docker/Makefile.postgresql.
+# Do not edit the generated file; edit the .in template instead.
+# The version below is read from CLOUDSYNC_VERSION in src/cloudsync.h.
+
+comment = 'CloudSync - CRDT-based multi-master database synchronization'
+default_version = '@EXTVERSION@'
+relocatable = true
+requires = ''
+superuser = false
+module_pathname = '$libdir/cloudsync'
+trusted = true

docker/postgresql/cloudsync.control.in

@@ -86,10 +86,10 @@ The `make postgres-supabase-build` command does the following:
 1. **Pulls the official Supabase Postgres base image** (e.g., `public.ecr.aws/supabase/postgres:15.8.1.085`) — this is Supabase's standard PostgreSQL image that ships with ~30 extensions pre-installed (PostGIS, pgvector, etc.)
 2. **Runs a multi-stage Docker build** using `docker/postgresql/Dockerfile.supabase`:
    - **Stage 1 (builder)**: Installs C build tools (`gcc`, `make`), copies the CloudSync source code (`src/`, `modules/`), and compiles `cloudsync.so` against Supabase's `pg_config`
-   - **Stage 2 (runtime)**: Starts from a clean Supabase Postgres image and copies in just three files:
+   - **Stage 2 (runtime)**: Starts from a clean Supabase Postgres image and copies in just three kinds of file:
      - `cloudsync.so` — the compiled extension binary
-     - `cloudsync.control` — tells PostgreSQL the extension's name and version
-     - `cloudsync--1.0.sql` — the SQL that defines all CloudSync functions
+     - `cloudsync.control` — tells PostgreSQL the extension's name and default version (generated at build time from `cloudsync.control.in`, with the version read from `src/cloudsync.h`)
+     - `cloudsync--<version>.sql` — the SQL that defines all CloudSync functions for the current release (e.g. `cloudsync--1.0.16.sql`), plus any `cloudsync--<from>--<to>.sql` upgrade scripts shipped under `src/postgresql/migrations/`
 3. **Tags the result** with the same name as the base image, so it's a drop-in replacement
 
 To find the correct tag, clone the Supabase repo and check:
@@ -118,7 +118,8 @@ Verify CloudSync is installed inside the image:
 ```bash
 docker run --rm <your-dockerhub-username>/supabase-postgres-cloudsync:15.8.1.085 \
   find / -name "cloudsync*" -type f 2>/dev/null
-# Should list cloudsync.so, cloudsync.control, and cloudsync--1.0.sql
+# Should list cloudsync.so, cloudsync.control, and cloudsync--<version>.sql
+# (plus any cloudsync--<from>--<to>.sql upgrade scripts)
 # in /nix/store/...-postgresql-and-plugins-15.8/ paths
 ```