Docker pgAdmin: как настроить GUI для PostgreSQL с помощью Docker Compose

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

pgAdmin 4 решает эти проблемы с помощью браузерного GUI, созданного специально для PostgreSQL. А запуск в Docker означает нулевую локальную установку. Достаточно запустить контейнер.

В этой статье я покажу, как настроить PostgreSQL и pgAdmin 4 с Docker Compose, соединить два контейнера и использовать инструменты pgAdmin — Query Tool, обозреватель схем и функции резервного копирования.

Чтобы следовать материалу, на вашей машине должны быть установлены и запущены Docker. Если вы впервые работаете с Docker Compose, прочитайте наше руководство о том, как он упрощает разработку с несколькими контейнерами.

Что такое pgAdmin 4?

pgAdmin 4 — это открытая, браузерная платформа администрирования и разработки для PostgreSQL. Доступ осуществляется через веб-браузер, поэтому ничего не нужно устанавливать как настольное приложение. Он предоставляет GUI для управления базами, выполнения запросов, изучения схем и работы с резервными копиями — без обращения к командной строке.

Официальный Docker-образ — dpage/pgadmin4, поддерживаемый командой разработчиков pgAdmin.

Запуск pgAdmin 4 в Docker имеет несколько реальных преимуществ перед локальной установкой. Во-первых, это портируемость — вся ваша среда базы данных хранится в файле docker-compose.yml, который можно поделиться с командой. Во-вторых, нет конфликтов версий — pgAdmin работает в собственном контейнере, полностью изолированном от остального на вашей машине. А когда закончите, docker compose down полностью всё очищает.

pgAdmin 4 по сравнению с другими GUI для PostgreSQL

GUI-инструментов для управления базами данных хватает. Вот как pgAdmin 4 выглядит на фоне двух популярных альтернатив.

pgAdmin 4 по сравнению с популярными альтернативами

DBeaver и TablePlus — хорошие инструменты, но ни у одного из них нет официального Docker-образа. Если ваш экземпляр PostgreSQL уже работает в Docker, pgAdmin 4 — отличный выбор: нужно лишь добавить один сервис в ваш docker-compose.yml, и всё запустится в одной сети.

Настройка окружения с Docker Compose

Самый быстрый способ запустить PostgreSQL и pgAdmin 4 вместе — это один файл docker-compose.yml. Если тема для вас новая, в нашем руководстве по Docker Compose разобраны основы. Здесь я сосредоточусь на специфике конфигурации pgAdmin.

Вот полный файл, который можно скопировать и вставить:

services:
  postgres:
    image: postgres:18
    container_name: postgres
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql
    networks:
      - pgnetwork

  pgadmin:
    image: dpage/pgadmin4:9.13
    container_name: pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: you@yourdomain.com
      PGADMIN_DEFAULT_PASSWORD: password
      PGADMIN_LISTEN_PORT: 5050 
    ports:
      - "5050:5050"                
    volumes:
      - pgadmin_data:/var/lib/pgadmin
    depends_on:
      - postgres
    networks:
      - pgnetwork

volumes:
  postgres_data:
  pgadmin_data:

networks:
  pgnetwork:

Поле depends_on говорит Docker Compose запустить контейнер postgres раньше pgadmin. Без него pgAdmin может стартовать до готовности PostgreSQL и не подключиться. Оно не ждёт полной «здоровости» PostgreSQL — лишь старта контейнера. Этого достаточно, чтобы избежать большинства гонок.

Переменные окружения pgAdmin 4

Требуются две переменные окружения:

• PGADMIN_DEFAULT_EMAIL — адрес электронной почты для входа в веб-интерфейс pgAdmin
• PGADMIN_DEFAULT_PASSWORD — пароль для этой учётной записи

Третья — необязательная, но её стоит указать:

• PGADMIN_LISTEN_PORT — порт, на котором pgAdmin слушает внутри контейнера. По умолчанию 80, но установка 5050 упрощает сопоставление портов.

При этом жёстко прописывать учётные данные в Compose-файле — плохая идея, особенно если файл попадёт в систему контроля версий. Перенесите их в файл .env.

Создайте файл .env в той же директории, что и docker-compose.yml:

POSTGRES_USER=admin
POSTGRES_PASSWORD=secret
POSTGRES_DB=mydb
PGADMIN_DEFAULT_EMAIL=admin@example.com
PGADMIN_DEFAULT_PASSWORD=secret

Затем используйте переменные в вашем Compose-файле:

# postgres
environment:
  POSTGRES_USER: ${POSTGRES_USER}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  POSTGRES_DB: ${POSTGRES_DB}
  
# pgadmin
environment:
  PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL}
  PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD}

Docker Compose подхватывает файлы .env при запуске команды, дополнительная настройка не требуется. Просто не забудьте добавить .env в .gitignore, и ваши учётные данные не попадут в репозиторий.

Тома и сохранность данных

