PostgreSQL で「password authentication failed for user」になり接続できない

要約

psql: error: ... FATAL: password authentication failed for user "app" は、サーバーが受け取ったパスワードがロールの保存値と一致しないときに出る。
原因はパスワードの単純な間違いか、pg_hba.conf の認証方式とハッシュ方式の食い違いのどちらか。
まずロールのパスワードを再設定し、それでも通らなければ pg_hba.conf の該当行と password_encryption を確認する。

よくある原因

1. パスワード不一致: 単純なタイプミスのほか、ロールにそもそもパスワードが設定されていないのに password 認証を要求しているケース。
2. 認証方式の食い違い: pg_hba.conf の方式が scram-sha-256 なのに、保存されているのが md5 ハッシュ（または逆）で照合できない。
3. 古い接続情報: シェルの PGPASSWORD やホームの .pgpass、アプリの環境変数が古い値を握っていて、入力したつもりの値が使われていない。
4. アップグレード起因: メジャーバージョン移行で password_encryption の既定が変わり、移行前ハッシュと不一致になる。

解決策

1. ロールのパスワードを再設定する

スーパーユーザーで接続し、対象ロールのパスワードを設定し直す。

ALTER ROLE app WITH PASSWORD 'new-secure-password';

この時点のサーバー設定（password_encryption）でハッシュが作り直されるため、方式の食い違いも同時に解消されることが多い。

2. pg_hba.conf の認証方式を確認して reload する

接続種別（local / host）ごとに方式が決まる。scram-sha-256 を使う行の例。

# TYPE  DATABASE  USER  ADDRESS         METHOD
host    all       all   127.0.0.1/32    scram-sha-256

編集後は再起動不要で reload するだけでよい（pg_hba.conf のドキュメント）。

SELECT pg_reload_conf();

3. 接続情報を突き合わせる

user・password・host・port・database を一つずつ確認する。
シェル変数が割り込んでいないかも見る。

echo "$PGPASSWORD"
psql "postgresql://app:new-secure-password@localhost:5432/appdb"