Как запустить PostgreSQL в Docker: compose, hub, image, run

PostgreSQL — это мощная система управления базами данных (СУБД) на открытом коде. Она подходит для работы с большими объемами данных, поддерживает стандарт SQL и расширяет его множеством дополнительных возможностей.

Преимущества PostgreSQL:

• Свободное распространение — систему можно бесплатно использовать, модифицировать и адаптировать под свои нужды. 

• Обогащение функциональности — PostgreSQL позволяет добавлять новые типы данных и дополнительные опции благодаря системе расширений. 

• Кроссплатформенность — проект поддерживается практически всеми операционными системами (ОС). 

• Защита данных — PostgreSQL располагает инструментами для обеспечения безопасности конфиденциальной информации. 

• Масштабирование — продукт соответствует требованиям корпоративных систем и может адаптироваться под растущие нагрузки. 

• Отказоустойчивость — система поддерживает механизмы репликации и кластеризации. 

• Работа с неструктурированными данными — PostgreSQL поддерживает инструменты работы с информацией разных форматов, которая разрозненно хранится в разных хранилищах. 

PostgreSQL успешно применяется как в небольших проектах, так и в масштабных корпоративных решениях. 

Docker-контейнеры — изолированные программные среды, в которых можно запускать приложения вместе со всеми необходимыми библиотеками, зависимостями и настройками. Они работают поверх общей операционной системы, но при этом не мешают друг другу. 

Контейнеры легко создавать, перемещать и запускать на разных компьютерах. Работать они будут везде одинаково. Такой подход сильно упрощает совместную разработку, тестирование и развертывание приложений. 

Чтобы связать контейнерное приложение в Docker с PostgreSQL, используется инструмент Docker Compose. Он позволяет управлять элементами проекта с помощью единого файла конфигурации. 

Установка Docker и Docker compose

Разберем установку на примере Ubuntu. Актуальный гайд Docker можно найти по адресу: https://docs.docker.com/engine/install/ubuntu/. 

Сначала обновите систему:

Установите пакеты, которые помогают системе работать с Docker через HTTPS:

Добавьте ключ Docker и репозиторий:

Обновите список пакетов и установите Docker вместе с плагином Compose:

Проверьте, что инструменты работают:

Современная версия Docker включает Compose как плагин, поэтому отдельная установка docker compose (через curl) больше не требуется.

Если вы не хотите самостоятельно настраивать контейнеры, тома, резервные копии и мониторинг, обратите внимание на сервис Evolution Managed PostgreSQL от Cloud.ru. Это полностью управляемая база данных PostgreSQL с удобным веб-интерфейсом, автоматическими бэкапами, масштабированием в пару кликов и встроенным мониторингом. Вы получаете готовый кластер без необходимости администрировать Docker-окружение.

Образ (image) — это шаблон, из которого создаются контейнеры. В нем предустановлено все необходимое — СУБД PostgreSQL, настройки окружения и базовые утилиты.

Получение образа PostgreSQL — процесс загрузки из Docker Hub или другого репозитория. Полученный образ ляжет в основу создания контейнера с базой данных.

Поиск образа на Docker Hub

Образ PostgreSQL ищите в официальном каталоге Docker Hub. В строке поиска введите postgres. Первым в списке результатов будет официальный образ PostgreSQL. Вы без проблем его найдете — он помечен как Official Image. Многие используют именно его, поскольку он поддерживается разработчиками PostgreSQL и регулярно обновляется. Нужную версию образа можно выбрать с помощью тегов. Рекомендуется указывать конкретную версию, например postgres:17 или postgres:16.4. Тег latest лучше не использовать в рабочих проектах.

Что из себя представляет образ PostgreSQL

Образ поддерживает несколько переменных окружения. Они нужны, чтобы настроить базу при запуске контейнера. Главные переменные:

• POSTGRES_USER — имя пользователя;

• POSTGRES_PASSWORD — пароль;

• POSTGRES_DB — имя базы, которая будет создана при старте.

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

PostgreSQL в Docker можно развернуть двумя способами:

• из командной строки (CLI) — для быстрых тестов и разработки;

• через Docker Compose — для воспроизводимых конфигураций, работы с несколькими сервисами и боевых сред.

Далее рассмотрим оба подхода.

Базовый запуск контейнера PostgreSQL с минимальной конфигурацией 

