build(supabase): build a custom supabase/postgres:17.6.1.071 docker image to be used from the supabase start stack

Author: andinux

docker/Makefile.postgresql

@@ -55,7 +55,9 @@ PG_EXTENSION_CONTROL = docker/postgresql/$(EXTENSION).control
 .PHONY: postgres-check postgres-build postgres-install 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-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
 
 # Check if PostgreSQL is available
 postgres-check:
@@ -119,6 +121,18 @@ postgres-test: postgres-install
 DOCKER_IMAGE = sqliteai/sqlite-sync-pg
 DOCKER_TAG ?= latest
 DOCKER_BUILD_ARGS ?=
+SUPABASE_CLI_IMAGE ?= $(shell docker ps --format '{{.Image}} {{.Names}}' | awk '/supabase_db/ {print $$1; exit}')
+SUPABASE_CLI_DOCKERFILE ?= docker/postgresql/Dockerfile.supabase
+SUPABASE_WORKDIR ?=
+SUPABASE_WORKDIR_ARG = $(if $(SUPABASE_WORKDIR),--workdir $(SUPABASE_WORKDIR),)
+SUPABASE_DB_HOST ?= 127.0.0.1
+SUPABASE_DB_PORT ?= 54322
+SUPABASE_DB_PASSWORD ?= postgres
+PG_DOCKER_DB_HOST ?= localhost
+PG_DOCKER_DB_PORT ?= 5432
+PG_DOCKER_DB_NAME ?= cloudsync_test
+PG_DOCKER_DB_USER ?= postgres
+PG_DOCKER_DB_PASSWORD ?= postgres
 
 # Build Docker image with pre-installed extension
 postgres-docker-build:
@@ -220,6 +234,58 @@ postgres-docker-shell:
 	@echo "Opening shell in PostgreSQL container..."
 	docker exec -it cloudsync-postgres bash
 
+# Build CloudSync into the Supabase CLI postgres image tag
+postgres-supabase-build:
+	@echo "Building CloudSync image for Supabase CLI..."
+	@if [ -z "$(SUPABASE_CLI_IMAGE)" ]; then \
+		echo "Error: Supabase CLI postgres image not found."; \
+		echo "Run 'supabase start' first, or set SUPABASE_CLI_IMAGE=public.ecr.aws/supabase/postgres:<tag>."; \
+		exit 1; \
+	fi
+	@tmp_dockerfile="$$(mktemp /tmp/cloudsync-supabase-cli.XXXXXX)"; \
+	src_dockerfile="$(SUPABASE_CLI_DOCKERFILE)"; \
+	if [ ! -f "$$src_dockerfile" ]; then \
+		if [ -f "docker/postgresql/Dockerfile.supabase" ]; then \
+			src_dockerfile="docker/postgresql/Dockerfile.supabase"; \
+		else \
+			echo "Error: Supabase Dockerfile not found (expected $$src_dockerfile)."; \
+			rm -f "$$tmp_dockerfile"; \
+			exit 1; \
+		fi; \
+	fi; \
+	sed -e "s|^FROM supabase/postgres:[^ ]*|FROM $(SUPABASE_CLI_IMAGE)|" \
+	    -e "s|^FROM public.ecr.aws/supabase/postgres:[^ ]*|FROM $(SUPABASE_CLI_IMAGE)|" \
+		"$$src_dockerfile" > "$$tmp_dockerfile"; \
+	if [ ! -s "$$tmp_dockerfile" ]; then \
+		echo "Error: Generated Dockerfile is empty."; \
+		rm -f "$$tmp_dockerfile"; \
+		exit 1; \
+	fi; \
+	echo "Using base image: $(SUPABASE_CLI_IMAGE)"; \
+	docker build -f "$$tmp_dockerfile" -t "$(SUPABASE_CLI_IMAGE)" .; \
+	rm -f "$$tmp_dockerfile"; \
+	echo "Build complete: $(SUPABASE_CLI_IMAGE)"
+
+# Rebuild CloudSync image and restart Supabase CLI stack
+postgres-supabase-rebuild: postgres-supabase-build
+	@echo "Restarting Supabase CLI stack..."
+	@command -v supabase >/dev/null 2>&1 || (echo "Error: supabase CLI not found in PATH." && exit 1)
+	@supabase stop $(SUPABASE_WORKDIR_ARG)
+	@supabase start $(SUPABASE_WORKDIR_ARG)
+	@echo "Supabase CLI stack restarted."
+
+# Run smoke test against Supabase CLI local database
+postgres-supabase-run-smoke-test:
+	@echo "Running Supabase CLI smoke test..."
+	@PGPASSWORD="$(SUPABASE_DB_PASSWORD)" psql postgresql://supabase_admin@$(SUPABASE_DB_HOST):$(SUPABASE_DB_PORT)/postgres -f docker/postgresql/smoke_test.sql
+	@echo "Smoke test completed."
+
+# Run smoke test against Docker standalone database
+postgres-docker-run-smoke-test:
+	@echo "Running Docker smoke test..."
+	@PGPASSWORD="$(PG_DOCKER_DB_PASSWORD)" psql postgresql://$(PG_DOCKER_DB_USER)@$(PG_DOCKER_DB_HOST):$(PG_DOCKER_DB_PORT)/$(PG_DOCKER_DB_NAME) -f docker/postgresql/smoke_test.sql
+	@echo "Smoke test completed."
+
 # ============================================================================
 # Development Workflow Targets
 # ============================================================================
