feat(dev): add --preview-db=N flag to nix run .#dev

Connects to the database used by an opencouncil preview deployment.
Detects whether the PR has an isolated DB (SSH tunnel) or uses
the shared staging DB (reads URL from server), and forces external
DB mode to skip local postgres.

Requires OC_PREVIEW_SSH to be set to the preview server SSH target.
Can be used independently or alongside --preview-tasks=M.

Author: kouloumos

.env.example

@@ -64,6 +64,13 @@ CDN_URL=https://data.opencouncil.gr
 # Generate with: openssl rand -base64 32
 CRON_SECRET=
 
+# ---------------------------------
+# Preview Server (for --preview-db flag)
+# ---------------------------------
+# SSH target for connecting to the preview server's database.
+# Only needed when using: nix run .#dev -- --preview-db=N
+# OC_PREVIEW_SSH=root@159.89.98.26
+
 # ---------------------------------
 # Optional Variables
 # ---------------------------------

docs/nix-usage.md

@@ -93,6 +93,48 @@ When `TASK_API_URL` is configured in `.env`, the dev runner will check if the ta
    ⚠ Task server not reachable (start it separately for E2E testing)
 ```
 
+### Preview Database (--preview-db=N)
+
+When testing against a preview deployment's database locally (e.g., running cron jobs or admin tools against a PR's data), use `--preview-db=N` where N is the **opencouncil** PR number:
+
+```bash
+nix run .#dev -- --preview-db=193
+```
+
+Can be combined with `--preview-tasks=M` to also connect to a tasks preview (where M is the **opencouncil-tasks** PR number):
+
+```bash
+nix run .#dev -- --preview-db=193 --preview-tasks=26
+```
+
+**Prerequisites:**
+- `OC_PREVIEW_SSH` must be set to the SSH target for the preview server:
+  ```bash
+  # In .env or exported
+  OC_PREVIEW_SSH=root@159.89.98.26
+  ```
+- Your SSH key must be in the server's `authorized_keys`
+
+**How it works:**
+
+The flag detects whether the PR has an isolated database (migration PRs with `.has-local-db` marker) or uses the shared staging database:
+
+- **Isolated DB**: Opens an SSH tunnel to the per-PR PostgreSQL instance on the server
+- **Shared staging DB**: Reads `DATABASE_URL` from the server's `.env` and uses it directly
+
+In both cases, the local postgres is skipped (`--db=external` mode is forced).
+
+**Startup output:**
+```
+🗄️  Connecting to preview database for PR #193...
+   ✓ SSH connection OK
+   ✓ Isolated database detected (port 5625)
+   ✓ SSH tunnel active: localhost:5625 → 127.0.0.1:5625
+   Database: postgresql://opencouncil@localhost:5625/opencouncil
+```
+
+The SSH tunnel is automatically cleaned up when the dev server exits.
+
 ### Mobile Preview (QR code for phone testing)
 
 The dev server binds to `0.0.0.0` by default, making it accessible from other devices on the same Wi-Fi. Click the **QR button** next to the DEV panel (bottom-right) to see a QR code encoding the LAN URL for the current page.

flake.nix

@@ -511,7 +511,7 @@ USAGE
               usage() {
                 cat <<'USAGE'
 Usage:
-  nix run .#dev -- [--db=remote|external|nix|docker] [--db-url URL] [--direct-url URL] [--migrate] [--no-studio] [--locked] [--no-lan] [--preview-tasks=N]
+  nix run .#dev -- [--db=remote|external|nix|docker] [--db-url URL] [--direct-url URL] [--migrate] [--no-studio] [--locked] [--no-lan] [--preview-tasks=N] [--preview-db=N]
 
 DB modes:
   --db=nix      Start Postgres+PostGIS via Nix + app (process-compose TUI) (default)
@@ -525,6 +525,7 @@ Flags:
   --fast           Use pre-built PostGIS from binary cache (faster first build, but may not match production)
   --no-lan         Bind dev server to localhost only (default: binds to 0.0.0.0 for mobile preview)
   --preview-tasks=N  Connect to opencouncil-tasks preview for PR #N (starts ngrok tunnel for callbacks)
+  --preview-db=N     Connect to the database used by opencouncil preview PR #N (requires OC_PREVIEW_SSH)
 USAGE
               }
 
@@ -539,6 +540,7 @@ USAGE
               postgis_locked="''${OC_POSTGIS_LOCKED:-1}"
               lan_enabled="''${OC_LAN:-1}"
               tasks_preview_pr="''${OC_PREVIEW_TASKS:-}"
+              preview_db_pr=""
 
               for arg in "$@"; do
                 case "$arg" in
@@ -550,6 +552,7 @@ USAGE
                   --fast) postgis_locked="0" ;;
                   --no-lan) lan_enabled="0" ;;
                   --preview-tasks=*) tasks_preview_pr="''${arg#--preview-tasks=}" ;;
+                  --preview-db=*) preview_db_pr="''${arg#--preview-db=}" ;;
                   --help|-h) usage; exit 0 ;;
                   *)
                     echo "Unknown argument: $arg" >&2
@@ -701,6 +704,94 @@ USAGE
                 echo ""
               fi
 
+              # --preview-db=N: connect to the database used by opencouncil preview PR #N
+              ssh_tunnel_pid=""
+              if [ -n "$preview_db_pr" ]; then
+                if [ -z "''${OC_PREVIEW_SSH:-}" ]; then
+                  echo "  ✗ OC_PREVIEW_SSH is not set." >&2
+                  echo "  Set it to the SSH target for the preview server:" >&2
+                  echo "    export OC_PREVIEW_SSH=root@159.89.98.26" >&2
+                  echo "  Or add to .env: OC_PREVIEW_SSH=root@159.89.98.26" >&2
+                  exit 1
+                fi
+
+                echo "🗄️  Connecting to preview database for PR #$preview_db_pr..."
+
+                # Validate SSH connectivity
+                if ! ssh -o ConnectTimeout=5 -o BatchMode=yes "$OC_PREVIEW_SSH" true 2>/dev/null; then
+                  echo "  ✗ Cannot connect to $OC_PREVIEW_SSH" >&2
+                  echo "  Check that your SSH key is in the server's authorized_keys" >&2
+                  exit 1
+                fi
+                echo "   ✓ SSH connection OK"
+
+                # Detect DB type: isolated (has .has-local-db marker) vs shared staging
+                preview_base_dir="/var/lib/opencouncil-previews"
+                # shellcheck disable=SC2029 # Intentional: expand variables locally before sending to server
+                if ssh "$OC_PREVIEW_SSH" "test -f $preview_base_dir/pr-$preview_db_pr/.has-local-db" 2>/dev/null; then
+                  # Isolated DB: tunnel to the per-PR postgres
+                  preview_db_port=$((5432 + preview_db_pr))
+
+                  # Verify the DB service is running
+                  # shellcheck disable=SC2029
+                  if ! ssh "$OC_PREVIEW_SSH" "systemctl is-active opencouncil-preview-db@$preview_db_pr" >/dev/null 2>&1; then
+                    echo "  ✗ Isolated database service is not running on the server." >&2
+                    echo "  Start it with: ssh $OC_PREVIEW_SSH systemctl start opencouncil-preview-db@$preview_db_pr" >&2
+                    exit 1
+                  fi
+
+                  echo "   ✓ Isolated database detected (port $preview_db_port)"
+
+                  # Check port is free before opening tunnel
+                  if is_port_in_use "$preview_db_port"; then
+                    echo "  ✗ Local port $preview_db_port is already in use." >&2
+                    echo "  Kill the existing process (e.g., a leftover SSH tunnel) and retry." >&2
+                    exit 1
+                  fi
+
+                  # Open SSH tunnel in background
+                  ssh -N -L "$preview_db_port:127.0.0.1:$preview_db_port" "$OC_PREVIEW_SSH" &
+                  ssh_tunnel_pid=$!
+
+                  # Wait for tunnel to bind the local port
+                  for _i in $(seq 1 10); do
+                    if is_port_in_use "$preview_db_port"; then
+                      break
+                    fi
+                    sleep 0.5
+                  done
+                  if ! is_port_in_use "$preview_db_port"; then
+                    echo "  ✗ SSH tunnel failed to bind port $preview_db_port." >&2
+                    kill "$ssh_tunnel_pid" 2>/dev/null || true
+                    exit 1
+                  fi
+
+                  echo "   ✓ SSH tunnel active: localhost:$preview_db_port → 127.0.0.1:$preview_db_port"
+
+                  db_url="postgresql://opencouncil@localhost:$preview_db_port/opencouncil"
+                  direct_url="$db_url"
+                  echo "   Database: $db_url"
+                else
+                  # Shared staging DB: read DATABASE_URL from server's .env
+                  echo "   ✓ Shared staging database detected"
+                  # shellcheck disable=SC2029
+                  preview_db_url=$(ssh "$OC_PREVIEW_SSH" "grep '^DATABASE_URL=' $preview_base_dir/.env 2>/dev/null | head -1 | cut -d= -f2-")
+                  if [ -z "$preview_db_url" ]; then
+                    echo "  ✗ Could not read DATABASE_URL from $preview_base_dir/.env on server." >&2
+                    exit 1
+                  fi
+
+                  db_url="$preview_db_url"
+                  direct_url="$preview_db_url"
+                  # Mask credentials in output
+                  echo "   Database: ''${preview_db_url%%@*}@***"
+                fi
+
+                echo ""
+                # Force external DB mode (skip local postgres)
+                db_mode="external"
+              fi
+
               # Check if TASK_API_URL is configured and reachable (non-blocking warning)
               if [ -z "$tasks_preview_pr" ] && [ -n "''${TASK_API_URL:-}" ]; then
                 echo "🔗 Task API configured: $TASK_API_URL"
@@ -852,6 +943,12 @@ EOF
                 cleanup_cmds="''${cleanup_cmds}kill $ngrok_pid 2>/dev/null || true; echo \"Stopped ngrok tunnel\";"
               fi
 
+              # If SSH tunnel is running, ensure it gets cleaned up on exit.
+              if [ -n "$ssh_tunnel_pid" ]; then
+                needs_cleanup=true
+                cleanup_cmds="''${cleanup_cmds}kill $ssh_tunnel_pid 2>/dev/null || true; echo \"Stopped SSH tunnel\";"
+              fi
+
               # Brief pause so startup messages are readable before TUI takes over
               echo "Starting process-compose..."
               sleep 5