{"record":{"id":"07986330106b83c1","repo":"block/buzz","slug":"db-connection-failed-e","errorCode":null,"errorMessage":"DB connection failed: {e}","messagePattern":"DB connection failed: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"critical","filePath":"crates/buzz-relay/src/main.rs","lineNumber":176,"sourceCode":"    relay_metrics::install(config.metrics_port, usage_idle_timeout_secs);\n    metrics::gauge!(\"buzz_audit_enabled\").set(if config.audit_enabled { 1.0 } else { 0.0 });\n    info!(\n        port = config.metrics_port,\n        idle_timeout_secs = usage_idle_timeout_secs,\n        \"Prometheus metrics exporter started\"\n    );\n\n    let db_config = DbConfig {\n        database_url: config.database_url.clone(),\n        read_database_url: config.read_database_url.clone(),\n        replica_read_max_age_ms: config.replica_read_max_age_ms,\n        max_connections: config.db_pool_size,\n        read_max_connections: config.db_read_pool_size,\n        ..DbConfig::default()\n    };\n    let db = Db::new(&db_config).await.map_err(|e| {\n        error!(\"Failed to connect to Postgres: {e}\");\n        anyhow::anyhow!(\"DB connection failed: {e}\")\n    })?;\n    if db.has_read_pool() {\n        info!(\"Postgres connected (writer + lazy read replica pool)\");\n        // Reader-down at boot must not crash or block the relay; this warn-only\n        // ping is the sole boot-time visibility that the replica is unreachable\n        // (the lazy pool with min_connections=0 dials nothing until first use).\n        db.spawn_read_pool_boot_ping();\n    } else {\n        info!(\"Postgres connected\");\n    }\n\n    let auto_migrate =\n        buzz_auto_migrate_enabled(std::env::var(\"BUZZ_AUTO_MIGRATE\").ok().as_deref());\n    if auto_migrate {\n        db.migrate().await.map_err(|e| {\n            error!(\"Failed to run database migrations: {e}\");\n            anyhow::anyhow!(\"Database migration failed: {e}\")\n        })?;","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/block/buzz/blob/f956e6fe06a76e50cbd8fba1a162482e752e7f1a/crates/buzz-relay/src/main.rs#L158-L194","documentation":"Fatal boot error: Db::new() could not establish the Postgres writer pool from DATABASE_URL using the configured db_pool_size. Every later subsystem (events, auth, search) depends on this store, so the relay refuses to start. The sqlx error string with the precise cause is appended.","triggerScenarios":"Postgres unreachable (wrong host/port, DNS failure), credentials rejected, DATABASE_URL malformed, target database does not exist, or the server refuses connections (max_connections exhausted, TLS mismatch).","commonSituations":"docker compose Postgres container not started or still initializing when the relay boots; `just setup` never run locally; rotated DB password not propagated; Kubernetes service name typo; connection budget exhausted by other clients.","solutions":["Test the exact URL: `psql \"$DATABASE_URL\" -c 'select 1'`","Start Postgres (e.g. `docker compose up -d postgres`) and retry boot","Fix host/credentials/database name in DATABASE_URL","Check Postgres logs for auth, TLS, or max_connection refusals"],"exampleFix":"# before — relay races postgres at boot\nservices:\n  relay:\n    depends_on: [postgres]\n\n# after — wait for readiness\nservices:\n  relay:\n    depends_on:\n      postgres:\n        condition: service_healthy","handlingStrategy":"retry","validationCode":"# Pre-flight the exact writer URL before starting the relay.\npsql \"$DATABASE_URL\" -c 'select 1' || { echo 'DATABASE_URL unreachable'; exit 1; }","typeGuard":null,"tryCatchPattern":"# docker-compose: bounded restarts absorb boot-time DB races\nservices:\n  relay:\n    restart: on-failure:5\n  postgres:\n    healthcheck:\n      test: [\"CMD\", \"pg_isready\", \"-U\", \"postgres\"]","preventionTips":["Order startup: Postgres healthy before the relay (depends_on condition or init container)","Run `just setup` on fresh clones so the database and migrations exist","Rotate DB credentials through the same pipeline that updates the relay env","Monitor Postgres connection count against max_connections"],"tags":["postgres","database","connection","startup","sqlx"],"backgroundTag":"postgres-connection-failed","analyzedSha":"f956e6fe06a76e50cbd8fba1a162482e752e7f1a","analyzedAt":"2026-08-16T22:11:40.750Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}