Том, смонтированный в /var/lib/pgadmin, — это место, где pgAdmin хранит данные: сессии, сохранённые подключения к серверам и конфигурацию. Если убрать этот том из Compose-файла, вы будете терять всё это при каждом перезапуске контейнера.

В текущем Compose-файле используется именованный том, которым Docker управляет на вашей хост-машине. Данные переживают перезапуски контейнера, его пересоздание и обновления образа — пока вы явно не удалите том командой docker volume rm.

Запуск стека и доступ к pgAdmin 4

Имея готовый docker-compose.yml, запустить стек можно одной командой:

docker compose up -d

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

docker ps

Вы должны увидеть postgres и pgadmin со статусом Up.

Статус контейнеров

Если что-то выглядит странно, посмотрите логи pgAdmin:

docker logs pgadmin

Здоровый старт выглядит так:

Логи запуска pgAdmin

Если видите ошибку, скорее всего, это одна из трёх:

• Сбой аутентификации по паролю: ваша PGADMIN_DEFAULT_PASSWORD отсутствует или неверно указана в файле .env

• Порт уже занят: что-то ещё слушает порт 5050; измените хост-порт в Compose-файле

• Нет такого файла или каталога: неверный путь к тому или у контейнера нет прав на запись

Когда оба контейнера запущены и логи чистые, откройте браузер и перейдите на http://localhost:5050:

Страница входа pgAdmin

Войдите с почтой и паролем, указанными в PGADMIN_DEFAULT_EMAIL и PGADMIN_DEFAULT_PASSWORD. Вы попадёте на панель pgAdmin и сможете зарегистрировать ваш сервер PostgreSQL:

Главная страница pgAdmin

Подключение pgAdmin 4 к вашему контейнеру PostgreSQL

В боковой панели pgAdmin щёлкните правой кнопкой по Servers — Register — Server. Откроется диалог с двумя вкладками, которые нужно заполнить: General и Connection.

Вкладка General

Дайте серверу осмысленное имя — например, local-dev-postgres. Это лишь метка внутри pgAdmin, выбирайте то, что удобно в вашем окружении.

Регистрация сервера — вкладка General

Вкладка Connection

Не используйте здесь localhost. 

Внутри сети Docker localhost — это сам контейнер, а не ваша хост-машина и не контейнер с PostgreSQL. У Docker есть собственный внутренний DNS, который разрешает имена контейнеров по названиям сервисов из вашего docker-compose.yml. Поэтому если ваш сервис PostgreSQL назван postgres, используйте его как имя хоста.

Заполните поля так:

• Host name/address: postgres (имя сервиса из docker-compose.yml)

• Port: 5432

• Maintenance database: значение POSTGRES_DB из вашего Compose-файла (например, mydb)

• Username: значение POSTGRES_USER (например, admin)

• Password: значение POSTGRES_PASSWORD

Нажмите Save. 

Регистрация сервера — вкладка Connection

Если всё указано верно, сервер появится в боковой панели, вы сможете развернуть его и увидеть свои базы данных:

Сервер успешно зарегистрирован

Это значит, что подключение установлено.

Использование Query Tool

Теперь, когда вы подключены, я покажу основы pgAdmin 4 и Postgres в целом.

Откройте Query Tool, выбрав в верхнем меню Tools - Query Tool. Интерфейс состоит из трёх панелей:

• Editor: здесь вы пишете SQL
• Data Output: здесь появляются результаты после выполнения запроса
• Messages: здесь PostgreSQL отправляет статусные сообщения, ошибки и информацию о выполнении

Query Tool

Написание и выполнение SQL

Давайте создадим простую таблицу orders и добавим немного данных. Каждый блок можно запускать кнопкой Play или клавишей F5 — это горячая клавиша.

Выполните это, чтобы создать таблицу:

CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    customer_name VARCHAR(100) NOT NULL,
    product VARCHAR(100) NOT NULL,
    quantity INT NOT NULL,
    order_date DATE DEFAULT CURRENT_DATE
);

Вставьте несколько строк:

INSERT INTO orders (customer_name, product, quantity)
VALUES
    ('Alice Johnson', 'Wireless Keyboard', 2),
    ('Bob Smith', 'USB-C Hub', 1),
    ('Carol White', 'Mechanical Keyboard', 3);

А теперь просто выберите данные:

SELECT * FROM orders;

Запрос данных

Результаты отображаются в панели Data Output в виде таблицы. Можно сортировать столбцы, менять их ширину и копировать строки прямо из сетки.

Чтение визуального плана запроса

Чтобы понять, что происходит «под капотом» при выполнении запроса, выполните EXPLAIN ANALYZE для вашего SELECT:

EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_name = 'Alice Johnson';

Результаты Explain Analyze

В панели Data Output вы увидите «сырой» вывод. Но в pgAdmin есть вариант получше. Нажмите кнопку Explain на панели инструментов — и pgAdmin отобразит план запроса в виде интерактивного графа.

План запроса в виде графа

