Установка PostgreSQL 16: ошибки новичков и подключение

PostgreSQL 16 можно запустить примерно за 10 минут в Docker Desktop или Docker Engine, не меняя системные файлы и настройки операционной системы. В конце у вас будет база appdb, постоянное хранилище данных и рабочее подключение через psql. Ниже — путь для Ubuntu, macOS и Windows с Docker Desktop.

Что подготовить до установки

Нужен установленный Docker Desktop для Windows или macOS либо Docker Engine с Compose-плагином в Linux. Проверьте, что Docker отвечает на команды:

docker --version
docker run --rm hello-world

В первой строке должна появиться версия Docker. Вторая команда скачает небольшой образ и завершится сообщением от Docker. Если терминал сообщает, что команда не найдена, сначала установите Docker с официального сайта. PostgreSQL в этой статье — именно версии 16, заданной образом postgres:16.

Термин: контейнер — изолированный процесс с приложением и его зависимостями. Он не равен виртуальной машине: PostgreSQL работает внутри контейнера, а данные можно хранить в отдельном Docker volume1.

Сноска 1. Docker volume — управляемое Docker хранилище. Если удалить контейнер, volume обычно остаётся, поэтому база не исчезает вместе с контейнером.

Самая частая ошибка новичка — проверять только статус контейнера. Статус «running» означает, что процесс жив, но не всегда означает, что PostgreSQL уже закончил запуск.

Пошаговая установка PostgreSQL 16

1. Создайте хранилище. Оно нужно, чтобы данные пережили пересоздание контейнера.

   docker volume create pgdata

   Проверка: Docker выведет имя pgdata без сообщения об ошибке.

2. Запустите PostgreSQL. Команда публикует порт только на локальном компьютере. Значение YOUR_POSTGRES_PASSWORD замените на собственный пароль, но не публикуйте его в репозитории.

   docker run --name postgres16 --restart unless-stopped \
     -e POSTGRES_PASSWORD=YOUR_POSTGRES_PASSWORD \
     -e POSTGRES_DB=appdb \
     -p 127.0.0.1:5432:5432 \
     -v pgdata:/var/lib/postgresql/data \
     -d postgres:16

   Проверка: команда вернёт длинный идентификатор контейнера. Это ещё не проверка готовности базы.

3. Дождитесь готовности сервера.

   docker logs -f postgres16

   Остановите просмотр логов сочетанием Ctrl+C, когда увидите строку database system is ready to accept connections. Контейнер при этом продолжит работать.

4. Подключитесь через psql. Флаг -h 127.0.0.1 заставляет клиент подключаться по TCP к опубликованному порту, а не искать локальный Unix-сокет.

   docker exec -it postgres16 psql \
     -h 127.0.0.1 \
     -U postgres \
     -d appdb \
     -W

   После запроса Password: введите пароль из шага 2. Успешное подключение откроется приглашением appdb=#.

5. Проверьте соединение и базовые права.

   SELECT version();
   \conninfo
   CREATE TABLE test_connection (id integer PRIMARY KEY, note text);
   INSERT INTO test_connection (id, note) VALUES (1, 'ok');
   SELECT * FROM test_connection;

   Проверка: первая команда показывает PostgreSQL 16, \conninfo — базу, пользователя и адрес, а последний запрос возвращает строку с ok. Команды, начинающиеся с обратного слеша, относятся к клиенту psql, а не к SQL.

Частые ошибки при первом подключении

Connection refused

Сообщение вида connection refused означает, что по указанному адресу никто не принимает соединение. Проверьте, запущен ли контейнер:

docker ps
docker logs postgres16

Если контейнер не отображается в docker ps, посмотрите все контейнеры командой docker ps -a. Если база ещё запускается, дождитесь строки о готовности. Если в логах указан занятый порт, остановите программу, которая слушает 5432, или опубликуйте PostgreSQL на другом порту, например -p 127.0.0.1:5433:5432. В последнем случае клиенту нужно указывать -p 5433.

Порт занят

Docker покажет ошибку вроде Bind for 127.0.0.1:5432 failed: port is already allocated. Обычно PostgreSQL уже установлен в системе или другой контейнер использует этот порт. Это не означает, что сама база сломана.

Для второго экземпляра оставьте внутренний порт 5432, но измените внешний:

docker run --name postgres16-test \
  -e POSTGRES_PASSWORD=YOUR_POSTGRES_PASSWORD \
  -e POSTGRES_DB=appdb \
  -p 127.0.0.1:5433:5432 \
  -v pgdata-test:/var/lib/postgresql/data \
  -d postgres:16

В приложении тогда используйте хост 127.0.0.1 и порт 5433. Внутри Docker-сети другие контейнеры обращаются к PostgreSQL по внутреннему порту 5432, а не по внешнему 5433.

Role does not exist

Ошибка role "admin" does not exist появляется, когда в параметре -U указано имя, которого нет в базе. Переменная POSTGRES_PASSWORD создаёт пароль для пользователя postgres, а не произвольного пользователя admin.

Для первого входа используйте -U postgres. Пользователя приложения создавайте отдельно, когда базовое подключение уже проверено. Не меняйте POSTGRES_USER в уже существующем контейнере: переменные инициализации применяются только при создании пустого каталога данных.

Database does not exist

Сообщение database "myapp" does not exist означает, что сервер доступен, но базы с таким именем нет. В примере автоматически создаётся только appdb. Подключитесь к ней или создайте другую базу из консоли:

CREATE DATABASE myapp;

Команду выполняйте из соединения с существующей базой. Нельзя подключиться к несуществующей базе, чтобы создать её изнутри.

Password authentication failed

Ошибка password authentication failed for user "postgres" обычно связана с неверным паролем. Проверьте раскладку клавиатуры и не добавились ли пробелы. Если контейнер запускается с уже существующим volume, новая переменная POSTGRES_PASSWORD пароль не меняет: начальная настройка повторно не выполняется.

Для учебного окружения можно удалить контейнер вместе с volume и начать заново, но это удалит данные:

docker rm -f postgres16
docker volume rm pgdata

Не запускайте эти команды на рабочей базе без резервной копии.

Что проверить, если подключение всё ещё не работает

• Контейнер: docker ps -a показывает, не завершился ли процесс сразу после запуска.
• Логи: docker logs postgres16 содержат причину ошибки и момент готовности.
• Порт: параметры клиента должны совпадать с внешним портом из -p.
• Имя базы: -d appdb должно соответствовать значению POSTGRES_DB при первом запуске.
• Старые данные: существующий volume сохраняет прежнего пользователя, пароль и базы.

Если вы ставите PostgreSQL не в Docker, а пакетами операционной системы, названия службы и расположение конфигурации зависят от Linux-дистрибутива или Windows. Не смешивайте команды: контейнерный сервер и системный сервер могут одновременно занять порт 5432.

Что сделать после первого входа

Не подключайте приложение от имени postgres. Создайте отдельную роль с минимальными правами и отдельную базу для проекта. Для локальной разработки это можно сделать после проверки соединения; пароль храните в переменной окружения или менеджере секретов, а не в исходном коде.

Следующим шагом измерьте три вещи: время установления соединения, число активных подключений и объём данных в volume. Перед обновлением образа PostgreSQL проверьте совместимость версии и сделайте резервную копию. Самый простой локальный сценарий не заменяет резервное копирование и настройку доступа для продакшена.