Сервисы · Пакет

PostgreSQL

winter-service-postgres — готовый сервис PostgreSQL. Приложение поднимает базу раньше всего остального, ждёт, пока она ответит, проверяет её, пока она работает, перезапускает после падения или зависания и останавливает последней — быстрой остановкой.

Пакет flytachi/winter-service-postgresКласс PostgresВерсии 14–18

Что это и зачем

Что это. Класс Postgres, реализующий Service: он знает, как запустить PostgreSQL в контейнере приложения, как понять, что он готов, как его остановить и что ему нужно в образе.

Проблема. Своя база в контейнере — это initdb при первом старте, проверка версии данных, отдельная роль приложения с базой и паролем, правильные права на каталоги, pg_isready без ложных FATAL в логе, верный сигнал остановки. Каждый проект собирает это заново и спотыкается об одно и то же.

Решение. Всё это — в пакете и проверено на настоящем сервере. В проекте остаётся одна строка.

Пакет запускает сервер. Подключаются к нему как обычно — через PDO или winter-ppa, см. Подключение.

Установка

bash
composer require flytachi/winter-service-postgres

Нужны PHP 8.4+, flytachi/winter-kernel 4.5+ и образ flytachi/winter (Alpine): сам сервер ставится из apk, и call service docker добавляет его в образ.

Быстрый старт

1. Объявить:

bootstrap.php
use Flytachi\Winter\Service\Postgres\Postgres;

protected static function components(Components $components): void
{
  $components->service(new Postgres(version: 18, database: 'app'));
}

2. Добавить в образ:

bash
php call service docker

В Dockerfile появится apk add postgresql18 postgresql18-client postgresql18-contrib и каталоги с владельцем winter. Подробнее — в Что нужно в образе.

Compose команда не трогает — она печатает, что в него добавить. Добавьте в docker-compose.yml то, что вам подходит:

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 секунд. Откуда это число — в Остановке.

bash
docker compose up -d --build

3. Запустить. При первом старте в логе:

text
[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: Http

PostgreSQL поднимается раньше всего: 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 с объяснением.

php
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:

  1. Данных нет → initdb с суперпользователем postgres, encoding и locale. Каталог, в котором лежат файлы, но не данные PostgreSQL, не инициализируется поверх — старт останавливается.
  2. Данные есть → их версия (PG_VERSION) сверяется с version. Не совпадает — старт останавливается с объяснением, что делать.
  3. Роли user нет → она создаётся: вход есть, прав суперпользователя нет.
  4. Пароль приводится к тому, что в коде: задан — применяется, убран — снимается. В скрипт пароль попадает через переменную окружения, а не через командную строку, которую видит любой процесс контейнера.
  5. Базы нет → она создаётся с владельцем user. Есть, но владелец другой → передаётся user.
  6. pg_hba.conf пишется заново: через сокет — все, по TCP — только user, только в свою базу, только с паролем. Если host — не loopback, то и с других адресов.
  7. Запуск сервера: 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.

Администратору — суперпользователь через сокет:

bash
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] на классе конфигурации:

main/Configs/MainDbConfig.php
#[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 знает, где его сервер:

php
$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

main/Db.php
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,
      ]);
  }
}
bootstrap.php
protected static function components(Components $components): void
{
  $components->service(Db::service());
}
php
$notes = Db::connect()->query('SELECT id, text FROM notes')->fetchAll();

Через winter-ppa

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

main/Configs/MainDbConfig.php
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
  }
}
bootstrap.php
protected static function components(Components $components): void
{
  $components->service(MainDbConfig::service());
}

Репозитории ссылаются на неё, как на любую конфигурацию:

php
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 держит соединения в каждом процессе, а не на всё приложение, поэтому посчитайте, сколько их может открыться сразу:

text
(воркеры HTTP + процессы, демоны, планировщик, WebSocket — те, что ходят в базу)
× $poolMaxConnections
+ ~5 — psql, миграции, проверки

По умолчанию это 1 воркер × 5 = 5 соединений, далеко от предела. Упирается обычно, когда растят воркеры: 8 воркеров (SERVER_WORKERS=8) × пул 20 — уже 160, и под пиком нагрузки база начнёт отвечать too many clients already. Тогда либо уменьшите пул, либо поднимите предел:

php
new Postgres(database: 'app', settings: ['max_connections' => 200]);

Каждое соединение PostgreSQL — отдельный процесс со своей памятью, поэтому предел поднимают с оглядкой на память контейнера, а не «с запасом».

Лог

Лог PostgreSQL идёт в лог приложения: в том же формате, канал -postgres- (в цвете — синий, чтобы не путать со строками приложения), в скобках — PID процесса базы, который написал строку.

text
[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, не обновив данные, значит получить сервер, который не стартует. Поэтому пакет и не пытается:

text
[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) ничего не требуют: образ получает их при следующей сборке.

Дальше