feat(postgresql): add multi-version PG builds and Docker Hub publishing

andinux · andinux · commit 7234216dce07 · 2026-03-31T18:31:44.000-06:00
Build PostgreSQL extension packages for both PG 17 and PG 15 in CI.
Add Dockerfile.release and Dockerfile.supabase.release for end-users
to create Docker images from pre-built GitHub release binaries without
cloning the repo. Add docker-publish CI job to push multi-arch images
to Docker Hub (sqlitecloud/sqlite-sync-postgres and
sqlitecloud/sqlite-sync-supabase) on release.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -277,7 +277,7 @@ jobs:
 
   postgres-build:
     runs-on: ${{ matrix.os }}
-    name: postgresql-${{ matrix.name }}-${{ matrix.arch }} build
+    name: postgresql${{ matrix.postgres_version }}-${{ matrix.name }}-${{ matrix.arch }} build
     timeout-minutes: 15
     strategy:
       fail-fast: false
@@ -286,15 +286,35 @@ jobs:
           - os: ubuntu-22.04
             arch: x86_64
             name: linux
+            postgres_version: '17'
+          - os: ubuntu-22.04
+            arch: x86_64
+            name: linux
+            postgres_version: '15'
+          - os: ubuntu-22.04-arm
+            arch: arm64
+            name: linux
+            postgres_version: '17'
           - os: ubuntu-22.04-arm
             arch: arm64
             name: linux
+            postgres_version: '15'
           - os: macos-15
             arch: arm64
             name: macos
+            postgres_version: '17'
+          - os: macos-15
+            arch: arm64
+            name: macos
+            postgres_version: '15'
           - os: macos-15
             arch: x86_64
             name: macos
+            postgres_version: '17'
+          - os: macos-15
+            arch: x86_64
+            name: macos
+            postgres_version: '15'
     steps:
 
       - uses: actions/checkout@v4.2.2
@@ -307,23 +327,23 @@ jobs:
           sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
           curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/postgresql.gpg
           sudo apt-get update
-          sudo apt-get install -y postgresql-server-dev-17
+          sudo apt-get install -y postgresql-server-dev-${{ matrix.postgres_version }}
 
       - name: macos install postgresql
         if: matrix.name == 'macos'
-        run: brew install postgresql@17 gettext
+        run: brew install postgresql@${{ matrix.postgres_version }} gettext
 
       - name: build and package postgresql extension (linux)
         if: matrix.name == 'linux'
-        run: make postgres-package
+        run: make postgres-package PG_CONFIG=/usr/lib/postgresql/${{ matrix.postgres_version }}/bin/pg_config
 
       - name: build and package postgresql extension (macos)
         if: matrix.name == 'macos'
-        run: make postgres-package PG_CONFIG=$(brew --prefix postgresql@17)/bin/pg_config PG_EXTRA_CFLAGS="-I$(brew --prefix gettext)/include ${{ matrix.arch == 'x86_64' && '-arch x86_64' || '' }}"
+        run: make postgres-package PG_CONFIG=$(brew --prefix postgresql@${{ matrix.postgres_version }})/bin/pg_config PG_EXTRA_CFLAGS="-I$(brew --prefix gettext)/include ${{ matrix.arch == 'x86_64' && '-arch x86_64' || '' }}"
 
       - uses: actions/upload-artifact@v4.6.2
         with:
-          name: cloudsync-postgresql-${{ matrix.name }}-${{ matrix.arch }}
+          name: cloudsync-postgresql${{ matrix.postgres_version }}-${{ matrix.name }}-${{ matrix.arch }}
           path: dist/postgresql/
           if-no-files-found: error
 
