That Password Prompt on a Fresh Postgres Install? It’s pg_hba.conf, Not a Bug.

Last week I spun up a clean Ubuntu VM, installed PostgreSQL 16, and typed psql -U postgres out of habit. Instead of a friendly prompt, I stared at an authentication failure. I had never set a password. The machine was 15 minutes old. If you’re reading this, you’ve probably hit that same moment of confusion—and the real answer is simple.

Here is the one‑sentence answer before you dive deeper:

It’s pg_hba.conf enforcing an authentication method that either demands your OS username match a database role (peer) or expects a password hash that doesn’t exist (scram-sha-256). The fix is either sudo -u postgres psql or creating a matching database role.

No, you didn’t forget a setup step. No, you don’t need to uninstall. No, the installer didn’t bug out.

I also recorded a video walking through the exact steps: ▶️ Watch the companion video. By the time you finish, you’ll be the pg_hba.conf whisperer on your team. ## What pg_hba.conf Actually Controls

The file is a client‑authentication rulebook. Each line says, “for a connection type from a database by a user to a specific address, use this authentication method.”

When you type psql -U postgres, you’re connecting over a Unix socket (if no host is given) as the postgres user. On most fresh Debian/Ubuntu installs the first matching rule is:

local   all   postgres   peer

Peer means “check the OS user behind the connection; if it matches the database role name, let them in — no password.” That’s why sudo -u postgres psql works and a plain psql -U postgres fails: the OS user is you, not postgres.

If PostgreSQL was built with scram-sha-256 defaults (common on RHEL‑family or source‑compiled installs), the rule might demand a password hash that doesn’t exist yet. Either way, the prompt isn’t wrong — it’s just following orders.

Spot the Rule That Caught You

Get the location and current rules right inside sudo -u postgres psql:

SHOW hba_file;

Open that file with nano, vim, or pg_conftool and look for uncommented lines that match your connection type (local, host, or hostssl). The first match wins, so ordering matters.

Quick‑Fix Paths That Won’t Break Things

1. The 30‑second fix: always connect as the postgres OS user.

   sudo -u postgres psql

Once inside, create your own superuser with a password if you want to use a GUI later.

1. Switch authentication for local sessions to trust temporarily — and only on a dev machine. Edit the local entry to trust, then reload:

   sudo pg_ctlcluster 16 main reload   # or systemctl reload postgresql

Now any OS user can become any database role without a password. Never do this on a server that accepts network connections.

1. Set a password for postgres and keep secure scram‑sha‑256. Within psql:

   ALTER USER postgres WITH PASSWORD 'a‑strong‑passphrase';

Then in pg_hba.conf, change the relevant local entry from peer to scram-sha-256 and reload. Now you can psql -U postgres and type the password.

When the Quick Fix Isn’t Enough

Production‑like setups quickly outgrow “just trust local.” Maybe your team uses pooled connections, or you’ve containerised Postgres where the peer method doesn’t apply. Then a misconfigured pg_hba.conf can lock everyone out.

While manual checks work for play, production clusters demand constant vigilance. Tools like MyDBA watch authentication errors and config integrity, so a missing local entry doesn’t become a 3am fire drill. Its health‑check dashboards surface connection‑refused counts and pg_hba.conf drift long before you’d notice in a log.

From “Access Denied” to Finger‑Guns

That initial password prompt isn’t a bug — it’s Postgres sticking to the security policy you inherited with the package. Once you can read pg_hba.conf as a simple allow‑list, you stop panicking and start tweaking it deliberately. You’ll know to sudo -u postgres first, inspect the rules, then shape authentication exactly the way your workload, team habits, and security posture require.

The real growth moment isn’t getting past the prompt; it’s recognising that every fresh install is a blank‑canvas security model waiting for your signature. Master this file once, and you’ll never feel locked out again — and you’ll know exactly why that’s a feature, not a failure.

---

pgdba Editorial builds MyDBA, a Postgres monitoring and health‑check tool — https://mydba.dev/?utm_source=devto&utm_medium=platform&utm_campaign=that-password-prompt-on-a-fresh-postgres-install-it-s-pg-hba-conf-not-

Tired of playing detective with psql: error: connection to server…? Let MyDBA keep an eye on auth patterns and config changes — grab a free account.