@@ -259,6 +325,10 @@ postgres-help:
 	@echo "  postgres-docker-stop    - Stop PostgreSQL container"
 	@echo "  postgres-docker-rebuild - Rebuild image and restart container"
 	@echo "  postgres-docker-shell   - Open bash shell in running container"
+	@echo "  postgres-supabase-build     - Build CloudSync into Supabase CLI postgres image"
+	@echo "  postgres-supabase-rebuild   - Build CloudSync image and restart Supabase CLI stack"
+	@echo "  postgres-supabase-run-smoke-test - Run smoke test against Supabase CLI database"
+	@echo "  postgres-docker-run-smoke-test   - Run smoke test against Docker database"
 	@echo ""
 	@echo "Development:"
 	@echo "  postgres-dev-rebuild    - Rebuild extension in running container (fast)"

docker/README.md

@@ -11,8 +11,6 @@ docker/
 │   ├── docker-compose.yml
 │   ├── init.sql        # CloudSync metadata tables
 │   └── cloudsync.control
-└── supabase/           # Supabase integration
-    └── docker-compose.yml
 ```
 
 ## Option 1: Standalone PostgreSQL
@@ -105,78 +103,100 @@ Run and Debug -> `Attach to Postgres (gdb)` -> pick the PID from step 4 -> Conti
 6) Trigger your breakpoint  
 Run the SQL that exercises the code path. If `psql` blocks, the backend is paused at a breakpoint; continue in the debugger.
 
-## Option 2: Supabase Integration
+## Option 2: Supabase Integration (cli)
 
-Use this for testing CloudSync with Supabase's full stack (auth, realtime, storage, etc.).
+Use this when you're running `supabase start` and want CloudSync inside the local stack.
+The Supabase CLI uses a bundled PostgreSQL image (for example,
+`public.ecr.aws/supabase/postgres:17.6.1.071`). Build a matching image that
+includes CloudSync, then tag it with the same name so the CLI reuses it. This
+keeps your local Supabase stack intact (auth, realtime, storage, etc.) while
+enabling the extension in the CLI-managed Postgres container.
 
 ### Prerequisites
 
-Ensure you have both repositories cloned side-by-side:
-
-```bash
-parent-directory/
-├── supabase/
-└── sqlite-sync/
-```
+- Supabase CLI installed (`supabase start` works)
+- Docker running
 
 ### Setup
 
-1. Clone the Supabase repository:
+1. Initialize a Supabase project (use a separate workdir to keep generated files
+   out of the repo):
    ```bash
-   git clone --depth 1 https://github.com/supabase/supabase
-   cd supabase/docker
+   mkdir -p ~/supabase-local
+   supabase init --workdir ~/supabase-local
    ```
 
-2. Copy CloudSync override configuration:
+2. Start Supabase once so the CLI pulls the Postgres image:
    ```bash
-   cp ../../sqlite-sync/docker/supabase/docker-compose.yml docker-compose.override.yml
+   supabase start --workdir ~/supabase-local
    ```
 
-3. Copy the `.env` file and configure it:
+3. Build and tag a CloudSync image using the same tag as the running CLI stack:
    ```bash
-   cp .env.example .env
-   # Edit .env with your preferred settings
+   make postgres-supabase-build
+   ```
+   This auto-detects the running `supabase_db` image tag and rebuilds it with
+   CloudSync installed. If you need to override the tag, set
+   `SUPABASE_CLI_IMAGE=public.ecr.aws/supabase/postgres:<tag>`.
+   Example: 
+   ```bash
+   SUPABASE_CLI_IMAGE=public.ecr.aws/supabase/postgres:17.6.1.071 make postgres-supabase-build
    ```
 
-### Starting Supabase with CloudSync
+4. Restart the stack:
+   ```bash
+   supabase stop --workdir ~/supabase-local
+   supabase start --workdir ~/supabase-local
+   ```
+
+### Using the CloudSync Extension
 
-The override file will automatically build the custom PostgreSQL image:
+You can load the extension automatically from a migration, or enable it
+manually.
 
+Migration-based (notes for CLI): Supabase CLI migrations run as the `postgres`
+role, which cannot create C extensions by default. Use manual enable or grant
+`USAGE` on language `c` once, then migrations will work.
+
+If you still want a migration file, add:
 ```bash