@@ -525,6 +545,8 @@ jobs:
             [**Expo**](https://www.npmjs.com/package/@sqliteai/sqlite-sync-expo): `npm install @sqliteai/sqlite-sync-expo`
             [**Android**](https://central.sonatype.com/artifact/ai.sqlite/sync): `ai.sqlite:sync:${{ steps.tag.outputs.version }}`
             [**Swift**](https://github.com/sqliteai/sqlite-sync#swift-package): [Installation Guide](https://github.com/sqliteai/sqlite-sync#swift-package)
+            [**Docker (PostgreSQL)**](https://hub.docker.com/r/sqlitecloud/sqlite-sync-postgres): `docker pull sqlitecloud/sqlite-sync-postgres:17` or `:15`
+            [**Docker (Supabase)**](https://hub.docker.com/r/sqlitecloud/sqlite-sync-supabase): `docker pull sqlitecloud/sqlite-sync-supabase:17` or `:15`
 
             ---
 
@@ -534,3 +556,89 @@ jobs:
             cloudsync-*-${{ steps.tag.outputs.version }}.*
             CloudSync-*-${{ steps.tag.outputs.version }}.*
           make_latest: true
+
+  docker-publish:
+    runs-on: ubuntu-22.04
+    name: docker ${{ matrix.image }} pg${{ matrix.pg_major }}
+    needs: [release]
+    if: github.ref == 'refs/heads/main'
+
+    env:
+      DOCKERHUB_ORG: sqlitecloud
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: sqlite-sync-postgres
+            pg_major: '17'
+            dockerfile: docker/postgresql/Dockerfile.release
+          - image: sqlite-sync-postgres
+            pg_major: '15'
+            dockerfile: docker/postgresql/Dockerfile.release
+          - image: sqlite-sync-supabase
+            pg_major: '17'
+            dockerfile: docker/postgresql/Dockerfile.supabase.release
+            supabase_tag: '17.6.1.071'
+          - image: sqlite-sync-supabase
+            pg_major: '15'
+            dockerfile: docker/postgresql/Dockerfile.supabase.release
+            supabase_tag: '15.8.1.085'
+
+    steps:
+
+      - uses: actions/checkout@v4.2.2
+        with:
+          submodules: true
+
+      - name: get cloudsync version
+        id: version
+        run: echo "version=$(make version)" >> $GITHUB_OUTPUT
+
+      - uses: docker/setup-qemu-action@v3
+
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: set docker tags and build args (standalone)
+        if: matrix.image == 'sqlite-sync-postgres'
+        id: standalone
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          PG=${{ matrix.pg_major }}
+          IMAGE=${{ env.DOCKERHUB_ORG }}/${{ matrix.image }}
+          {
+            echo "tags=${IMAGE}:${PG},${IMAGE}:${PG}-${VERSION}"
+            echo "build_args<<EOF"
+            echo "POSTGRES_TAG=${PG}"
+            echo "CLOUDSYNC_VERSION=${VERSION}"
+            echo "EOF"
+          } >> $GITHUB_OUTPUT
+
+      - name: set docker tags and build args (supabase)
+        if: matrix.image == 'sqlite-sync-supabase'
+        id: supabase
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          IMAGE=${{ env.DOCKERHUB_ORG }}/${{ matrix.image }}
+          SUPABASE_TAG=${{ matrix.supabase_tag }}
+          {
+            echo "tags=${IMAGE}:${{ matrix.pg_major }},${IMAGE}:${{ matrix.pg_major }}-${VERSION},${IMAGE}:${SUPABASE_TAG}"
+            echo "build_args<<EOF"
+            echo "SUPABASE_POSTGRES_TAG=${SUPABASE_TAG}"
+            echo "CLOUDSYNC_VERSION=${VERSION}"
+            echo "EOF"
+          } >> $GITHUB_OUTPUT
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ${{ matrix.dockerfile }}
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ matrix.image == 'sqlite-sync-postgres' && steps.standalone.outputs.tags || steps.supabase.outputs.tags }}
+          build-args: ${{ matrix.image == 'sqlite-sync-postgres' && steps.standalone.outputs.build_args || steps.supabase.outputs.build_args }}
diff --git a/docker/postgresql/Dockerfile.release b/docker/postgresql/Dockerfile.release
@@ -0,0 +1,50 @@
+# PostgreSQL with pre-compiled CloudSync (sqlite-sync) extension
+#
+# Usage:
+#   docker build \
+#     --build-arg POSTGRES_TAG=17 \
+#     --build-arg CLOUDSYNC_VERSION=1.0.1 \
+#     -t sqlite-sync-postgres:17 \
+#     -f docker/postgresql/Dockerfile.release .
+#
+# Or pull the pre-built image from Docker Hub:
+#   docker pull sqlitecloud/sqlite-sync-postgres:17
+#
+
+ARG POSTGRES_TAG=17
+FROM postgres:${POSTGRES_TAG}
+
+ARG CLOUDSYNC_VERSION
+ARG TARGETARCH
+
+# Map Docker platform arch to artifact arch
+RUN case "${TARGETARCH}" in \
+      amd64) ARCH="x86_64" ;; \
+      arm64) ARCH="arm64" ;; \
+      *) echo "Unsupported architecture: ${TARGETARCH}" && exit 1 ;; \
+    esac && \
+    apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && \
+    ASSET="cloudsync-postgresql${PG_MAJOR}-linux-${ARCH}-${CLOUDSYNC_VERSION}.tar.gz" && \
+    URL="https://github.com/sqliteai/sqlite-sync/releases/download/${CLOUDSYNC_VERSION}/${ASSET}" && \
+    echo "Downloading ${URL}" && \
+    curl -fSL "${URL}" -o /tmp/cloudsync.tar.gz && \
+    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.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/*
+
+# Verify installation
+RUN ls -la "$(pg_config --pkglibdir)/cloudsync.so" && \
+    ls -la "$(pg_config --sharedir)/extension/cloudsync"* && \
+    echo "CloudSync extension installed successfully"
+
+# Copy initialization script (auto-creates the extension on first start)
+COPY docker/postgresql/init.sql /docker-entrypoint-initdb.d/
+
+EXPOSE 5432
+
+LABEL org.sqliteai.cloudsync.description="PostgreSQL with CloudSync CRDT extension" \
+      org.opencontainers.image.source="https://github.com/sqliteai/sqlite-sync"
diff --git a/docker/postgresql/Dockerfile.supabase.release b/docker/postgresql/Dockerfile.supabase.release
@@ -0,0 +1,72 @@
+# Supabase PostgreSQL with pre-compiled CloudSync (sqlite-sync) extension
+#
+# Usage:
+#   docker build \
+#     --build-arg SUPABASE_POSTGRES_TAG=15.8.1.085 \
+#     --build-arg CLOUDSYNC_VERSION=1.0.1 \
+#     -f docker/postgresql/Dockerfile.supabase.release \
+#     -t my-cloudsync-supabase-postgres .
+#
+# Or pull the pre-built image from Docker Hub:
+#   docker pull sqlitecloud/sqlite-sync-supabase:15
+#
+
+ARG SUPABASE_POSTGRES_TAG=17.6.1.071
+FROM public.ecr.aws/supabase/postgres:${SUPABASE_POSTGRES_TAG}
+
+ARG CLOUDSYNC_VERSION
+ARG TARGETARCH
+
+ENV CLOUDSYNC_PG_CONFIG=/root/.nix-profile/bin/pg_config
+
+# Download pre-compiled extension and install into Supabase's Nix layout
+RUN case "${TARGETARCH}" in \
+      amd64) ARCH="x86_64" ;; \
+      arm64) ARCH="arm64" ;; \
+      *) echo "Unsupported architecture: ${TARGETARCH}" && exit 1 ;; \
+    esac && \
+    # Derive PG major version from pg_config
+    PG_MAJOR=$(${CLOUDSYNC_PG_CONFIG} --version | sed 's/[^0-9]*//' | cut -d. -f1) && \
+    apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && \
+    ASSET="cloudsync-postgresql${PG_MAJOR}-linux-${ARCH}-${CLOUDSYNC_VERSION}.tar.gz" && \
+    URL="https://github.com/sqliteai/sqlite-sync/releases/download/${CLOUDSYNC_VERSION}/${ASSET}" && \
+    echo "Downloading ${URL}" && \
+    curl -fSL "${URL}" -o /tmp/cloudsync.tar.gz && \
+    mkdir -p /tmp/cloudsync && \
+    tar -xzf /tmp/cloudsync.tar.gz -C /tmp/cloudsync && \
+    # Resolve Supabase's Nix library path
+    PKGLIBDIR="$(${CLOUDSYNC_PG_CONFIG} --pkglibdir)" && \
+    NIX_PGLIBDIR="$(grep -E '^export NIX_PGLIBDIR' /usr/bin/postgres | sed -E "s/.*'([^']+)'.*/\1/" || true)" && \
+    if [ -n "$NIX_PGLIBDIR" ]; then PKGLIBDIR="$NIX_PGLIBDIR"; fi && \
+    SHAREDIR_PGCONFIG="$(${CLOUDSYNC_PG_CONFIG} --sharedir)" && \
+    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/" && \
+    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/"; \
+    fi && \
+    rm -rf /tmp/cloudsync /tmp/cloudsync.tar.gz && \
+    apt-get purge -y curl && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*
+
+# Verify installation
+RUN NIX_PGLIBDIR="$(grep -E '^export NIX_PGLIBDIR' /usr/bin/postgres | sed -E "s/.*'([^']+)'.*/\1/" || true)" && \
+    echo "Verifying CloudSync extension installation..." && \
+    if [ -n "$NIX_PGLIBDIR" ]; then \
+        ls -la "$NIX_PGLIBDIR/cloudsync.so"; \
+    else \
+        ls -la "$(${CLOUDSYNC_PG_CONFIG} --pkglibdir)/cloudsync.so"; \
+    fi && \
+    ls -la "$(${CLOUDSYNC_PG_CONFIG} --sharedir)/extension/cloudsync"* && \
+    if [ -d "/usr/share/postgresql/extension" ]; then \
+        ls -la /usr/share/postgresql/extension/cloudsync*; \
+    fi && \
+    echo "CloudSync extension installed successfully"
+
+EXPOSE 5432
+
+WORKDIR /
+
+LABEL org.sqliteai.cloudsync.description="Supabase PostgreSQL with CloudSync CRDT extension" \
+      org.opencontainers.image.source="https://github.com/sqliteai/sqlite-sync"
diff --git a/docs/TODO.md b/docs/TODO.md
@@ -2,46 +2,48 @@
 
 ## CI / Releases
 
