PostgreSQL ― это объектно-реляционная система управления базами данных с открытым исходным кодом, которая используется для хранения и обработки данных в веб-приложениях, корпоративных системах и аналитических платформах.
Она поддерживает сложные запросы, транзакции, расширения, работу с JSON, геоданными и большими объемами информации, оставаясь при этом стабильной и предсказуемой в работе. За счет строгого соблюдения стандартов SQL и активного развития сообщества PostgreSQL давно вышла за рамки обычной БД и стала полноценной платформой для работы с данными.
Зачем запускать PostgreSQL в Docker
В практической разработке PostgreSQL часто разворачивают не только на серверах, но и в локальной среде ― для тестирования, отладки и обучения. При этом установка и настройка базы данных напрямую в операционной системе может занимать время и требовать учета версий, зависимостей и возможных конфликтов с уже установленными программами. Поэтому PostgreSQL все чаще запускают в изолированной среде с заранее заданными настройками.
Контейнер позволяет запустить базу данных без сложной установки и без изменений в системе. PostgreSQL можно быстро поднять, остановить или удалить, не оставляя лишних файлов и настроек. Одна и та же конфигурация будет работать одинаково на разных компьютерах, что удобно при работе в команде и переносе проекта.
В локальной разработке это особенно полезно: база данных запускается за несколько секунд, легко пересоздается и не мешает другим проектам. В результате работа с PostgreSQL становится проще и предсказуемее.
Подготовка к установке
Для установки PostgreSQL в контейнере подготовьте рабочее окружение и убедитесь, что выполнены основные требования:
- Есть сервер или виртуальная машина под управлением Linux, например Ubuntu 24.04; допускается использование других дистрибутивов Linux, которые поддерживают Docker и Docker Compose.
- При отсутствии собственного сервера можно арендовать облако в Рег.облако ― подойдет для разработки, тестирования и рабочих проектов.
- Есть установленный Docker для запуска и управления контейнерами и Docker Compose для удобной работы с конфигурациями из нескольких сервисов.
- Есть доступ к серверу по SSH и права, которые позволяют устанавливать и настраивать программное обеспечение.
Если у вас не установлены Docker и Docker Compose, следуйте нашей инструкции.
Установка Docker и Docker Compose в Ubuntu 24.04
Установим Docker и Docker Compose из официального репозитория. Все команды ниже выполните от имени root-пользователя либо от обычного пользователя с правами sudo.
Сначала обновите списки пакетов и установите вспомогательные утилиты, которые понадобятся для работы с репозиториями и ключами:
apt update && apt -y install ca-certificates curl
Создайте каталог для хранения ключей репозиториев и задайте для него корректные права доступа:
install -m 0755 -d /etc/apt/keyrings
Скачайте GPG-ключ официального репозитория Docker. Он используется для проверки подлинности пакетов:
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
Назначьте права доступа на скачанный ключ:
chmod a+r /etc/apt/keyrings/docker.asc
Добавьте официальный репозиторий Docker в систему. Для Ubuntu 24.04 автоматически будет использовано кодовое имя дистрибутива:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
tee /etc/apt/sources.list.d/docker.list > /dev/null
Обновите списки пакетов и установите Docker вместе с необходимыми компонентами, включая плагин Docker Compose:
apt update && apt -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Проверьте, что Docker Compose установлен корректно, выполнив команду:
docker compose version
Если версия утилиты отображается, значит установка прошла успешно и система готова к дальнейшей настройке PostgreSQL.
Описание образа PostgreSQL
Компания PostgreSQL Global Development Group поддерживает официальный образ PostgreSQL, который предназначен для запуска базы данных в контейнерах. Образ размещен в репозитории Docker Hub и регулярно обновляется вместе с выходом новых версий СУБД и исправлений безопасности. Подробная техническая документация и примеры конфигураций также доступны в репозитории на GitHub, где описаны особенности и сценарии использования образа.
Официальный образ рассчитан на стабильную работу PostgreSQL и используется как в локальной разработке, так и на серверах. Настройка базы данных выполняется на этапе запуска контейнера с помощью переменных окружения, что упрощает управление пользователями, базами данных и параметрами инициализации.
Образ PostgreSQL поддерживает широкий набор аппаратных архитектур, благодаря чему может использоваться на разных платформах. Актуальный список поддерживаемых архитектур зависит от версии образа и указан в репозитории Docker Hub.
В процессе запуска контейнера PostgreSQL использует набор встроенных переменных окружения, которые позволяют управлять начальной настройкой базы данных без ручного вмешательства:
| Переменная окружения | Назначение |
|---|---|
| POSTGRES_USER | Создает пользователя для подключения к базе данных и базу данных с тем же именем. При отсутствии переменной создается пользователь postgres |
| POSTGRES_PASSWORD | Задает пароль пользователя базы данных. Переменная обязательна ― без нее контейнер не запустится и завершит работу |
| POSTGRES_DB | Создает отдельную базу данных с указанным именем. При отсутствии переменной используется имя пользователя |
| POSTGRES_INITDB_ARGS | Передает дополнительные параметры в процесс инициализации базы данных |
| POSTGRES_INITDB_WALDIR | Указывает каталог для хранения журнала транзакций PostgreSQL. |
| POSTGRES_HOST_AUTH_METHOD | Определяет метод аутентификации пользователей при подключении к базе данных |
| PGDATA | Задает директорию для хранения файлов базы данных внутри контейнера |
Быстрый запуск PostgreSQL в Docker
Начнем с самого простого варианта ― запуска PostgreSQL с минимальной конфигурацией. Этот способ подойдет для знакомства с образом, тестирования или быстрого развертывания базы данных без дополнительных настроек.
- Запустите контейнер PostgreSQL с помощью команды ниже. Она создает и запускает контейнер с базой данных 16-й версии:
docker run --name postgres_basic \
-e POSTGRES_PASSWORD=StrongPass_123 \
-d postgres:17
В этой команде имя контейнера задается через параметр --name. Оно используется для удобства управления и не является обязательным. При его отсутствии Docker присвоит контейнеру имя автоматически.
Переменная окружения POSTGRES_PASSWORD задает пароль для пользователя postgres. Эта переменная обязательна для запуска контейнера PostgreSQL. При ее отсутствии контейнер завершит работу с ошибкой и перейдет в состояние Exited.
Ключ -d запускает контейнер в фоновом режиме. Терминал при этом остается доступным для дальнейшей работы. Без этого параметра контейнер будет работать в режиме переднего плана и завершится при закрытии сессии.
В конце команды указывается имя образа и его тег ― postgres:17. Тег 17 означает использование семнадцатой версии PostgreSQL. Явное указание версии важно с точки зрения стабильности и безопасности. Тег latest не рекомендуется, так как он может указывать на неподходящую или нестабильную версию образа.
- Убедитесь, что контейнер запущен. Для этого выполните команду:
docker ps
В списке должен отображаться контейнер с именем postgres_basic и статусом Up.
- Подключитесь к запущенному экземпляру PostgreSQL через утилиту psql внутри контейнера:
docker exec -it postgres_basic psql -h localhost -U postgres -p 5432
Команда psql запускает интерактивную оболочку PostgreSQL. Параметр -h localhost указывает, что подключение выполняется к базе данных внутри текущего контейнера. Пользователь postgres используется по умолчанию, а порт 5432 является стандартным для PostgreSQL.
После успешного выполнения команды вы попадете в консоль psql и сможете выполнять SQL-запросы к базе данных.
Запуск PostgreSQL через Docker Compose
Помимо запуска СУБД с помощью команды docker run в standalone-режиме, когда используется один контейнер, PostgreSQL удобно запускать через Docker Compose. Этот способ особенно полезен, если база данных является частью проекта и должна запускаться вместе с другими сервисами.
Пример файла docker-compose.yml для запуска PostgreSQL:
version: '3.9'
services:
db:
image: postgres:17
ports:
- 5432:5432
restart: always
environment:
POSTGRES_USER=new_user
POSTGRES_PASSWORD=StrongPass_123
POSTGRES_DB=app_db
В этом примере будет запущен PostgreSQL версии 17 с проброшенным портом 5432, который используется по умолчанию. Docker автоматически создаст том для хранения данных базы, и внутри контейнера они будут размещены в каталоге /var/lib/postgresql/data. Благодаря этому данные сохранятся даже при перезапуске контейнера.
При старте контейнера создается пользователь с именем new_user, для него задается пароль StrongPass_123, а также создается база данных app_db. Все параметры инициализации задаются через переменные окружения, что упрощает управление конфигурацией и делает ее наглядной.
Для запуска PostgreSQL выполните команду:
docker compose up -d
Ее нужно запустить из директории, в которой расположен файл docker-compose.yml. В результате контейнер будет запущен в фоновом режиме, а PostgreSQL станет доступен для подключения по указанному порту.
Настройка PostgreSQL в Docker
Запуск контейнера PostgreSQL решает задачу быстрого развертывания, но для реальной работы обычно требуется настроить доступ извне, хранение данных, а иногда и конфигурацию сервера.
Доступ к PostgreSQL извне контейнера
Контейнер с PostgreSQL по умолчанию изолирован и доступен только внутри сети Docker. Подключения с хостовой системы или с других серверов в этом режиме невозможны. Чтобы разрешить внешние подключения, необходимо настроить сопоставление портов между контейнером и хостовой операционной системой.
Для открытия доступа используется параметр -p, который указывается при запуске контейнера. Он задает, какой порт на хосте будет связан с портом сервиса внутри контейнера. Общий формат выглядит следующим образом:
-p портхоста:портконтейнера
PostgreSQL по умолчанию использует порт 5432, поэтому чаще всего его сопоставляют с таким же портом на хосте. Пример запуска контейнера с открытым доступом к базе данных:
docker run --name postgres_public \
-p 5432:5432 \
-e POSTGRES_USER=db_admin \-e POSTGRES_PASSWORD=StrongPass_123 \
-e POSTGRES_DB=main_db \
-d postgres:17
В результате PostgreSQL станет доступен по IP-адресу сервера и порту 5432. Подключение можно выполнять как с хостовой машины, так и с другого сервера, используя любой клиент для работы с PostgreSQL, например DBeaver или psql.
При использовании удаленного доступа стоит учитывать сетевые ограничения и правила безопасности. Ограничьте доступ к порту на уровне файрвола и используйте сложные пароли для пользователей базы данных.
Использование собственной конфигурации PostgreSQL
Стандартных настроек PostgreSQL бывает недостаточно, особенно при работе с высокой нагрузкой или нестандартными требованиями к логированию и памяти. В контейнере PostgreSQL можно использовать собственный файл конфигурации, не изменяя сам образ и не пересобирая его.
Файл конфигурации размещается на хостовой операционной системе и монтируется внутрь контейнера при запуске. Для этого применяется опция -v, которая позволяет связать файл на хосте с файлом внутри контейнера. За счет этого конфигурация сохраняется даже при удалении контейнера.
Основной конфигурационный файл PostgreSQL называется postgresql.conf.
Пример запуска контейнера с использованием собственного конфигурационного файла:
docker run -d --name postgres_custom_config \
-v "$PWD/my-postgres.conf":/etc/postgresql/postgresql.conf \
-e POSTGRES_PASSWORD=StrongPassword12345 \
postgres:17 \
-c config_file=/etc/postgresql/postgresql.conf
В этом примере файл my-postgres.conf, расположенный в текущем каталоге хостовой системы, подключается внутрь контейнера по пути /etc/postgresql/postgresql.conf. Параметр -c config_file=… указывает PostgreSQL использовать именно этот файл при запуске.
Таким же способом можно подключать и другие конфигурационные файлы, а также настраивать различные сервисы, работающие в контейнерах.
Использование языковых стандартов ― локаль
PostgreSQL поддерживает работу с языковыми стандартами, или локалями. Локаль влияет на сортировку строк, сравнение символов, форматирование дат и чисел. Корректная настройка локали особенно важна при работе с национальными алфавитами и текстовыми данными.
Один из способов задать локаль ― создать собственный образ PostgreSQL на базе официального. В этом случае нужная локаль добавляется на этапе сборки образа. Ниже приведен пример Dockerfile с добавлением русской локали:
FROM postgres:17
RUN localedef -i ru_RU -c -f UTF-8 -A /usr/share/locale/locale.alias ru_RU.UTF-8
ENV LANG ru_RU.utf8
В результате контейнер будет запускаться с установленной локалью ru_RU.UTF-8, которая будет использоваться PostgreSQL при инициализации базы данных.
Настроить локаль можно и без сборки собственного образа, используя готовые образы на базе Alpine Linux. В этом случае локаль задается через переменные окружения и параметры инициализации PostgreSQL при запуске контейнера:docker run -d \
-e LANG=ru_RU.utf8 \
-e POSTGRES_INITDB_ARGS="--locale-provider=icu --icu-locale=ru-RU" \
-e POSTGRES_PASSWORD=782LMwVX8# \
postgres:17-alpine
Выбранная локаль применяется только при первой инициализации базы данных. Изменение локали для уже созданной базы данных невозможно без ее пересоздания, поэтому параметры локали стоит задавать на этапе первого запуска контейнера.
Работа с томами: хранение данных вне контейнера
Контейнеры Docker можно в любой момент остановить, удалить и пересоздать. При этом все данные, которые находятся внутри контейнера, будут потеряны. Для PostgreSQL это критично, поэтому файлы базы данных выносят за пределы контейнера и хранят на хостовой системе. Для этого используется механизм томов Docker.
Том позволяет сохранить данные независимо от жизненного цикла контейнера. Даже если контейнер будет удален, информация в базе данных останется и может быть использована повторно при новом запуске PostgreSQL.
Создание тома Docker для PostgreSQL
Создайте том для базы данных:
docker volume create pg_storage
Посмотрите информацию о созданном томе и его расположение:
docker volume inspect pg_storage
По умолчанию Docker размещает тома в каталоге /var/lib/docker/volumes.
Запустите контейнер PostgreSQL и подключите созданный том к каталогу /var/lib/postgresql/data, в котором PostgreSQL хранит файлы базы данных:
docker run -d \
--name postgres_volume_test \
-e POSTGRES_PASSWORD=StrongPass_456 \
-v pg_storage:/var/lib/postgresql/data \
postgres:17
Подключитесь к PostgreSQL и создайте тестовые данные:
docker exec -it postgres_volume_test psql -U postgres
CREATE DATABASE sample_db;
\c sample_db
CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));
INSERT INTO users (id, name) VALUES (1, 'ivan');
\q
Выйдите из контейнера:
exit
Удалите контейнер:
docker rm -f postgres_volume_test
Проверьте, что файлы базы данных остались в томе:
ls -l /var/lib/docker/volumes/pg_storage/_data
Запустите контейнер снова, примонтировав тот же том:
docker run -d \
--name postgres_volume_test \
-e POSTGRES_PASSWORD=StrongPass_456 \
-v pg_storage:/var/lib/postgresql/data \
postgres:17
Подключитесь к базе данных и убедитесь, что данные сохранились:
docker exec -it postgres_volume_test psql -U postgres
\l
\c sample_db
SELECT * FROM users;
Использование томов в Docker Compose
Тома в Docker Compose объявляются в отдельной секции volumes. Здесь задаются имена томов, которые будут автоматически созданы Docker при первом запуске, если они еще не существуют. Такие тома хранятся на хостовой системе и не зависят от жизненного цикла контейнеров.
Пример файла docker-compose.yml с томом для хранения данных PostgreSQL: version: '3.9'
volumes:
pg_data:
services:
db:
image: postgres:17
ports:
- 5432:5432
volumes:
- pg_data:/var/lib/postgresql/data
restart: always
environment:
POSTGRES_USER=new_usr1
POSTGRES_PASSWORD=StrongPass_123
POSTGRES_DB=usr1_db
В данном примере том pg_data используется для хранения файлов базы данных PostgreSQL. Он монтируется в каталог /var/lib/postgresql/data внутри контейнера ― именно здесь PostgreSQL по умолчанию хранит свои данные. Все изменения в базе данных будут записываться в этот том.
Docker Compose создает том автоматически при первом запуске сервиса. Если контейнер будет остановлен или удален, данные в томе сохранятся. При повторном запуске сервиса PostgreSQL использует уже существующие данные, а процесс инициализации базы выполняться не будет.
Чтобы запустить PostgreSQL, выполните команду:
docker compose up -d
Ее необходимо выполнять из каталога, где находится файл docker-compose.yml. Проверить список созданных томов можно командой:
docker volume ls
Типичные ошибки и как их исправить
При работе с PostgreSQL в Docker ошибки чаще всего связаны не с самой СУБД, а с нюансами запуска контейнера, переменных окружения и хранения данных. Мы собрали наиболее распространенные проблемы:
Контейнер завершился со статусом Exited
Почти всегда причина в отсутствии обязательной переменной POSTGRES_PASSWORD при первом запуске.
Проверьте логи контейнера:
docker logs <имя_контейнера>
Запустите контейнер заново, указав пароль:
docker run -d --name postgres_basic \
-e POSTGRES_PASSWORD=StrongPass_123 \
postgres:17
Если контейнер запускался через Docker Compose, проверьте, что переменная POSTGRES_PASSWORD есть в секции environment, затем выполните:
docker compose up -d
Не удается подключиться к базе с хоста или с другого сервера
Чаще всего порт не проброшен или закрыт на уровне сети.
Проверьте, что контейнер запущен и порт проброшен:
docker ps
В колонке PORTS должно быть что-то вроде 0.0.0.0:5432->5432/tcp.
Если проброса нет, перезапустите контейнер с -p:
docker run -d --name postgres_public \
-p 5432:5432 \
-e POSTGRES_PASSWORD=StrongPass_123 \
postgres:17
Если подключение идет с другого сервера, откройте порт 5432 в файрволе и в правилах безопасности вашего провайдера.
Пароль не подходит, хотя вы его точно задавали
Как правило, это происходит, когда том с данными уже содержит старую инициализацию, и новые переменные POSTGRES_PASSWORD, POSTGRES_USER, POSTGRES_DB не применяются.
Проверьте, какой том подключен:
docker inspect <имя_контейнера> | grep -A 5 Mounts
Если данные не нужны, удалите контейнер и том, затем запустите заново:
docker rm -f <имяконтейнера> docker volume rm <имятома>
Если данные нужны, поменяйте пароль внутри PostgreSQL:
docker exec -it <имя_контейнера> psql -U postgres
ALTER USER postgres WITH PASSWORD 'NewStrongPass_123';
\q
Контейнер не видит ваш конфигурационный файл
Причина ― неверный путь к файлу на хосте или неправильное монтирование.
Проверьте, что файл существует на хосте:
ls -l my-postgres.conf
Запускайте контейнер из каталога, где лежит файл, или укажите полный путь. Пример с текущим каталогом:
docker run -d --name postgres_custom_config \
-v "$PWD/my-postgres.conf":/etc/postgresql/postgresql.conf \
-e POSTGRES_PASSWORD=StrongPass_123 \
postgres:17 \
-c config_file=/etc/postgresql/postgresql.conf
Также проверьте права доступа к файлу.
Ошибка permission denied при работе с томами или файлами
Чаще всего проблема возникает из-за прав на каталоги, которые вы монтируете с хоста. Для именованных томов Docker это обычно неактуально, а для bind-монтажа папок ― встречается часто.
Если вы монтируете директорию с хоста, проверьте владельца и права:
ls -ld <папка>
Убедитесь, что процессы в контейнере могут читать и писать в нее. В сомнительных случаях используйте именованный том вместо папки.
Заключение
PostgreSQL в Docker позволяет быстро развернуть рабочую базу данных без сложной установки и лишней настройки системы. Контейнеры упрощают управление версиями, делают окружение воспроизводимым и подходят как для локальной разработки, так и для серверов.
В статье мы разобрали основные способы запуска PostgreSQL, настройку доступа, работу с томами, конфигурационными файлами и локалью.
Если вы хотите быстро развернуть рабочую базу данных без ручной настройки, можно воспользоваться PostgreSQL как сервисом в Рег.облаке.
Платформа обеспечивает:
- готовое развертывание и обновления СУБД без ручного администрирования,
- автоматическое резервное копирование и восстановление данных,
- стабильную работу и масштабирование под нагрузку,
- полный контроль над доступом к данным и изоляцию,
- размещение в российских ЦОДах с соблюдением всех требований безопасности и локализации.
FAQ
Как запустить PostgreSQL в Docker одной командой?
Чтобы запустить PostgreSQL в Docker одной командой, выполните:
docker run -d \
--name postgres_basic \
-e POSTGRES_PASSWORD=StrongPass_123 \
postgres:17
Контейнер запустится в фоновом режиме с пользователем postgres и заданным паролем.
Как настроить журналирование в PostgreSQL в Docker?
Журналирование в PostgreSQL, запущенном в Docker, настраивается через конфигурационный файл базы данных. Проще всего использовать собственный файл postgresql.conf и подключить его к контейнеру.
Создайте или отредактируйте файл конфигурации, указав нужные параметры логирования, например:
logging_collector = on
log_directory = 'log'
log_filename = 'postgresql-%Y-%m-%d.log'
log_statement = 'all'
log_min_duration_statement = 500
Запустите контейнер PostgreSQL с подключением этого файла:
docker run -d \
--name postgres_logging \
-v "$PWD/postgresql.conf":/etc/postgresql/postgresql.conf \
-e POSTGRES_PASSWORD=StrongPass_123 \
postgres:17 \
-c config_file=/etc/postgresql/postgresql.conf
Файлы журналов будут сохраняться внутри контейнера в каталоге, указанном в параметре log_directory. Чтобы сохранить логи вне контейнера, подключите отдельный том или каталог хоста.
Как оптимизировать производительность PostgreSQL в Docker?
Оптимизация PostgreSQL в Docker сводится к настройке самой СУБД и окружения контейнера.
Используйте выделенные тома для хранения данных, а не файловую систему контейнера. Задайте параметры памяти и процессов в postgresql.conf, например shared_buffers, work_mem и max_connections, с учетом ресурсов сервера. Ограничьте ресурсы контейнера по CPU и памяти, чтобы избежать перегрузки системы. Для рабочих нагрузок выбирайте конкретную версию образа PostgreSQL и не используйте тег latest.
Какие инструменты можно использовать для мониторинга PostgreSQL в Docker?
В PostgreSQL, запущенном в Docker, мониторинг можно организовать как средствами самой СУБД, так и с помощью внешних инструментов.
Для базового контроля подойдут системные представления PostgreSQL, такие как pg_stat_activity, pg_stat_database и pg_stat_bgwriter. Они позволяют отслеживать активные подключения, нагрузку и работу фоновых процессов прямо через SQL.
Для полноценного мониторинга чаще используют связку Prometheus и Grafana. Prometheus собирает метрики с контейнеров и базы данных, а Grafana отображает их в виде дашбордов с графиками и оповещениями.
Графические клиенты, такие как DBeaver и pgAdmin, подходят для оперативного контроля. Через них удобно смотреть активные сессии, выполняемые запросы и общее состояние PostgreSQL без настройки отдельной системы мониторинга.
