PostgreSQL: ошибка FATAL role does not exist — причины и решение

MAATRIX

Приложение не заходит в базу, в логах — PostgreSQL ошибка FATAL role does not exist. Смысл прост: PostgreSQL не нашёл роль (пользователя), под которой пытаются подключиться. В PostgreSQL пользователи называются ролями, и эта ошибка означает, что нужной роли просто нет или её имя не совпадает с тем, что указано в подключении. Разберём, почему так происходит и как быстро всё починить.

Первое действие: проверьте, какие роли существуют

Не гадайте — посмотрите список ролей в базе и сравните с тем, под кем пытается зайти приложение. Подключитесь суперпользователем postgres и выведите роли:

sudo -u postgres psql -c "\du"

Команда \du покажет все существующие роли. Сравните их с именем пользователя в строке подключения приложения (в DATABASE_URL, конфиге или переменных окружения). Часто причина видна сразу: роли с таким именем нет вовсе, либо есть похожая, но с другим написанием. PostgreSQL чувствителен к регистру, если имя было создано в кавычках, и к точному совпадению. Определив, что именно не так — роли нет или имя не совпадает, — вы сразу поймёте, какой из вариантов ниже ваш. Это избавляет от лишних действий.

Причина 1: роль вообще не создана

Самый частый случай — роль просто не создали. Так бывает после переноса приложения на новый сервер, восстановления базы из дампа без создания пользователей или свежей установки, где заведена база, но не заведён пользователь под неё. Создайте роль с паролем и правом подключения:

CREATE ROLE myuser WITH LOGIN PASSWORD 'надёжный_пароль';

Ключевое слово LOGIN обязательно — без него роль существует, но не может использоваться для входа (это отдельная частая ошибка). Имя роли должно точно совпадать с тем, что ждёт приложение. После создания роли выдайте ей доступ к нужной базе (об этом ниже) и проверьте подключение. Если приложение при старте само создаёт схему, роль должна существовать до первого запуска. Создание недостающего пользователя закрывает большинство случаев этой ошибки — она чаще всего означает буквально «вы забыли завести пользователя».

Причина 2: имя роли не совпадает с подключением

Роль есть, но приложение всё равно получает ошибку — значит, имя в подключении не совпадает с реальным. Причины: опечатка, другой регистр, лишние пробелы, роль называется иначе, чем ожидает конфиг. Посмотрите точное имя в \du и сверьте символ в символ со строкой подключения. Если приложение ждёт роль app_user, а в базе есть только appuser — это разные роли. Либо исправьте имя в конфиге приложения, либо создайте роль с тем именем, которое ждёт приложение.

Отдельный нюанс — регистр. Если роль создавали как "MyUser" в двойных кавычках, PostgreSQL сохранит регистр, и подключаться нужно ровно так же. Обычно роли создают в нижнем регистре без кавычек, чтобы избежать путаницы. Если сомневаетесь, проще всего привести имя роли и конфиг приложения к единому нижнему регистру. Сверка точного написания имени — быстрый способ устранить ошибку, когда роль вроде бы есть, но подключение всё равно падает.

Причина 3: роль есть, но нет прав на базу

Иногда роль создана и имя совпадает, но после входа приложение упирается в отказ доступа к базе или объектам — это уже не role does not exist, а нехватка прав, которую легко спутать. Убедитесь, что роль владеет базой или имеет к ней доступ. Дайте права на базу и объекты:

GRANT ALL PRIVILEGES ON DATABASE mydb TO myuser;
GRANT ALL ON ALL TABLES IN SCHEMA public TO myuser;

Если приложение будет создавать таблицы, роли нужны права на схему public (в новых версиях PostgreSQL права на создание в public по умолчанию урезаны). Часто удобнее сделать роль владельцем базы при её создании: CREATE DATABASE mydb OWNER myuser;. Разграничивайте права разумно — приложению обычно не нужен суперпользователь, достаточно прав на свою базу. Правильная выдача прав завершает настройку: роль не только существует и совпадает по имени, но и реально может работать с данными.

Причина 4: подключение к не той базе или кластеру

Бывает, что роль создана в одном кластере или на одном сервере PostgreSQL, а приложение подключается к другому — например, на сервере запущено два экземпляра на разных портах, или приложение по ошибке ходит на localhost, где своя пустая база, вместо нужного сервера. Проверьте, куда именно идёт подключение, и есть ли там ваша роль:

sudo -u postgres psql -p 5432 -c "\du"

Сверьте порт и хост из конфига приложения с тем, где вы создавали роль. Если экземпляров несколько, роль надо создать в том, к которому реально подключается приложение. Эта причина неочевидна, но встречается: всё сделано правильно, только не в том месте. Убедившись, что вы и приложение работаете с одним и тем же кластером и базой, вы устраните расхождение, из-за которого роль «есть, но её нет».

Как проверить, что подключение восстановлено

После создания роли и выдачи прав проверьте вход ровно так, как это делает приложение — тем же пользователем, к той же базе, на тот же хост и порт:

psql "host=127.0.0.1 port=5432 dbname=mydb user=myuser" -c "SELECT current_user;"

Успешный ответ с именем вашей роли подтверждает, что она существует, совпадает по имени и имеет доступ. Если снова ошибка — её текст уточнит, что не так: role does not exist вернёт вас к созданию или имени, а сообщение о правах или пароле укажет на следующий шаг. Проверка именно под параметрами приложения важна: подключение суперпользователем postgres может работать, а прикладная роль — падать, и тестировать нужно ту, что реально используется.

Профилактика: чтобы роли не терялись

Чтобы ошибка role does not exist не всплывала при переносах и развёртываниях, относитесь к ролям как к части настройки базы. При переносе приложения на новый сервер помните: дамп через pg_dump содержит данные базы, но роли — это объекты уровня кластера, и их создают отдельно (либо используют pg_dumpall для переноса ролей). Держите скрипт создания нужных ролей и выдачи прав вместе с проектом, чтобы развернуть базу с нуля одной командой и ничего не забыть.

Документируйте, какая роль к какой базе с какими правами относится, и используйте единый нижний регистр в именах, чтобы не спотыкаться о регистр и кавычки. Не давайте прикладным ролям избыточных прав — принцип наименьших привилегий и безопаснее, и понятнее. Тогда развёртывание на новом сервере проходит предсказуемо, а роли не «теряются» при миграциях. Аккуратное управление ролями превращает эту частую ошибку в разовую мелочь, которую вы устраняете за минуту.

Частые вопросы