Пул соединений

Прикладной код пула не видит: репозиторий сам берёт соединение и сам его отдаёт. Эта страница — про то, что происходит под ним, и про три решения, которые всё-таки принимает человек: сколько соединений, что делать при сбое и как понять, что пул забит.

Как он устроен

Главное, что даёт PPA. Устроен по образцу HikariCP из мира Java: смысл не в переиспользовании как таковом, а в том, что соединения поддерживаются работоспособными.

воркер
└── пул (на класс конфигурации)
    ├── соединение 1  ← корутина A взяла на время запроса
    ├── соединение 2  ← корутина B
    └── соединение 3    свободно

Корутина берёт соединение при первом обращении к базе и возвращает автоматически, когда завершается. Освобождать вручную не нужно нигде — возврат навешивается defer.

Правила, применяемые при каждой выдаче

Проверка только простоявших. Соединение, пролежавшее без дела дольше 500 мс, перед выдачей проверяется; мёртвое — выбрасывается и заменяется свежим. Соединение, которым только что пользовались, не проверяется вообще.

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

Ротация по возрасту. Соединение старше 30 минут заменяется заранее, до того как его закроет сервер или файрвол. Момент замены слегка разбрасывается во времени, чтобы весь пул не обновился разом.

Ограниченное ожидание. Если все соединения заняты, запрос ждёт свободного не дольше poolWaitTimeout и затем падает с PpaPoolException. Лучше быстрый понятный отказ, чем зависший навсегда запрос.

Что происходит при сбое

Пул различает две принципиально разные причины ошибки:

С PostgreSQL пришлось повозиться: PDO не сообщает о потере соединения кодом 08006. Когда сокета уже нет, брать SQLSTATE неоткуда, и ошибка приходит как HY000 с общим кодом libpq 7 — тем же, что у обычной синтаксической ошибки. Если вердикт драйвера настолько неинформативен, пул проверяет соединение и решает по ответу.

Настройка

Пул есть у любой конфигурации базы — по умолчанию на 5 соединений. Чтобы задать свои значения, реализуйте PpaPoolConfigInterface через PpaPoolTrait:

use Flytachi\Winter\Cdo\Config\PgDbConfig;
use Flytachi\Winter\Ppa\Pool\{PpaPoolConfigInterface, PpaPoolTrait};

class MainDbConfig extends PgDbConfig implements PpaPoolConfigInterface
{
  use PpaPoolTrait;

  public int   $poolMaxConnections = 10;
  public float $poolWaitTimeout    = 5.0;

  public function setUp(): void
  {
      $this->host     = env('DB_HOST', 'localhost');
      $this->database = env('DB_NAME', 'app');
      $this->username = env('DB_USER', 'postgres');
      $this->password = env('DB_PASS', '');
  }
}

Трейт даёт значение по умолчанию каждому параметру, поэтому конфигурация объявляет только то, что меняет, и не ломается, когда в интерфейс добавляется новый.

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

Посмотреть, что происходит

php call db pool

MainMainDbConfig
active 12 · idle 3 · total 15 · maximum 20 · workers 2
saturated  1 of 2 workers                    [SATURATED]
per worker
worker#0  MainMainDbConfig  active=2  idle=3 total=5  max=10  age=0s
worker#1  MainMainDbConfig  active=10 idle=0 total=10 max=10  age=3s

Смотреть нужно на строки воркеров, а не на общий итог: запрос встаёт в очередь к пулу своего воркера, поэтому один забитый воркер — это реальные задержки, даже когда суммарно места полно.

Консоль — отдельный процесс и в память работающего сервера заглянуть не может, поэтому воркеры сами публикуют статистику по таймеру. Интервал задаётся переменной PPA_POOL_TELEMETRY (секунды, по умолчанию 5, 0 выключает). Те же цифры отдаёт эндпоинт /actuator/pools, если включён актуатор.

Загрузка пула намеренно не входит в /actuator/health: доступность базы и заполненность пула — разные вопросы. Занятый, но исправно работающий сервис не должен отвечать degraded проверке, которая решает, слать ли ему трафик.

Справочник PpaConnectionPool

Статический фасад. В прикладном коде обычно не нужен — им пользуются репозитории.

Разница между двумя последними существенная. shutdown() закрывает сокеты и снимает таймер обслуживания: живой Timer::tick не даст реактору воркера завершиться. reset() вызывают в потомке после форка — там сокеты нельзя закрывать, потому что дескрипторы общие с родителем и закрытие оборвало бы его соединение.

Без Swoole

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

Дальше

• PHP Persistence API — обзор слоя и примеры запросов
• Конфигурация БД — где задаются учётные данные и драйвер
• Репозитории — то, ради чего соединение берут