Для базового запуска контейнера полезна команда docker run. Главное — установить пароль для суперпользователя postgres через переменную окружения POSTGRES_PASSWORD.

Команда:

Что делает docker run:

• -d запускает контейнер в фоновом режиме.

• --name my-postgres дает контейнеру имя.

• -e POSTGRES_PASSWORD=mysecretpassword — устанавливает пароль для суперпользователя. Для тестирования можно указать пароль прямо в команде. Для боевого окружения лучше вынести учетные данные в отдельный файл (например, .env) и использовать --env-file.

• postgres указывает, какой образ Docker использовать. 

Приведенная выше команда работает в командной строке Linux. В Docker Compose синтаксис будет отличаться.

Проброс портов и томов

Чтобы работать с PostgreSQL, необходимо сделать две вещи:

1. Пробросить порт — открыть доступ к базе данных с вашего компьютера.

2. Использовать том — примонтировать папку с хостовой файловой системы в контейнер. Это нужно, чтобы данные базы не пропадали при удалении или обновлении контейнера. Вы указываете конкретную директорию на хосте (или именованный том), и PostgreSQL сохраняет туда все файлы.

Для этого в команду docker run добавьте флаги -p (порт) и -v (том):

• -p 5432:5432 — связывает порт 5432 на вашем компьютере с портом 5432 внутри контейнера;

• -v pgdata:/var/lib/postgresql/data — создает именованный том pgdata. Данные будут храниться в /var/lib/docker/volumes/pgdata. Если нужна конкретная папка на хосте, укажите абсолютный путь: -v /home/user/pgdata:/var/lib/postgresql/data.

Compose позволит определить и запустить PostgreSQL вместе с другими сервисами. 

Конфигурация Docker Compose

Для развертывания PostgreSQL через Docker Compose создайте файл docker-compose.yml, где описан сервис базы данных с постоянным томом для хранения данных, переменными окружения для инициализации и настройками сети. 

Посмотрите на пример ниже, который включает сервис pgAdmin как опцию. Это необязательный элемент — для работы PostgreSQL достаточно только сервиса db. pgAdmin приведен для удобства визуального управления.

Еще пример файла — на скрине. В нем описание не такое подробное. 

Какие разделы есть в файле:

Services — главный раздел с описанием каждого контейнера.

1. image — используемый образ Docker, например, postgres:17 или postgres:16.4;

2. build — путь к Dockerfile, который нужен, если образ будет собран локально;

3. ports — проброс портов (например, "8080:80");

4. environment — переменные окружения, например, пароли для базы данных;

5. volumes — в секции services подключает тома к контейнеру, в корневой секции — определяет именованные тома.

Networks — определяет пользовательские сети. Docker Compose автоматически создает общую сеть для всех сервисов, позволяя им обращаться друг к другу по имени.

Файл docker-compose.yml гарантирует, что приложение будет запущено с одинаковой конфигурацией на любой машине — на компьютере разработчика, на тестовом сервере или в продакшене.

В том же каталоге, что и docker-compose.yml, находится файл .env (db.env). В нем задаются переменные окружения для работы контейнеров, запущенных с помощью Docker Compose. Пример файла:

Чтобы избежать путаницы, не дублируйте переменные окружения в секции environment файла docker-compose.yml, если вы используете env_file. Используйте либо тот, либо другой способ — но не оба одновременно для одних и тех же переменных.

Запуск и управление контейнерами с помощью Docker Compose

В таблице — основные команды для управления контейнерами. 

Использовать Docker Compose очень удобно, поскольку с помощью одной команды docker compose up -d можно запустить систему, состоящую из множества сервисов.

Альтернатива командной строке: Portainer. Если вы не хотите запоминать команды Docker Compose, установите Portainer — веб-интерфейс для управления контейнерами, образами, томами и сетями. В нем можно развернуть PostgreSQL буквально в несколько кликов, а также мониторить состояние сервисов. Portainer сам запускается как контейнер и работает поверх Docker.

Конфигурация PostgreSQL в контейнере Docker осуществляется двумя основными способами — через монтирование конфигурационных файлов для тонкой настройки и через переменные окружения. 

Управление конфигурационными файлами

Это лучший способ, если вам нужно задать много пользовательских параметров (например, max_connections, shared_buffers и т.д.). Стандартные переменные окружения в таких настройках бессильны. 

Создайте на своем компьютере файл с нужными настройками. Например, файл custom.conf с таким содержанием:

