ci(e2e): start the iOS test database in the background

.github/workflows/e2e.yml

@@ -307,6 +307,14 @@ jobs:
           node-version: '24'
           cache: 'npm'
 
+      # macOS runners have no Docker - run the test database via Homebrew
+      # Postgres instead, matching docker-compose.test.yml (test/test@5433,
+      # tmpfs-equivalent: the runner is ephemeral anyway). The ~1 min install
+      # runs in the background from here so it overlaps npm ci, Maestro, the
+      # simulator pick and Metro; "Wait for test database" below joins it.
+      - name: Start test database (Homebrew Postgres, port 5433, background)
+        run: bash scripts/ci/postgres-brew.sh background
+
       - name: Install dependencies (workspace root)
         run: npm ci --prefer-offline --no-audit
 
@@ -326,17 +334,14 @@ jobs:
       - name: Pick a simulator device
         run: bash scripts/e2e/ios-simulator.sh pick
 
-      # Metro starts in the background here so its boot overlaps Postgres and
-      # the backend; it is awaited (and the bundle prewarmed) right before
+      # Metro starts in the background here so its boot overlaps the Postgres
+      # install and the backend; it is awaited (and the bundle prewarmed) right before
       # Maestro runs.
       - name: Start Metro bundler (background)
         run: bash scripts/e2e/metro-start.sh
 
-      # macOS runners have no Docker - run the test database via Homebrew
-      # Postgres instead, matching docker-compose.test.yml (test/test@5433,
-      # tmpfs-equivalent: the runner is ephemeral anyway).
-      - name: Start test database (Homebrew Postgres, port 5433)
-        run: bash scripts/ci/postgres-brew.sh
+      - name: Wait for test database (installing since checkout)
+        run: bash scripts/ci/postgres-brew.sh wait
 
       - name: Run database migrations
         run: npm run migrate:test

scripts/ci/postgres-brew.sh

@@ -8,9 +8,51 @@
 # (measured 155 s of a 220 s step). The image's pinned index is fine for a
 # throwaway test database; if it ever lacks a postgresql@16 bottle the install
 # fails loudly, which is the right signal to bump the image.
+#
+# Modes: `start` (default) installs, inits and starts the server; `wait`
+# blocks until esign_test accepts connections. The iOS job runs `start` in
+# the background right after checkout (`background`, which also records the
+# PID and log for `wait`) so the install overlaps npm ci, Maestro, the
+# simulator pick and Metro, then calls `wait` right before migrations.
 set -euo pipefail
 export HOMEBREW_NO_AUTO_UPDATE=1 HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_NO_ENV_HINTS=1
 TMP="${RUNNER_TEMP:-/tmp}"
+MODE="${1:-start}"
+SETUP_LOG="$TMP/pg-setup.log"
+
+wait_for_db() {
+  # The background install has no PGBIN until brew is done; poll pg_isready
+  # from wherever it lands. Up to 5 min: the whole install is ~1 min warm.
+  # HOMEBREW_PREFIX is exported on the runner images; `brew --prefix` itself
+  # costs ~20 s of Ruby startup on a busy runner, so only fall back to it.
+  local pgbin="" candidate
+  candidate="${HOMEBREW_PREFIX:-$(brew --prefix)}/opt/postgresql@16/bin"
+  for i in {1..150}; do
+    if [ -z "$pgbin" ] && [ -x "$candidate/pg_isready" ]; then pgbin="$candidate"; fi
+    if [ -n "$pgbin" ] && "$pgbin/pg_isready" -q -h localhost -p 5433 -U test -d esign_test; then
+      echo "Database ready after $((i * 2))s"; return 0
+    fi
+    if [ -f "$TMP/pg-setup.pid" ] && ! kill -0 "$(cat "$TMP/pg-setup.pid")" 2>/dev/null \
+       && ! grep -q "^SETUP_OK$" "$SETUP_LOG" 2>/dev/null; then
+      echo "::error::Background Postgres setup exited before the database was ready"; break
+    fi
+    sleep 2
+  done
+  echo "--- $SETUP_LOG ---"; cat "$SETUP_LOG" 2>/dev/null || true
+  echo "::error::Database not ready after $((i * 2))s"; return 1
+}
+
+case "$MODE" in
+  wait) wait_for_db; exit $? ;;
+  background)
+    nohup bash "$0" start > "$SETUP_LOG" 2>&1 &
+    echo $! > "$TMP/pg-setup.pid"
+    echo "Postgres setup started in the background (pid $(cat "$TMP/pg-setup.pid"), log $SETUP_LOG)"
+    exit 0 ;;
+  start) ;;
+  *) echo "usage: $0 [start|background|wait]" >&2; exit 2 ;;
+esac
+
 brew install --quiet postgresql@16
 PGBIN="$(brew --prefix postgresql@16)/bin"
 echo "test" > "$TMP/pgpass"
@@ -22,3 +64,4 @@ for i in {1..15}; do
 done
 "$PGBIN/createdb" -h localhost -p 5433 -U test esign_test
 "$PGBIN/pg_isready" -h localhost -p 5433 -U test -d esign_test
+echo SETUP_OK