-- [ ] **Compile PostgreSQL extension against both PG15 and PG17**
-  - The `postgres-build` CI job currently hardcodes PG17 (`postgresql-server-dev-17`)
-  - Add a matrix over `['15', '17']` matching the existing `postgres-test` job
-  - Name artifacts with the PG version: `cloudsync-postgresql-linux-x86_64-pg17-1.0.0.tar.gz`
-  - Files compiled against one major PG version will not load on another
-  - **This is a prerequisite for the standard Dockerfile improvement below**
+- [x] **Compile PostgreSQL extension against both PG15 and PG17**
+  - The `postgres-build` CI job now builds for both PG 15 and PG 17 via matrix
+  - Artifacts are named with the PG version: `cloudsync-postgresql17-linux-x86_64`, `cloudsync-postgresql15-linux-arm64`, etc.
 
 ## With Docker
 
-Decision: do not publish to a registry. Instead provide Dockerfiles users build themselves.
+### Standard PostgreSQL (`Dockerfile.release`)
 
-### Standard PostgreSQL (`Dockerfile`)
-
-- [ ] **Update `Dockerfile` to download pre-compiled extension from GitHub releases instead of building from source**
-  - Currently copies the full source tree and compiles inside the container
-  - New approach: accept `--build-arg CLOUDSYNC_VERSION=1.0.0`, fetch the matching tarball from GitHub releases at build time
-  - Dockerfile detects PG major version and architecture automatically to pick the right tarball
+- [x] **`Dockerfile.release` downloads pre-compiled extension from GitHub releases**
+  - Accepts `--build-arg POSTGRES_TAG=17` and `--build-arg CLOUDSYNC_VERSION=1.0.0`
+  - Detects PG major version (`PG_MAJOR`) and architecture (`TARGETARCH`) automatically to pick the right tarball
   - User only needs the Dockerfile — no full repo clone required
