PostgreSQL
winter-service-postgres — готовый сервис PostgreSQL. Приложение поднимает базу раньше
всего остального, ждёт, пока она ответит, проверяет её, пока она работает, перезапускает
после падения или зависания и останавливает последней — быстрой остановкой.
Что это и зачем
Что это. Класс Postgres, реализующий Service:
он знает, как запустить PostgreSQL в контейнере приложения, как понять, что он готов,
как его остановить и что ему нужно в образе.
Проблема. Своя база в контейнере — это initdb при первом старте, проверка версии
данных, отдельная роль приложения с базой и паролем, правильные права на каталоги,
pg_isready без ложных FATAL в логе, верный сигнал остановки. Каждый проект собирает
это заново и спотыкается об одно и то же.
Решение. Всё это — в пакете и проверено на настоящем сервере. В проекте остаётся одна строка.
Пакет запускает сервер. Подключаются к нему как обычно — через PDO или
winter-ppa, см. Подключение.
Установка
composer require flytachi/winter-service-postgresНужны PHP 8.4+, flytachi/winter-kernel 4.5+ и образ flytachi/winter (Alpine): сам
сервер ставится из apk, и call service docker добавляет его в образ.
Быстрый старт
1. Объявить:
use Flytachi\Winter\Service\Postgres\Postgres;
protected static function components(Components $components): void
{
$components->service(new Postgres(version: 18, database: 'app'));
}2. Добавить в образ:
php call service dockerВ Dockerfile появится apk add postgresql18 postgresql18-client postgresql18-contrib
и каталоги с владельцем winter. Подробнее — в Что нужно в образе.
Compose команда не трогает — она печатает, что в него добавить. Добавьте в
docker-compose.yml то, что вам подходит:
services:
server:
stop_grace_period: 70s
volumes:
- postgres-data:/var/lib/postgresql/data
volumes:
postgres-data:stop_grace_period— нужен всегда (ниже — почему).- Том — если база должна пережить пересоздание контейнера. Для тестов или
одноразового стенда его можно не ставить. Каталог данных уже лежит в вашем томе
(
data: '/var/lib/app/postgresql') — отдельный том не нужен.
Остановке нужно 70 секунд
С PostgreSQL контейнеру на остановку нужно до 70 секунд — stop_grace_period: 70s.
У Docker по умолчанию 10 секунд: потом он убивает контейнер, и база не успевает
остановиться чисто. В Kubernetes задайте те же 70 секунд. Откуда это число — в
Остановке.
docker compose up -d --build3. Запустить. При первом старте в логе:
[2026-11-15 02:10:00] [INFO ] -sys- [1]: Application starting High: postgres
[2026-11-15 02:10:01] [INFO ] -postgres- [9]: initialised PostgreSQL 18 data in /var/lib/postgresql/data.
[2026-11-15 02:10:01] [INFO ] -postgres- [9]: created role winter.
[2026-11-15 02:10:02] [INFO ] -postgres- [9]: created database app.
[2026-11-15 02:10:02] [INFO ] -postgres- [9]: database system is ready to accept connections
[2026-11-15 02:10:02] [INFO ] -sys- [1]: postgres is up.
[2026-11-15 02:10:02] [INFO ] -sys- [1]: Application starting Normal: HttpPostgreSQL поднимается раньше всего: HTTP принимает первый запрос, когда база уже
отвечает. Строки базы идут в общий лог под каналом -postgres- — подробнее в Логе.
Параметры
Сервер
| Параметр | По умолчанию | Что задаёт |
|---|---|---|
version |
18 |
Мажорная версия: образ ставит postgresql{version}. Данные другой версии не открываются — см. Смена мажорной версии |
data |
/var/lib/postgresql/data |
Каталог данных — его держат в томе |
socket |
/run/postgresql |
Каталог Unix-сокета |
host |
null |
null — только сокет, снаружи контейнера не подключиться. 127.0.0.1 — ещё и TCP внутри контейнера. 0.0.0.0 — и для других контейнеров. С host нужен пароль |
port |
5432 |
Порт TCP; он же в имени сокета (.s.PGSQL.5432) |
user |
'winter' |
Роль приложения: вход есть, прав суперпользователя нет, владелец своей базы. Создаётся, если её нет. См. Роли |
password |
null |
Пароль роли приложения. Спрашивается по TCP (scram-sha-256), через сокет — никогда. Применяется на каждом старте: сменили в коде — сменился в базе, убрали — убран |
database |
null |
База приложения; создаётся, если её нет, — на любом старте, не только первом. null — база с именем роли (winter) |
encoding |
'UTF8' |
Кодировка кластера |
locale |
'C' |
Локаль кластера; в musl на Alpine других локалей почти нет |
timezone |
null |
Часовой пояс сервера (timezone, log_timezone), ставится на каждом старте: по нему now()::date и date_trunc('day', …) считают сутки. null — как у приложения, TIME_ZONE (без него — UTC). Имя IANA, Asia/Tashkent; через settings не задаётся |
contrib |
true |
Ставить ли в образ postgresql{version}-contrib — расширения pgcrypto, pg_trgm, citext и другие. См. Расширения |
settings |
[] |
Настройки сервера, каждая уходит как -c ключ=значение: ['shared_buffers' => '256MB', 'max_connections' => 200]; true/false становятся on/off |
args |
[] |
Другие аргументы postgres как есть |
shutdown |
Shutdown::Fast |
Как останавливать — см. Остановка |
logs |
true |
Писать ли лог PostgreSQL в лог приложения — см. Лог. false — как пишет сам PostgreSQL |
Компонент
| Параметр | По умолчанию | Что задаёт |
|---|---|---|
name |
'postgres' |
Имя в логах и app status; том в подсказке compose — {name}-data |
priority |
Priority::High |
Стартует раньше остальных, останавливается после них |
critical |
true |
Не может работать — приложение останавливается |
retries |
3 |
Перезапуски после падения за 30 минут |
grace |
30.0 |
Секунды на остановку до SIGKILL |
startTimeout |
60 |
Секунды, чтобы стать готовым; первый старт выполняет initdb |
alive |
true |
true — pg_isready раз в 10 с, 5 с на ответ, 6 неудач подряд значат «завис». Свой Probe. null или false — не проверять |
Всё проверяется при создании объекта: версия, которую образ не поставит, относительный
путь, порт вне диапазона, host без пароля, имя пользователя или базы не из букв, цифр и
_, user: 'postgres' (это суперпользователь), database: 'postgres' (это база самого
кластера), неизвестный часовой пояс, настройка в две строки — каждое даёт InvalidArgumentException с объяснением.
new Postgres(
version: 18,
database: 'app',
settings: ['shared_buffers' => '256MB', 'max_connections' => 200],
alive: Probe::command(['pg_isready', '-q', '-h', '/run/postgresql', '-d', 'app'],
every: 15, failures: 8), // more patience under heavy load
shutdown: Shutdown::Smart, // wait for every session to finish
);Что происходит при старте
Перед сервером работает скрипт пакета, который затем сам становится сервером
(exec), поэтому сигнал остановки приходит прямо PostgreSQL:
- Данных нет →
initdbс суперпользователемpostgres,encodingиlocale. Каталог, в котором лежат файлы, но не данные PostgreSQL, не инициализируется поверх — старт останавливается. - Данные есть → их версия (
PG_VERSION) сверяется сversion. Не совпадает — старт останавливается с объяснением, что делать. - Роли
userнет → она создаётся: вход есть, прав суперпользователя нет. - Пароль приводится к тому, что в коде: задан — применяется, убран — снимается. В скрипт пароль попадает через переменную окружения, а не через командную строку, которую видит любой процесс контейнера.
- Базы нет → она создаётся с владельцем
user. Есть, но владелец другой → передаётсяuser. pg_hba.confпишется заново: через сокет — все, по TCP — толькоuser, только в свою базу, только с паролем. Еслиhost— не loopback, то и с других адресов.- Запуск сервера:
postgres -D … -k <socket> -p <port> -c listen_addresses=<host> …
Всё до запуска сервера делается в однопользовательском режиме PostgreSQL — сервер ещё не слушает ни сокет, ни порт.
Роли
В кластере две роли:
| Роль | Кто | Как входит |
|---|---|---|
postgres |
суперпользователь: скрипт старта и администратор | только через сокет, внутри контейнера, без пароля |
user (winter) |
приложение: обычная роль, владелец своей базы | через сокет без пароля; по TCP — с паролем и только в свою базу |
Роли приложения хватает на всё, что нужно приложению: таблицы, индексы, ALTER в своей
базе, расширения из contrib.
Зачем вторая роль. На случай SQL-инъекции. Тот, кто нашёл её в приложении, получает права соединения приложения — и не больше:
| Через инъекцию | суперпользователь | роль приложения |
|---|---|---|
| читать и менять данные своей базы | да | да |
COPY … TO PROGRAM — команда в контейнере |
да | нет |
pg_read_file() — чтение файлов, например .env |
да | нет |
ALTER SYSTEM, создание ролей |
да | нет |
С суперпользователем инъекция становится захватом контейнера, с ролью приложения —
остаётся в пределах одной базы. Это вторая линия обороны: первая — запросы с
параметрами, как их строит winter-ppa.
Администратору — суперпользователь через сокет:
docker exec -it app psql -h /run/postgresql -U postgresДанные, где роль приложения — суперпользователь
Если кластер создан так, что user в нём — суперпользователь, сервер стартует как
обычно, а в логе — предупреждение, что приложение подключается со всеми правами, и как это
исправить. Сам скрипт права не понижает.
Расширения
contrib (по умолчанию включён) ставит в образ расширения, которые идут вместе с
PostgreSQL: pgcrypto, pg_trgm, citext, hstore, unaccent, ltree, uuid-ossp и
другие. Сервис их только ставит, а включает в базе CREATE EXTENSION. В
winter-ppa это #[Extension] на классе конфигурации:
#[Extension('pg_trgm')]
#[Extension('citext')]
class MainDbConfig extends PgDbConfig implements PpaPoolConfigInterface
{
public static function service(): Postgres
{
return new Postgres(version: 18, database: 'app'); // contrib: true
}
// setUp() — see Connecting
}Роль приложения сама включает доверенные расширения — это почти всё, что нужно коду:
pgcrypto, uuid-ossp, citext, hstore, pg_trgm, unaccent, ltree, btree_gin,
btree_gist, fuzzystrmatch, intarray, cube, isn, lo, seg, tablefunc.
Недоверенные расширения
pg_stat_statements, postgres_fdw, dblink и другие служебные включает только
суперпользователь. CREATE EXTENSION от роли приложения на них остановится:
permission denied to create extension … Must be superuser. PostGIS и pgvector в contrib
не входят — это отдельные пакеты apk.
Для UUID расширение не нужно: gen_random_uuid() встроен в PostgreSQL 13+. Не нужен
contrib — new Postgres(contrib: false), и в образе на 4 МБ меньше.
Подключение
Объект Postgres знает, где его сервер:
$pg->dsn(); // pgsql:host=/run/postgresql;port=5432;dbname=app
$pg->user(); // winter — the application's role, not the superuser
$pg->database; // app — without database: winter, the role's nameЧерез сокет, внутри контейнера, пароль не спрашивается. По TCP (задан host) —
pgsql:host=127.0.0.1;port=5432;dbname=app, с user и password.
Поэтому то, как база запускается и как к ней подключаются, удобно держать в одном месте — в одном методе, который вызывают и приложение, и код, который подключается.
Через PDO
namespace Main;
use Flytachi\Winter\Service\Postgres\Postgres;
final class Db
{
public static function service(): Postgres
{
return new Postgres(version: 18, database: 'app');
}
public static function connect(): \PDO
{
$pg = self::service();
return new \PDO($pg->dsn(), $pg->user(), $pg->password, [
\PDO::ATTR_ERRMODE => \PDO::ERRMODE_EXCEPTION,
]);
}
}protected static function components(Components $components): void
{
$components->service(Db::service());
}$notes = Db::connect()->query('SELECT id, text FROM notes')->fetchAll();Через winter-ppa
Естественное место — класс конфигурации базы winter-ppa:
один и тот же класс и запускает сервер, и подключается к нему, поэтому сокет, порт, база
и пользователь не могут разойтись.
namespace Main\Configs;
use Flytachi\Winter\Cdo\Config\PgDbConfig;
use Flytachi\Winter\Ppa\Pool\PpaPoolConfigInterface;
use Flytachi\Winter\Ppa\Pool\PpaPoolTrait;
use Flytachi\Winter\Service\Postgres\Postgres;
class MainDbConfig extends PgDbConfig implements PpaPoolConfigInterface
{
use PpaPoolTrait;
public int $poolMaxConnections = 10;
public float $poolWaitTimeout = 5.0;
/** What the application runs. */
public static function service(): Postgres
{
return new Postgres(version: 18, database: 'app');
}
/** How winter-ppa connects to it. */
public function setUp(): void
{
$pg = self::service();
$this->host = $pg->socket; // a socket directory is a host for libpq
$this->port = $pg->port;
$this->database = $pg->database;
$this->username = $pg->user;
$this->password = $pg->password ?? ''; // through the socket none is asked
}
}protected static function components(Components $components): void
{
$components->service(MainDbConfig::service());
}Репозитории ссылаются на неё, как на любую конфигурацию:
class NoteRepository extends Repository
{
protected string $dbConfigClassName = MainDbConfig::class;
protected string $entityClassName = Note::class;
public static string $table = 'notes';
}
$notes = NoteRepository::instance()->orderBy('id')->findAll();
$id = new NoteRepository()->insert($note);Если база открыта по TCP (задан host, подключаются другие контейнеры), в setUp()
хостом становится 127.0.0.1 — или имя контейнера, — а пароль обязателен.
Клиент по TCP — укажите базу приложения
По TCP роль приложения пускают только в её базу. DBeaver, TablePlus и другие клиенты с
пустым полем «Database» просятся в служебную postgres и получают
no pg_hba.conf entry … database "postgres". Укажите базу из database: — без него это
winter, имя роли: psql -h 127.0.0.1 -U winter -d winter.
Сколько соединений
У PostgreSQL по умолчанию max_connections = 100, и три из них оставлены суперпользователю.
Пул winter-ppa держит соединения в каждом процессе, а не на всё приложение, поэтому
посчитайте, сколько их может открыться сразу:
(воркеры HTTP + процессы, демоны, планировщик, WebSocket — те, что ходят в базу)
× $poolMaxConnections
+ ~5 — psql, миграции, проверкиПо умолчанию это 1 воркер × 5 = 5 соединений, далеко от предела. Упирается обычно, когда
растят воркеры: 8 воркеров (SERVER_WORKERS=8) × пул 20 — уже 160, и под пиком нагрузки
база начнёт отвечать too many clients already. Тогда либо уменьшите пул, либо поднимите
предел:
new Postgres(database: 'app', settings: ['max_connections' => 200]);Каждое соединение PostgreSQL — отдельный процесс со своей памятью, поэтому предел поднимают с оглядкой на память контейнера, а не «с запасом».
Лог
Лог PostgreSQL идёт в лог приложения: в том же формате, канал -postgres- (в цвете —
синий, чтобы не путать со строками приложения), в скобках — PID процесса базы, который
написал строку.
[2026-11-15 02:11:23] [ERROR] -postgres- [64]: relation "usres" does not exist at character 15 {"statement":"SELECT * FROM usres"}Уровни PostgreSQL становятся уровнями лога:
| PostgreSQL | Лог |
|---|---|
DEBUG1–DEBUG5 |
DEBUG |
LOG, INFO |
INFO |
NOTICE |
NOTIC |
WARNING |
WARN |
ERROR |
ERROR |
FATAL |
CRIT |
PANIC |
EMERG |
LOG_LEVELдействует и на базу.LOG_LEVEL=warningубирает её обычные сообщения (старт, контрольные точки) и оставляет предупреждения и ошибки.DETAIL,HINT,STATEMENT,CONTEXTне идут отдельными строками, а присоединяются к своей ошибке — в контекст под ключамиdetail,hint,statement,context.- JSON и файл логов работают так же, как для строк приложения. В JSON PID базы — в
extra.program. - Строки скрипта старта (
created role winter.) — тоже в канале-postgres-; его предупреждения и ошибки — с уровнямиWARNиERROR.
Лог выключен — база тоже молчит
Строки PostgreSQL идут через логгер приложения, поэтому без LOG_LEVEL (лог выключен) не
видно и их — в том числе причины, по которой база не стартовала: останется только
postgres failed: exit code 1. Чтобы увидеть её, задайте LOG_LEVEL=error — в логе
будут только ошибки — или logs: false: тогда PostgreSQL пишет свой вывод напрямую.
Свой log_line_prefix в settings разбор не поймёт: такие строки попадут в лог как
есть, с уровнем INFO. Нужен вывод PostgreSQL без изменений — logs: false.
Подробный лог запросов
log_statement: 'all' или log_min_duration_statement: 0 дают тысячи строк в секунду,
и все они идут через процесс приложения. Для такого лога включите собственный сборщик
PostgreSQL — 'logging_collector' => true в settings: он пишет в файлы внутри
каталога данных, мимо приложения.
Остановка
shutdown |
Сигнал | Что делает PostgreSQL |
|---|---|---|
Shutdown::Smart |
SIGTERM |
Ждёт, пока закроются все сессии. Клиент, который не уходит, — например, psql администратора, — держит остановку, пока не кончится grace |
Shutdown::Fast (по умолчанию) |
SIGINT |
Обрывает сессии, откатывает их транзакции, пишет контрольную точку: чисто и быстро |
Shutdown::Immediate |
SIGQUIT |
Останавливается без контрольной точки; следующий старт восстанавливается, как после падения |
Зависший сервер — проверка alive не прошла 6 раз подряд — останавливается по ступеням:
его сигнал, через grace / 2 — SIGTERM, через grace — SIGKILL; затем
перезапускается. Как это устроено — в alive.
70 секунд на остановку
PostgreSQL останавливается последним, после HTTP, поэтому их сроки складываются:
| Что | Секунды |
|---|---|
| HTTP дорабатывает запросы | 30 |
PostgreSQL (grace) |
30 |
| запас приложения | 5 |
| запас контейнера | 5 |
stop_grace_period |
70 |
Именно это число печатает call service docker. Обычно остановка занимает доли
секунды: 70 — это предел, а не ожидание.
Изменили grace (new Postgres(grace: 60.0)) — запустите call service docker снова
и поправьте stop_grace_period в compose: здесь он станет 100 секунд. В Kubernetes то же число задаётся в
terminationGracePeriodSeconds.
Смена мажорной версии
PostgreSQL 19 не читает данные 18. Поднять version, не обновив данные, значит получить
сервер, который не стартует. Поэтому пакет и не пытается:
[2026-11-15 02:10:01] [ERROR] -postgres- [9]: the data in /var/lib/postgresql/data is PostgreSQL 18, the server is 19: upgrade it with pg_upgrade, or set version: 18.Данные переносят через pg_upgrade (обе версии в образе) или через выгрузку и загрузку
(pg_dumpall), и только потом поднимают version. Минорные обновления (18.6 → 18.7)
ничего не требуют: образ получает их при следующей сборке.
Дальше
- Сервисы — что это и как устроено.
- Что нужно в образе — что записывает
call service docker. - MariaDB и Redis — другие готовые сервисы.
- Конфигурация базы —
PgDbConfigи пул соединений.