From 3cc09924be624472448dbef1d4f0304706f51487 Mon Sep 17 00:00:00 2001
From: KellyMichels <kellymic@gmail.com>
Date: Wed, 22 Jul 2026 19:18:01 -0500
Subject: [PATCH] fix(bash): zbackup treats a not-running local DB as a calm
 skip

Fold all pg_dump messaging into local_pg_dump (caller just captures
success) and special-case an unreachable database. "connection refused"
/ "could not connect" / DNS / timeout now print a quiet
"Local database not running at host:port - source-only backup." instead
of a red multi-line error - a stopped dev DB is a normal state. Real
failures (version mismatch, auth, missing db) still print the full
pg_dump error so they're diagnosable.
---
 bash/zbackup | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/bash/zbackup b/bash/zbackup
index 9292ec0..8009d3b 100644
--- a/bash/zbackup
+++ b/bash/zbackup
@@ -46,27 +46,32 @@ ts()         { date +%Y%m%d-%H%M%S; }
 tag_suffix() { [ -n "$tag" ] && printf '_%s' "$(printf '%s' "$tag" | tr -s '[:space:]' '_')"; }
 
 # Dump the project's Postgres database if its .env declares a DATABASE_URL.
-# Checks <root>/.env, then <root>/backend/.env.
-# Exit codes:  0 = dumped ($2 written)   1 = dump attempted but failed
-#              2 = no local database configured (no .env / no DATABASE_URL)
+# Checks <root>/.env, then <root>/backend/.env. Prints its own status line for
+# every outcome; returns 0 (dumped, $2 written) or 1 (nothing dumped).
+# A not-running database (connection refused) is a calm, expected skip; a real
+# failure (version mismatch, auth, missing db) prints the loud pg_dump error.
 local_pg_dump() {  # <root> <out_path>
-  local root="$1" out="$2" env_file db_url err_out
+  local root="$1" out="$2" env_file db_url err_out rc
   env_file="$root/.env"; [ -f "$env_file" ] || env_file="$root/backend/.env"
-  [ -f "$env_file" ] || return 2
+  if [ ! -f "$env_file" ]; then dim "    No local DATABASE_URL - source-only backup."; return 1; fi
   db_url="$(grep -m1 '^DATABASE_URL=' "$env_file" | cut -d= -f2- | tr -d '[:space:]')"
-  [ -n "$db_url" ] || return 2
+  if [ -z "$db_url" ]; then dim "    No local DATABASE_URL - source-only backup."; return 1; fi
   db_url="$(printf '%s' "$db_url" | sed -E 's|^postgresql\+[^:]+://|postgresql://|')"
   if [[ "$db_url" =~ ^postgresql://([^:]+):([^@]+)@([^:]+):([0-9]+)/([^?]+) ]]; then
     local user="${BASH_REMATCH[1]}" pass="${BASH_REMATCH[2]}" host="${BASH_REMATCH[3]}"
     local port="${BASH_REMATCH[4]}" db="${BASH_REMATCH[5]}"
     command -v pg_dump >/dev/null 2>&1 || { err '    pg_dump not installed - skipping PG backup'; return 1; }
-    # Capture stderr so a failure is diagnosable (version mismatch, unreachable
-    # host, auth) instead of a bare "pg_dump failed".
-    if err_out="$(PGPASSWORD="$(z_urldecode "$pass")" pg_dump -h "$host" -p "$port" -U "$user" -d "$db" -F p -f "$out" 2>&1)" \
-       && [ -f "$out" ]; then
+    err_out="$(PGPASSWORD="$(z_urldecode "$pass")" pg_dump -h "$host" -p "$port" -U "$user" -d "$db" -F p -f "$out" 2>&1)"; rc=$?
+    if [ "$rc" -eq 0 ] && [ -f "$out" ]; then
       ok "    PostgreSQL dump: $(awk -v b="$(wc -c < "$out")" 'BEGIN{printf "%.1f", b/1024}') KB"
       return 0
     fi
+    # Not reachable (usually just not running locally) is expected - stay calm.
+    if printf '%s' "$err_out" | grep -qiE 'connection refused|could not connect|no route to host|could not translate host|timeout expired'; then
+      dim "    Local database not running at $host:$port - source-only backup."
+      return 1
+    fi
+    # A real failure (version mismatch, auth, missing db) - show the reason.
     err "    pg_dump failed ($host:$port/$db as $user):"
     printf '%s\n' "$err_out" | grep -v '^[[:space:]]*$' | sed 's/^/      /' >&2
     return 1
@@ -92,12 +97,7 @@ backup_project() {  # <key>
   dump_dir="$(mktemp -d "${TMPDIR:-/tmp}/zbackup_${key}_XXXXXX")"
   db_dump="$dump_dir/database_pg.sql"
   warn "  [1/3] Checking for a local database to dump..."
-  local_pg_dump "$root" "$db_dump"
-  case $? in
-    0) extra="$db_dump" ;;
-    2) dim  "    No local DATABASE_URL - source-only backup." ;;
-    *) warn "    Database dump failed (see above) - continuing with source-only backup." ;;
-  esac
+  if local_pg_dump "$root" "$db_dump"; then extra="$db_dump"; fi
 
   warn "  [2/3] Archiving source..."
   local excl=()