Можно использовать флаг -v или секцию volumes в docker-compose.yml, чтобы пробросить ваш файл внутрь контейнера. Так вы указываете PostgreSQL, что нужно применить этот файл. 

Пример работы с помощью docker-compose.yml:

Можно запустить файл с помощью docker run:

Ограничение ресурсов контейнера

Для продакшен-окружения обязательно ограничивайте CPU и память, которые может использовать контейнер с PostgreSQL. Иначе один контейнер может «уронить» хост-машину.

В docker run:

В docker-compose.yml:

Работа с переменными окружения

Переменные окружения (-e) в образе PostgreSQL в основном используются для первичной инициализации базы данных. Они работают только при первом запуске контейнера, когда создается пустая база данных. При последующих запусках переменные игнорируются. 

Основные переменные: 

• POSTGRES_PASSWORD — устанавливает пароль для пользователя postgres.

• POSTGRES_USER — меняет имя суперпользователя с postgres на другое по вашему выбору. 

• POSTGRES_DB — создает базу данных с указанным именем сразу после запуска.

Пример docker run с инициализацией: 

Эта команда создаст пользователя myuser с паролем mypass и сразу подготовит базу mydb. Ее владельцем будет новый пользователь myuser.

Переменные окружения не позволят вам настроить параметры работы сервера. Для более тонких настроек придется создавать пользовательский конфигурационный файл postgresql.conf либо передавать настройки прямо в команде запуска:

Предлагаем методы подключения к запущенному экземпляру PostgreSQL с хоста или из других контейнеров. 

Подключение с хоста

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

При запуске контейнера вы должны с помощью флага -p пробросить порт. Например, -p 5432:5432 связывает порт 5432 вашего компьютера с портом 5432 внутри контейнера.

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

• Хост: localhost (или 127.0.0.1)

• Порт: 5432 (или тот порт, который вы указали первым в команде -p)

• Пользователь: postgres (или тот, что задан вами в POSTGRES_USER)

• Пароль: тот, что вы указали в POSTGRES_PASSWORD

Подключение с другого устройства в локальной сети. Если нужно подключиться к PostgreSQL с другого компьютера в той же локальной сети, используйте IP-адрес хостовой машины, на которой запущен контейнер. Например:

• Хост: 192.168.1.100 (IP вашего сервера с Docker)

• Порт: 5432 (или проброшенный порт)

Убедитесь, что брандмауэр на хостовой машине разрешает входящие подключения на этот порт.

Подключение из другого контейнера 

Этот способ актуален, если приложение тоже находится в Docker, и ему нужно обнаружить контейнер с базой данных. Главное, чтобы приложение и PostgreSQL находились в одной пользовательской сети Docker и имели имена. 

Создайте сеть:

Запустите PostgreSQL в этой сети. Обязательно укажите имя контейнера (--name) и сеть (--network).

Запустите приложение внутри сети:

Какие параметры подключения вы увидите внутри приложения: 

• Хост my-postgres-db (имя контейнера PostgreSQL)

• Порт 5432 (внутренний порт PostgreSQL)

• Пользователь postgres, для которого можно задать собственное имя

• Пароль mysecretpassword — секретный пароль

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

То же самое в Docker Compose. Сеть создавать не нужно — Compose создает ее автоматически. Достаточно описать оба сервиса в одном файле:

Внутри контейнера app подключение к БД доступно по имени сервиса: db:5432.

Контейнеры Docker не сохраняют состояние (stateless). При удалении контейнера данные внутри него теряются, если не использовать тома.

Для продакшен используйте отдельный каталог на хосте, например:

Или:

Это упрощает бэкапы и перенос данных между серверами.

Затем используйте полную команду запуска контейнера с томом:

Проверка, что данные сохраняются:

База demo останется на месте.

Итоги

Из статьи вы узнали:

• как установить Docker + Compose одной командой;

• почему не стоит использовать latest и как выбирать версию PostgreSQL;

• разницу между запуском через docker run и docker compose;

• как пробрасывать порты и монтировать тома для сохранения данных;

• как ограничивать CPU и память для контейнера;

• как подключаться к PostgreSQL с хоста, из локальной сети и из другого контейнера;

• что такое Portainer как альтернатива командной строке.

Этих знаний достаточно для безопасного и воспроизводимого развертывания PostgreSQL в Docker на любом окружении.