-  - Example: `docker build --build-arg POSTGRES_TAG=17 --build-arg CLOUDSYNC_VERSION=1.0.0 -t my-cloudsync-postgres .`
-  - **Blocked by:** release artifacts having PG version in the filename (see CI/Releases above)
-  - **User flow (fresh):** Build image → use in `docker-compose.yml` → `CREATE EXTENSION cloudsync`
-  - **User flow (existing):** Build image → swap in `docker-compose.yml` → restart → `CREATE EXTENSION cloudsync`
-
-### Supabase (`Dockerfile.supabase`)
-
-- Supabase uses a non-standard Nix-based PostgreSQL build — pre-compiled `.so` from releases will not work, must always compile from source
-- [ ] **Update `Dockerfile.supabase` to download source tarball from GitHub releases instead of using `COPY src/`**
-  - Currently uses `COPY src/`, `COPY modules/`, `COPY Makefile` — requires the user to run `docker build` from inside the cloned repo
-  - New approach: accept `--build-arg CLOUDSYNC_VERSION=1.0.0`, fetch the source tarball from GitHub releases at build time and compile inside the container
-  - GitHub automatically generates source tarballs for every release (`Source code (tar.gz)`)
-  - User only needs the `Dockerfile.supabase` — no repo clone required
-  - Example: `docker build -f Dockerfile.supabase --build-arg SUPABASE_POSTGRES_TAG=15.8.1.085 --build-arg CLOUDSYNC_VERSION=1.0.0 -t my-cloudsync-supabase-postgres .`
-  - **User flow (fresh):** Build image → replace default Supabase postgres image in `docker-compose.yml` → `CREATE EXTENSION cloudsync`
-  - **User flow (existing):** Build image → follow Supabase's update guide to swap the postgres image → `CREATE EXTENSION cloudsync`
+  - Example: `docker build --build-arg POSTGRES_TAG=17 --build-arg CLOUDSYNC_VERSION=1.0.0 -f docker/postgresql/Dockerfile.release -t my-cloudsync-postgres .`
+
+- [x] **Pre-built Docker images published to Docker Hub on release**
+  - `sqlitecloud/sqlite-sync-postgres:17`, `:15`, `:17-<version>`, `:15-<version>`
+  - Multi-arch: `linux/amd64` + `linux/arm64`
+  - Users can just `docker pull` — no build needed
+
+### Supabase
+
+Two Dockerfiles:
+- `Dockerfile.supabase` — builds from source (for development and testing, requires repo clone)
+- `Dockerfile.supabase.release` — downloads pre-built extension from GitHub releases (for end-users, no repo clone needed)
+
+- [x] **Pre-built Supabase Docker images published to Docker Hub on release**
+  - `sqlitecloud/sqlite-sync-supabase:17`, `:15`, `:17-<version>`, `:15-<version>`
+  - Also tagged with the exact Supabase base image version (`:17.6.1.071`, `:15.8.1.085`)
+  - Multi-arch: `linux/amd64` + `linux/arm64`
+  - Users can reference the image directly in their Supabase `docker-compose.yml`
+
+- [x] **`Dockerfile.supabase.release` downloads pre-compiled extension from GitHub releases**
+  - Pre-built binaries are ABI-compatible with Supabase's Nix-based PostgreSQL (same PG major version)
+  - Handles Supabase's non-standard Nix paths (`NIX_PGLIBDIR`, dual share directories)
+  - Accepts `--build-arg SUPABASE_POSTGRES_TAG=15.8.1.085` and `--build-arg CLOUDSYNC_VERSION=1.0.0`
+  - Example: `docker build -f docker/postgresql/Dockerfile.supabase.release --build-arg SUPABASE_POSTGRES_TAG=15.8.1.085 --build-arg CLOUDSYNC_VERSION=1.0.0 -t my-cloudsync-supabase .`
 
 ## Without Docker
 
 For users with an existing native PostgreSQL installation (bare metal or VM, not containerized).
 
-- [ ] **Ensure release tarballs are usable for native installs**
+- [x] **Release tarballs are usable for native installs**
   - User downloads the right tarball from GitHub releases (correct OS + arch + PG version)
   - Extracts 3 files: `cloudsync.so`, `cloudsync--1.0.sql`, `cloudsync.control`
   - Copies them to the PostgreSQL extension directories:
@@ -50,4 +52,3 @@ For users with an existing native PostgreSQL installation (bare metal or VM, not
     cp cloudsync--1.0.sql cloudsync.control $(pg_config --sharedir)/extension/
     ```
   - Runs `CREATE EXTENSION cloudsync;` — done, no Docker or compiler needed
-  - **Blocked by:** release artifacts having PG version in the filename (see CI/Releases above)
