feat: add portable CLI binaries for multi-platform Supabase CLI distribution (#2033)

This commit implements portable, self-contained PostgreSQL binaries for
the Supabase CLI across macOS (ARM), Linux (x64), and Linux (ARM64),
along with automated CI/CD workflows for building and releasing these
artifacts.

The Supabase CLI needs to ship PostgreSQL binaries that work on user
machines without requiring Nix or other system dependencies. This means
extracting the actual binaries from Nix's wrapper scripts, bundling all
necessary shared libraries, and patching them to use relative paths
instead of hardcoded Nix store paths.

A `variant` parameter was added to the postgres build pipeline to
distinguish between "full" (all extensions) and "cli" (minimal
extensions for Supabase CLI). The `cliExtensions` list contains 6
extensions required for running Supabase migrations: supautils,
pg_graphql, pgsodium, supabase_vault, pg_net, and pg_cron. Built-in
extensions (uuid-ossp, pgcrypto, pg_stat_statements) are included
automatically with PostgreSQL. `makeOurPostgresPkgs`/`makePostgresBin`
were modified to accept this parameter. A new `psql_17_cli` package is
created using `variant = "cli"`, while the full extension set is
preserved for base packages (`psql_15`, `psql_17`, `psql_orioledb-17`).

The portable CLI variant (`psql_17_cli_portable`) includes 6 extensions
for migration support while maintaining a significantly smaller size
than the full build. The implementation in
`nix/packages/postgres-portable.nix` extracts binaries from
`psql_17_cli` using a `resolve_binary()` function that follows wrapper
layers to find the actual ELF/Mach-O binaries behind Nix's environment
setup scripts.

All Nix-provided libraries (ICU, readline, zlib, etc.) are bundled while
excluding system libraries (`libc`, `libpthread`, `libm`, `glibc`,
`libdl`) that must come from the host. This distinction is critical:
Linux bundles must exclude glibc due to kernel ABI dependencies, while
macOS can include more libs due to its different linking model.
Dependency resolution runs multiple passes to catch transitive deps
(e.g., ICU → charset → etc.).

Platform-specific patching is applied: Linux binaries use the system
interpreter (`/lib64/ld-linux-*.so.2`) and `$ORIGIN`-based RPATHs, while
macOS binaries use `@rpath` with `@executable_path`. Wrapper scripts set
`LD_LIBRARY_PATH` (Linux) or `DYLD_LIBRARY_PATH` (macOS) to find bundled
libraries. The bundle includes PostgreSQL config templates
(`postgresql.conf`, `pg_hba.conf`, `pg_ident.conf`) tailored for CLI
usage with minimal local dev settings, plus the complete Supabase
migration script (`migrate.sh`) with all init-scripts and migration SQL
files (55 files, 236KB).

A Docker-style initialization script (`supabase-postgres-init.sh`)
provides one-command database setup via environment variables
(`POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `PGDATA`).

To achieve true portability, a `portable` parameter was added to the
PostgreSQL build in `nix/postgresql/generic.nix`. When `portable =
true`, three critical hardcoded paths are excluded from the build:

1. `--with-system-tzdata` is removed from configure flags, allowing
   PostgreSQL to use bundled timezone data from the `share/` directory
   instead of a hardcoded `/nix/store/.../tzdata` path;

2. the `locale-binary-path.patch` is excluded, so PostgreSQL calls
   `locale -a` from system PATH rather than using an absolute path to
   glibc's locale command;

3. the `postFixup` initdb wrapper is disabled to avoid hardcoding glibc
   paths. The `portable` parameter defaults to `false` in
   `nix/postgresql/default.nix` but is overridden to `true` for the CLI
   variant in `nix/packages/postgres.nix` using `.override { portable =
   true; }`.

This ensures standard PostgreSQL builds remain unchanged while the CLI
variant produces truly portable binaries without any `/nix/store`
references.

A GitHub Actions workflow builds portable binaries across all three
platforms using a matrix strategy. Each build runs automated portability
checks that verify no `/nix/store` references remain, validate RPATH
configuration, confirm transitive dependencies are bundled, ensure
system libraries are NOT bundled, and check wrapper scripts contain
proper library path setup. Post-build testing validates binaries work
without Nix (`postgres --version`, `psql --version`). On tagged releases
(`v*-cli`), the workflow creates GitHub releases with tarball artifacts
and checksums.

The test infrastructure needed significant changes to support variants
with different extension sets. An `isCliVariant` parameter was added to
`makeCheckHarness`, and the hardcoded `shared_preload_libraries` list in
`postgresql.conf.in` was replaced with a `@PRELOAD_LIBRARIES@`
placeholder. A `generatePreloadLibs` script now parses `receipt.json` at
test time and dynamically builds the preload list based on available
extensions, removing the previous timescaledb removal hack for OrioleDB.

Author: LGUG2Z

.github/workflows/cli-release.yml

@@ -0,0 +1,9 @@
+# Supabase CLI Host-Based Authentication
+# TYPE  DATABASE        USER            ADDRESS                 METHOD
+
+# Local connections
+local   all             all                                     scram-sha-256
+# IPv4 local connections
+host    all             all             127.0.0.1/32            scram-sha-256
+# IPv6 local connections
+host    all             all             ::1/128                 scram-sha-256

nix/checks.nix

@@ -0,0 +1,2 @@
+# Supabase CLI Ident Map Configuration
+# MAPNAME       SYSTEM-USERNAME         PG-USERNAME

nix/packages/cli-config/pg_hba.conf.template

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+set -euo pipefail
+
+KEY_FILE="${PGSODIUM_KEY_FILE:-$HOME/.supabase/pgsodium_root.key}"
+KEY_DIR="$(dirname "$KEY_FILE")"
+
+# Create directory if it doesn't exist
+mkdir -p "$KEY_DIR"
+
+if [[ ! -f "${KEY_FILE}" ]]; then
+    head -c 32 /dev/urandom | od -A n -t x1 | tr -d ' \n' > "${KEY_FILE}"
+fi
+cat "$KEY_FILE"

nix/packages/cli-config/pg_ident.conf.template

@@ -0,0 +1,43 @@
+# Supabase CLI PostgreSQL Configuration
+# Minimal configuration for local development
+
+# Connection Settings
+listen_addresses = '127.0.0.1'
+port = 54322
+max_connections = 100
+unix_socket_directories = '/tmp'
+
+# Memory Settings (conservative for local dev)
+shared_buffers = 128MB
+effective_cache_size = 256MB
+work_mem = 4MB
+maintenance_work_mem = 64MB
+
+# Write Ahead Log
+wal_level = replica
+max_wal_senders = 0
+
+# Logging
+log_destination = 'stderr'
+logging_collector = off
+log_min_messages = warning
+log_min_error_statement = error
+
+# Locale
+lc_messages = 'C'
+lc_monetary = 'C'
+lc_numeric = 'C'
+lc_time = 'C'
+
+# Extensions
+shared_preload_libraries = 'pg_stat_statements, pg_cron, pg_net, pgsodium, supabase_vault, supautils'
+
+# pgsodium and vault configuration
+# Set the path to your pgsodium_getkey.sh script
+# Default location when using portable bundle: share/supabase-cli/config/pgsodium_getkey.sh
+#pgsodium.getkey_script = '/path/to/pgsodium_getkey.sh'
+#vault.getkey_script = '/path/to/pgsodium_getkey.sh'
+
+# Supautils configuration
+supautils.reserved_roles = 'supabase_admin,supabase_auth_admin,supabase_storage_admin,supabase_read_only_user,supabase_replication_admin,supabase_realtime_admin,supabase_functions_admin'
+supautils.reserved_memberships = 'pg_read_server_files,pg_write_server_files,pg_execute_server_program'

nix/packages/cli-config/pgsodium_getkey.sh

@@ -0,0 +1,191 @@
+#!/bin/bash
+set -Eeo pipefail
+
+# Supabase PostgreSQL Initialization Script
+# Similar to docker-entrypoint.sh from official postgres image
+# Handles database initialization, password setup, and configuration
+
+# Default values
+PGDATA="${PGDATA:-./data}"
+POSTGRES_USER="${POSTGRES_USER:-supabase_admin}"
+POSTGRES_PASSWORD="${POSTGRES_PASSWORD:-postgres}"
+POSTGRES_DB="${POSTGRES_DB:-postgres}"
+
+# Get the directory where this script lives
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Script is at share/supabase-cli/bin/, so go up 3 levels to reach bundle root
+BUNDLE_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+PGBIN="$BUNDLE_DIR/bin"
+
+# Logging functions
+postgres_log() {
+    local type="$1"; shift
+    printf '%s [%s] %s\n' "$(date '+%Y-%m-%d %H:%M:%S')" "$type" "$*"
+}
+
+postgres_note() {
+    postgres_log Note "$@"
+}
+
+postgres_error() {
+    postgres_log ERROR "$@" >&2
+}
+
+# Check if PGDATA is initialized
+postgres_is_initialized() {
+    [ -s "$PGDATA/PG_VERSION" ]
+}
+
+# Setup initial database
+postgres_setup_db() {
+    postgres_note "Initializing database in $PGDATA"
+
+    # Create PGDATA directory if it doesn't exist
+    mkdir -p "$PGDATA"
+
+    # Run initdb
+    "$PGBIN/initdb" \
+        -D "$PGDATA" \
+        -U "$POSTGRES_USER" \
+        --encoding=UTF8 \
+        --locale=C \
+        --no-instructions
+
+    postgres_note "Database initialized"
+}
+
+# Setup configuration files
+postgres_setup_config() {
+    postgres_note "Setting up configuration files"
+
+    # Copy config templates
+    cp "$BUNDLE_DIR/share/supabase-cli/config/postgresql.conf.template" "$PGDATA/postgresql.conf"
+    cp "$BUNDLE_DIR/share/supabase-cli/config/pg_hba.conf.template" "$PGDATA/pg_hba.conf"
+    cp "$BUNDLE_DIR/share/supabase-cli/config/pg_ident.conf.template" "$PGDATA/pg_ident.conf"
+
+    # Set absolute path to getkey script in postgresql.conf
+    GETKEY_SCRIPT="$BUNDLE_DIR/share/supabase-cli/config/pgsodium_getkey.sh"
+
+    # Ensure getkey script is executable
+    if [ -f "$GETKEY_SCRIPT" ]; then
+        chmod +x "$GETKEY_SCRIPT"
+    fi
+
+    cat >> "$PGDATA/postgresql.conf" << EOF
+
+# pgsodium and vault configuration (set by supabase-postgres-init)
+pgsodium.getkey_script = '$GETKEY_SCRIPT'
+vault.getkey_script = '$GETKEY_SCRIPT'
+EOF
+
+    postgres_note "Configuration files set up"
+}
+
+# Set password for superuser using single-user mode
+postgres_setup_password() {
+    if [ -n "$POSTGRES_PASSWORD" ]; then
+        postgres_note "Setting password for user: $POSTGRES_USER"
+
+        # Use single-user mode to set password before server starts
+        # This allows us to use scram-sha-256 authentication
+        # Must specify 'postgres' database as the target database
+        # -j flag allows natural multi-line SQL (terminated by semicolon + empty line)
+        "$PGBIN/postgres" --single -j -D "$PGDATA" postgres <<-EOSQL
+			ALTER USER "$POSTGRES_USER" WITH PASSWORD '$POSTGRES_PASSWORD';
+		EOSQL
+
+        postgres_note "Password set successfully"
+    fi
+}
+
+# Create additional database if specified and different from default
+postgres_create_db() {
+    if [ "$POSTGRES_DB" != "postgres" ]; then
+        postgres_note "Creating database: $POSTGRES_DB"
+
+        # Must specify 'postgres' database as the target database for single-user mode
+        # -j flag allows natural multi-line SQL (terminated by semicolon + empty line)
+        "$PGBIN/postgres" --single -j -D "$PGDATA" postgres <<-EOSQL
+			CREATE DATABASE "$POSTGRES_DB";
+		EOSQL
+
+        postgres_note "Database created"
+    fi
+}
+
+# Run initialization scripts from a directory
+postgres_process_init_files() {
+    local initdir="$1"
+
+    if [ -d "$initdir" ]; then
+        postgres_note "Running initialization scripts from $initdir"
+
+        # Process files in sorted order
+        for f in "$initdir"/*; do
+            if [ ! -f "$f" ]; then
+                continue
+            fi
+
+            case "$f" in
+                *.sh)
+                    if [ -x "$f" ]; then
+                        postgres_note "Running $f"
+                        "$f"
+                    else
+                        postgres_note "Sourcing $f"
+                        . "$f"
+                    fi
+                    ;;
+                *.sql)
+                    postgres_note "Running $f"
+                    "$PGBIN/postgres" --single -j -D "$PGDATA" postgres < "$f"
+                    ;;
+                *.sql.gz)
+                    postgres_note "Running $f"
+                    gunzip -c "$f" | "$PGBIN/postgres" --single -j -D "$PGDATA" postgres
+                    ;;
+                *)
+                    postgres_note "Ignoring $f"
+                    ;;
+            esac
+        done
+    fi
+}
+
+# Main initialization flow
+postgres_init() {
+    if postgres_is_initialized; then
+        postgres_note "Database already initialized, skipping setup"
+        return
+    fi
+
+    postgres_setup_db
+    postgres_setup_config
+    postgres_setup_password
+    postgres_create_db
+
+    # Process any initialization scripts in standard location
+    # This allows users to add custom init scripts similar to Docker
+    postgres_process_init_files "$BUNDLE_DIR/share/supabase-cli/init-scripts"
+
+    postgres_note "Initialization complete"
+}
+
+# Main entrypoint
+main() {
+    # Validate environment
+    if [ -z "$PGDATA" ]; then
+        postgres_error "PGDATA environment variable must be set"
+        exit 1
+    fi
+
+    # Initialize database if needed
+    postgres_init
+
+    # Start PostgreSQL server
+    postgres_note "Starting PostgreSQL server"
+    exec "$PGBIN/postgres" -D "$PGDATA" "$@"
+}
+
+# Run main function
+main "$@"

nix/packages/cli-config/postgresql.conf.template

@@ -62,6 +62,9 @@
             psql_orioledb-17 = self'.packages."psql_orioledb-17/bin";
             inherit (self.supabase) defaults;
           };
+          psql_17_cli_portable = pkgs.callPackage ./postgres-portable.nix {
+            psql_17_cli = self'.legacyPackages.psql_17_cli;
+          };
           start-replica = pkgs.callPackage ./start-replica.nix {
             psql_15 = self'.packages."psql_15/bin";
             inherit pgsqlSuperuser;