feat(postgres): versioned extension upgrades with CI-gated migration scripts (#45)

Make the PostgreSQL extension version derive from CLOUDSYNC_VERSION
(MAJOR.MINOR), ship per-release upgrade scripts under
src/postgresql/migrations/ so existing deployments can run
ALTER EXTENSION cloudsync UPDATE, and add a CI check that fails when
a release is missing its migration script or accidentally drifts the
SQL surface in a PATCH release.

Before this change, default_version was pinned to '1.0' across all
17 releases, no upgrade scripts existed, and a SQL-changing release
could silently break users by leaving pg_extension.extversion stale
while cloudsync.so loaded new bindings.

User-facing impact:
- PATCH (e.g. 1.0.16 → 1.0.17): swap the binary, no ALTER EXTENSION
- MINOR/MAJOR (e.g. 1.0.x → 1.1.0): one ALTER EXTENSION cloudsync UPDATE per database

Documented in README "Versioning", both PG quickstarts ("Upgrading
a later release"), and src/postgresql/migrations/README.md.

No CLOUDSYNC_VERSION bump in this PR — pure build/CI infrastructure.

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

README.md

@@ -212,6 +212,12 @@ Part of the **[SQLite AI](https://sqlite.ai)** ecosystem:
 | **[SQLite-JS](https://github.com/sqliteai/sqlite-js)** | Custom SQLite functions in JavaScript |
 | **[Liteparser](https://github.com/sqliteai/liteparser)** | Fully compliant SQLite SQL parser |
 
+## Versioning
+
+This project follows [semver](https://semver.org/). The single source of truth is `CLOUDSYNC_VERSION` in `src/cloudsync.h`; all packaged artifacts (NPM, Maven, pub.dev, Swift, Docker, native tarballs) inherit this version. PATCH releases never alter the exposed API — they ship bug fixes, performance improvements, and internal changes only.
+
+The PostgreSQL extension differs only in how it surfaces the version: its catalog version (`default_version` / `installed_version`) exposes `MAJOR.MINOR` only, so PATCH releases are transparent binary upgrades and only MINOR/MAJOR releases need `ALTER EXTENSION cloudsync UPDATE`. The `cloudsync_version()` SQL function always reports the full semver of the loaded `.so`. See the [PostgreSQL upgrade docs](docs/postgresql/quickstarts/postgres.md#upgrading-a-later-release) for the user-facing procedure.
+
 ## License
 
 This project is licensed under the [Elastic License 2.0](./LICENSE.md). For production or managed service use, [contact SQLite Cloud, Inc](mailto:info@sqlitecloud.io) for a commercial license.

docker/Makefile.postgresql

@@ -12,7 +12,17 @@ PG_INCLUDEDIR := $(shell $(PG_CONFIG) --includedir-server 2>/dev/null)
 
 # Extension metadata
 EXTENSION = cloudsync
-EXTVERSION = 1.0
+# Read the binary version (full semver) from src/cloudsync.h, and derive
+# EXTVERSION as just MAJOR.MINOR. Rationale: PATCH bumps are binary-only
+# (no SQL surface change, no ALTER EXTENSION UPDATE needed); MINOR/MAJOR bumps
+# are the SQL-surface-changing ones that require a per-release upgrade script.
+# cloudsync_version() in the .so still reports the full semver for debugging.
+#
+# Recursive (=) rather than immediate (:=) assignment so the shell calls only
+# fire when a PG-related target actually references these variables. Non-PG
+# targets parse this included makefile without invoking sed/cut at all.
+CLOUDSYNC_VERSION_FULL = $(shell sed -n 's/^\#define CLOUDSYNC_VERSION[[:space:]]*"\([^"]*\)".*/\1/p' src/cloudsync.h)
+EXTVERSION             = $(shell echo '$(CLOUDSYNC_VERSION_FULL)' | cut -d. -f1-2)
 
 # Detect OS for platform-specific settings
 ifneq ($(OS),Windows_NT)
@@ -82,29 +92,61 @@ 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-generate-files 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..."
 	@which $(PG_CONFIG) > /dev/null || (echo "Error: pg_config not found. Install postgresql-server-dev." && exit 1)
+	@[ -n "$(CLOUDSYNC_VERSION_FULL)" ] || (echo "Error: could not read CLOUDSYNC_VERSION from src/cloudsync.h" && exit 1)
+	@[ -n "$(EXTVERSION)" ] || (echo "Error: could not derive MAJOR.MINOR EXTVERSION from CLOUDSYNC_VERSION '$(CLOUDSYNC_VERSION_FULL)'" && exit 1)
 	@echo "PostgreSQL version: $$($(PG_CONFIG) --version)"
+	@echo "CloudSync version : $(CLOUDSYNC_VERSION_FULL) (extension version $(EXTVERSION))"
 	@echo "Extension directory: $(PG_PKGLIBDIR)"
 	@echo "Share directory: $(PG_SHAREDIR)"
 	@echo "Include directory: $(PG_INCLUDEDIR)"
 
+# Render the versioned .sql install script and .control file from their .in
+# templates. This is a phony target (rather than file rules keyed on
+# $(PG_EXTENSION_SQL) / $(PG_EXTENSION_CONTROL)) so that $(EXTVERSION) never
+# appears in a rule's target or prerequisite position — those expansions
+# happen at parse time and would force sed/cut to run on every `make`
+# invocation, including for non-PG goals. Here, the references live inside
+# the recipe body and are only evaluated when this target actually fires.
+# Writes via a .tmp + atomic mv so a failed sed can't leave a half-rendered
+# output file in the extension share dir.
+postgres-generate-files: postgres-check
+	@echo "Rendering extension files at version $(EXTVERSION) (binary $(CLOUDSYNC_VERSION_FULL))"
+	@sed 's/@EXTVERSION@/$(EXTVERSION)/g' $(PG_EXTENSION_SQL_IN)     > $(PG_EXTENSION_SQL).tmp     && mv $(PG_EXTENSION_SQL).tmp     $(PG_EXTENSION_SQL)
+	@sed 's/@EXTVERSION@/$(EXTVERSION)/g' $(PG_EXTENSION_CONTROL_IN) > $(PG_EXTENSION_CONTROL).tmp && mv $(PG_EXTENSION_CONTROL).tmp $(PG_EXTENSION_CONTROL)
+
 # Build PostgreSQL extension
-postgres-build: postgres-check
-	@echo "Building PostgreSQL extension..."
+postgres-build: postgres-generate-files
+	@echo "Building PostgreSQL extension (version $(EXTVERSION))..."
 	@echo "Compiling source files..."
 	@for src in $(PG_ALL_SRC); do \
 		echo "  CC $$src"; \
@@ -125,26 +167,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 +367,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="$(CLOUDSYNC_VERSION_FULL)" -f "$$tmp_dockerfile" -t "$$supabase_cli_image" .; \
 	rm -f "$$tmp_dockerfile"; \
 	echo "Build complete: $$supabase_cli_image"
 
@@ -361,6 +414,8 @@ 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-generate-files  - Render cloudsync.control and cloudsync--<ext>.sql from templates"
 	@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