PostgreSQL "database does not exist" & "role does not exist" Errors: Root Causes, Emergency Triage & IaC Provisioning

Differentiating typos, case-sensitive quoting ("Prod" vs prod), and missing roles after restores, emergency creation runbook, and Terraform/IaC automation.

Reviewed by:Senior Database Architect & SRE (dataiotech Labs)

Tested Versions: PostgreSQL 14 / 15 / 16 / 17

Operational Verification & Reliability Metadata

Last Technical Review: 2 Kasım 2026

Tested VersionsPostgreSQL 14.10, 15.6, 16.4, 17.11 (Ubuntu 24.04 / Alpine Linux)

Required PrivilegesSUPERUSER or CREATEDB / CREATEROLE privilege

Risk Assessment

LowMissing role or database causes deployment pipelines to enter CrashLoopBackOff

Expected OutputTarget database and role listed in \l and \du with correct ownership and grants

Rollback Procedure:Clean up temporary objects via DROP DATABASE / DROP ROLE

PostgreSQL Docs: CREATE ROLE & CREATE DATABASE

First 60 Seconds Emergency Protocol:

The error string is a symptom, not the root cause. Do not restart the server blindly. Run the diagnostic queries below to pinpoint the actual failure mode.

▸Symptom

Applications or CI/CD pipelines fail upon startup, generating entries in PostgreSQL server logs:

plaintext

FATAL:  database "prod" does not exist
FATAL:  role "deploy" does not exist

▸What You See in Production

Kubernetes pods enter CrashLoopBackOff. PostgreSQL is fully responsive, but clients are rejected at handshake due to invalid identifiers or missing catalog entities.

▸Root Cause Matrix

Probability	Root Cause	Description
%50	Case Sensitivity & Quoting	PostgreSQL folds unquoted identifiers to lowercase. `"Prod"` and `prod` represent distinct entities.
%30	Post-Restore Missing Roles	Standard `pg_dump` omits cluster-wide objects (`pg_dumpall --globals-only`).
%20	Configuration Typo	Environment variables contain misspelled connection targets.

▸EMERGENCY RUNBOOK (0-5 min)

sql

-- 1. Inspect databases and roles
\l
\du

-- 2. Provision missing target database and role
CREATE DATABASE prod OWNER app_user;
CREATE ROLE deploy LOGIN PASSWORD 'StrongTempPassword2026!';
GRANT CONNECT ON DATABASE prod TO deploy;

▸PERMANENT BLUEPRINT & IaC

1Globals Backup: Back up cluster roles via pg_dumpall --globals-only.
2Terraform Infrastructure: Manage roles declaratively in version-controlled IaC.
3Idempotent Ingestion: Run pre-flight bootstrap scripts with conditional existence checks.

▸Verification

sql

SELECT datname, pg_catalog.pg_get_userbyid(datdba) AS owner FROM pg_database WHERE datname = 'prod';
SELECT rolname, rolcanlogin FROM pg_roles WHERE rolname = 'deploy';

Other Database Error Triage Playbooks

Other battle-tested diagnostic guides for high-severity database errors.

All Errors (82)

POSTGRESQL7 min

PostgreSQL Connection Exhaustion & too many clients Triage

Root causes of FATAL: sorry, too many clients already and remaining connection slots errors, read-only pg_stat_activity diagnosis with privilege boundaries, and two-tier pooling mitigation.

POSTGRESQL4 min

PostgreSQL password authentication failed: Root Cause and Fix

Four root causes of psql password authentication failed: incorrect password, md5/SCRAM mismatch, pg_hba.conf rule ordering, and port/cluster confusion. Step-by-step triage.

POSTGRESQL4 min

PostgreSQL connection refused: 8-Step Definitive Triage

Difference between connection refused, timeout, and no pg_hba entry; triage for listen_addresses, port conflicts, firewalls, and Docker container mappings.