-cd supabase/docker
-docker-compose up -d
+~/supabase-local/supabase/migrations/00000000000000_cloudsync.sql
+```
+Contents:
+```sql
+CREATE EXTENSION IF NOT EXISTS cloudsync;
 ```
 
-This will:
-- Build the CloudSync-enabled PostgreSQL image (first time only)
-- Start all Supabase services with CloudSync support
-- Initialize CloudSync metadata tables alongside Supabase tables
-
-Access Supabase Studio at http://localhost:3000
+Then either:
+- run `GRANT USAGE ON LANGUAGE c TO postgres;` once as `supabase_admin`, or
+- skip the migration and enable the extension manually after `supabase db reset`.
 
-### Using the CloudSync Extension
+Manual enable (no reset required):
 
-Connect to the database and enable the extension:
+Connect as the Supabase superuser (C extensions require superuser or language
+privileges), then enable the extension:
 
 ```bash
-psql postgresql://postgres:postgres@localhost:5432/postgres
+psql postgresql://supabase_admin:postgres@127.0.0.1:54322/postgres
 ```
 
 ```sql
 CREATE EXTENSION cloudsync;
-
--- Verify installation
 SELECT cloudsync_version();
 ```
 
+If you want to use the `postgres` role instead:
+
+```sql
+GRANT USAGE ON LANGUAGE c TO postgres;
+```
+
 ### Rebuilding After Changes
 
-If you modify the CloudSync source code, rebuild the image:
+If you modify the CloudSync source code, rebuild the CLI image and restart:
 
 ```bash
-cd supabase/docker
-docker-compose build db
-docker-compose up -d
+make postgres-supabase-rebuild SUPABASE_WORKDIR=~/supabase-local
 ```
 
 ## Development Workflow

docker/postgresql/Dockerfile.supabase

@@ -0,0 +1,86 @@
+# Build stage for CloudSync extension (match Supabase runtime)
+FROM public.ecr.aws/supabase/postgres:17.6.1.071 AS cloudsync-builder
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    ca-certificates \
+    git \
+    make \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create directory for extension source
+WORKDIR /tmp/cloudsync
+
+# Copy entire source tree (needed for includes and makefiles)
+COPY src/ ./src/
+COPY docker/ ./docker/
+COPY Makefile .
+
+# Build the CloudSync extension using Supabase's pg_config
+ENV CLOUDSYNC_PG_CONFIG=/root/.nix-profile/bin/pg_config
+RUN if [ ! -x "$CLOUDSYNC_PG_CONFIG" ]; then \
+        echo "Error: pg_config not found at $CLOUDSYNC_PG_CONFIG."; \
+        exit 1; \
+    fi; \
+    make postgres-build PG_CONFIG="$CLOUDSYNC_PG_CONFIG"
+
+# 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/
+
+# Runtime image based on Supabase Postgres
+FROM public.ecr.aws/supabase/postgres:17.6.1.071
+
+# Match builder pg_config path
+ENV CLOUDSYNC_PG_CONFIG=/root/.nix-profile/bin/pg_config
+
+# Install CloudSync extension artifacts
+COPY --from=cloudsync-builder /tmp/cloudsync-artifacts/ /tmp/cloudsync-artifacts/
+RUN if [ ! -x "$CLOUDSYNC_PG_CONFIG" ]; then \
+        echo "Error: pg_config not found at $CLOUDSYNC_PG_CONFIG."; \
+        exit 1; \
+    fi; \
+    PKGLIBDIR="`$CLOUDSYNC_PG_CONFIG --pkglibdir`"; \
+    # Supabase wraps postgres and overrides libdir via NIX_PGLIBDIR.
+    NIX_PGLIBDIR="`grep -E \"^export NIX_PGLIBDIR\" /usr/bin/postgres | sed -E \"s/.*'([^']+)'.*/\\1/\"`"; \
+    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-artifacts/lib/cloudsync.so "$PKGLIBDIR/" && \
+    install -m 644 /tmp/cloudsync-artifacts/extension/cloudsync* "$SHAREDIR_PGCONFIG/extension/"; \
+    if [ "$SHAREDIR_STD" != "$SHAREDIR_PGCONFIG" ]; then \
+        install -d "$SHAREDIR_STD/extension" && \
+        install -m 644 /tmp/cloudsync-artifacts/extension/cloudsync* "$SHAREDIR_STD/extension/"; \
+    fi
+
+# Verify installation
+RUN if [ ! -x "$CLOUDSYNC_PG_CONFIG" ]; then \
+        echo "Error: pg_config not found at $CLOUDSYNC_PG_CONFIG."; \
+        exit 1; \
+    fi; \
+    NIX_PGLIBDIR="`grep -E \"^export NIX_PGLIBDIR\" /usr/bin/postgres | sed -E \"s/.*'([^']+)'.*/\\1/\"`"; \
+    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 PostgreSQL port
+EXPOSE 5432
+
+# Return to root directory
+WORKDIR /
+
+# Add label with extension version
+LABEL org.sqliteai.cloudsync.version="1.0" \
+      org.sqliteai.cloudsync.description="PostgreSQL with CloudSync CRDT extension"