PostgreSQL で「role does not exist」になり接続・操作できない

要約

FATAL: role "app" does not exist（psql: ... role ... does not exist）は、接続しようとしたロール（PostgreSQL ではユーザー＝ロール）がそのデータベースクラスタに登録されていないときに出る。
ロールはデータベース単位ではなくクラスタ全体で共有されるため（Database Roles）、どこかで作っておく必要がある。
まず実在するロールを確認し、無ければ作る。
名前がずれているだけなら接続情報を直す。

よくある原因

1. 未作成: ロールを一度も作っていない。
   単純な綴り違いも含む。
2. 既定ロールの思い込み: psql はユーザー名を省くと OS ユーザー名と同じロールを探す。initdb 時の名前と違うと「postgres does not exist」のように出る。
3. Docker の後出し変更: POSTGRES_USER を変更しても、既に作られたデータボリュームには反映されず旧ロールしか存在しない。
4. 削除・別クラスタ: 誤って削除した、または別インスタンスに作ってしまった。

解決策

1. ロールを作成する

スーパーユーザー（多くは postgres）で接続して作る（CREATE ROLE）。

CREATE ROLE app WITH LOGIN PASSWORD 'secret';

LOGIN を付けないと接続用にならない点に注意。CREATE USER は LOGIN 付きの別名。

2. 実在するロールを確認する

SELECT rolname FROM pg_roles ORDER BY 1;

ここに出ない名前で接続していれば、それが原因。psql なら \du でも一覧できる。

3. 接続情報を合わせる / Docker を作り直す

アプリの user や PGUSER を実在ロールに合わせる。
Docker で初期ユーザーを変えたいときは、データボリュームを消してから再作成する。

docker compose down -v   # ボリュームごと削除（データも消える点に注意）
docker compose up -d