chore(migrate): add local migration test harness script

api/prisma/test-migration-local.sh

@@ -0,0 +1,84 @@
+#!/bin/sh
+# ---------------------------------------------------------------------------
+# Local migration test harness.
+# Builds the migration Docker image from the monorepo root, spins up a fresh
+# throwaway Postgres container, runs the migration job against it, and tears
+# everything down when done — pass or fail.
+#
+# Usage (from monorepo root):
+#   sh api/prisma/test-migration-local.sh
+#
+# Requirements: Docker
+# ---------------------------------------------------------------------------
+set -e
+
+NETWORK=migrate-test-net
+DB_CONTAINER=migrate-test-postgres
+MIGRATE_IMAGE=optima-api-migrate-local-test
+DB_USER=optima
+DB_PASS=testpass
+DB_NAME=optima
+
+# ---- Cleanup function — always runs on exit ----
+cleanup() {
+  echo "[test] Cleaning up..."
+  docker rm -f "$DB_CONTAINER" 2>/dev/null || true
+  docker network rm "$NETWORK" 2>/dev/null || true
+  docker rmi "$MIGRATE_IMAGE" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# ---- 1. Create an isolated Docker network ----
+echo "[test] Creating Docker network: $NETWORK"
+docker network create "$NETWORK"
+
+# ---- 2. Start a fresh Postgres container ----
+echo "[test] Starting fresh Postgres container: $DB_CONTAINER"
+docker run -d \
+  --name "$DB_CONTAINER" \
+  --network "$NETWORK" \
+  -e POSTGRES_USER="$DB_USER" \
+  -e POSTGRES_PASSWORD="$DB_PASS" \
+  -e POSTGRES_DB="$DB_NAME" \
+  postgres:17
+
+# Wait for Postgres to be ready (up to 30s)
+echo "[test] Waiting for Postgres to be ready..."
+READY=0
+for i in $(seq 1 30); do
+  if docker exec "$DB_CONTAINER" pg_isready -U "$DB_USER" -d "$DB_NAME" > /dev/null 2>&1; then
+    READY=1
+    break
+  fi
+  sleep 1
+done
+
+if [ $READY -eq 0 ]; then
+  echo "[test] Postgres did not become ready in 30s. Aborting."
+  exit 1
+fi
+echo "[test] Postgres is ready."
+
+# ---- 3. Build the migration image from the monorepo root ----
+echo "[test] Building migration image: $MIGRATE_IMAGE"
+# Determine the monorepo root (two levels up from this script's directory)
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+REPO_ROOT=$(cd "$SCRIPT_DIR/../.." && pwd)
+
+docker build \
+  -f "$REPO_ROOT/api/Dockerfile" \
+  --target migration \
+  -t "$MIGRATE_IMAGE" \
+  "$REPO_ROOT"
+
+# ---- 4. Run the migration container against the test Postgres ----
+echo "[test] Running migration container..."
+DATABASE_URL="postgresql://${DB_USER}:${DB_PASS}@${DB_CONTAINER}:5432/${DB_NAME}"
+
+docker run --rm \
+  --network "$NETWORK" \
+  -e DATABASE_URL="$DATABASE_URL" \
+  "$MIGRATE_IMAGE"
+
+echo ""
+echo "[test] SUCCESS — all migrations applied cleanly to a fresh database."