Сейчас пример простой, но при соединении таблиц или более сложных агрегациях граф даст гораздо больше информации.

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

Управление схемой базы данных

Боковая панель pgAdmin даёт полный обзор структуры базы — и позволяет изменять её через GUI.

Дерево выглядит так: Servers — ваш сервер — Databases — ваша база — Schemas — public — Tables. Разверните любую таблицу, и вы увидите её Columns, Indexes и Constraints в виде дочерних узлов. Нажмите на любой из них, чтобы посмотреть детали в правой панели.

Создание и изменение таблиц

Чтобы создать новую таблицу, щёлкните по Tables в вашей схеме правой кнопкой и выберите Create — Table. Откроется диалог с несколькими вкладками.

Создание таблиц

Во вкладке General задаётся имя таблицы. Переключитесь на вкладку Columns, чтобы добавить столбцы — в каждой строке можно указать имя столбца, тип данных, длину и допускается ли NULL. Вкладка Constraints отвечает за первичные ключи, внешние ключи и уникальные ограничения.

Чтобы добавить индекс к существующей таблице, разверните таблицу в боковой панели, щёлкните правой кнопкой по Indexes и выберите Create — Index. Выберите столбцы и тип индекса — по умолчанию btree, и он подходит в большинстве случаев.

Создание индекса

Резервное копирование и восстановление

Чтобы сделать резервную копию базы, перейдите в Tools — Backup. Нужно выбрать формат:

• Custom: сжатый двоичный формат; самый гибкий и лучший выбор в большинстве случаев, так как позволяет восстанавливать отдельные таблицы
• Plain: обычный SQL-скрипт, который можно открыть в любом текстовом редакторе
• Tar: несжатый архив; встречается реже, но полезен в некоторых сценариях восстановления

После выбора формата и пути назначения pgAdmin запускает pg_dump в фоне и сохраняет файл на вашу локальную машину.

Создание резервной копии

Для восстановления перейдите в Tools — Restore, выберите файл резервной копии и укажите целевую базу данных.

Восстановление из резервной копии

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

Рекомендации по запуску pgAdmin 4 в Docker

Запустить pgAdmin 4 — одно, а вот поддерживать его стабильную работу — другое. Вот несколько практических советов.

Не храните учётные данные в Compose-файле

Если ваш docker-compose.yml попадёт в систему контроля версий — а так обычно и бывает — хардкоженные пароли уйдут вместе с ним. Используйте файл .env для учётных данных и добавьте его в .gitignore. В проде идите дальше и применяйте Docker secrets, которые монтируют чувствительные значения как файлы, а не переменные окружения.

Никогда не открывайте порт pgAdmin публично

По умолчанию Docker привязывает порты к 0.0.0.0, то есть ко всем сетевым интерфейсам, включая публичные. На удалённом сервере это делает ваш экземпляр pgAdmin доступным из интернета. Привяжите явно к 127.0.0.1:

ports:
  - "127.0.0.1:5050:5050"

Так pgAdmin будет доступен только с самого сервера. Для удалённого доступа используйте SSH-туннель или реверс-прокси.

Фиксируйте теги образов

Если использовать dpage/pgadmin4:latest, при следующем docker compose pull подтянется новая версия. Она может работать иначе, сломать конфигурацию или привнести неожиданные изменения. Используйте конкретный тег, например dpage/pgadmin4:9.13, чтобы вся команда работала на одной версии.

Предварительно загружайте подключения сервера с servers.json

Если у всей команды общий Compose-набор, не заставляйте каждого вручную регистрировать сервер PostgreSQL после запуска стека. pgAdmin поддерживает файл servers.json, который заполняет подключения при старте. Смонтируйте его в контейнер так:

volumes:
  - ./servers.json:/pgadmin4/servers.json

Вот как выглядит минимальный servers.json:

{
  "Servers": {
    "1": {
      "Name": "local-dev-postgres",
      "Group": "Servers",
      "Host": "postgres",
      "Port": 5432,
      "MaintenanceDB": "mydb",
      "Username": "admin",
      "SSLMode": "prefer"
    }
  }
}

Сервер появится при старте pgAdmin — ручная настройка не нужна.

Итоги

В этой статье мы с нуля настроили pgAdmin 4 в Docker. Вы написали Docker Compose-файл, который поднимает вместе PostgreSQL и pgAdmin 4, соединили контейнеры через внутренний DNS Docker и использовали ключевые функции pgAdmin — Query Tool, обозреватель схем и процесс резервного копирования/восстановления.

Ключевой принцип здесь — воспроизводимость. 

Файлы docker-compose.yml, servers.json и .env — всё, что нужно, чтобы передать коллеге полностью настроенную среду базы данных. Так проблема «у меня работает» больше не возникнет.

Чтобы глубже разобраться в Docker и контейнеризации, посмотрите наш курс Intermediate Docker. В нём много полезного о многостадийных сборках, сетях и подробный разбор Compose.