---
title: "Commit ID у Laravel 13.40: як дізнатися, що репліка вже наздогнала primary"
url: https://laravelukraine.com/blog/commit-id-u-laravel-1340-iak-diznatisia-shho-replika-vze-nazdognala-primary
date: 2026-11-17
---

# Commit ID у Laravel 13.40: як дізнатися, що репліка вже наздогнала primary

У Laravel 13.40 з'явилися три методи з'єднання, які прибирають вгадування з роботи з репліками: [`getLastCommitId()`, `hasCommitId()` і `mergeCommitIds()`](https://github.com/laravel/framework/pull/62198) від Тобіаса Петрі (Tobias Petry). Після запису можна запам'ятати позицію primary, а потім спитати репліку, чи вона до цієї позиції вже дійшла. Не "мабуть, за дві секунди дійшла", а так чи ні.

### Чим погане фіксоване вікно

Три тижні тому ми писали про [`PreventStaleDatabaseReads` і `usingWritePdo()` з Laravel 13.38](https://laravelukraine.com/blog/laravel-1336-1338-repliki-bazi-danix-bez-zastarilix-danix). Коротко: `sticky` у конфігу з'єднання береже свіжі дані лише до кінця поточного запиту, а форма зазвичай робить `PUT` і редирект на `GET` - другий запит знову читає з репліки. `Middleware` кладе в сесію мітку часу запису й дві секунди (або скільки задасте через `PreventStaleDatabaseReads::for(15)`) спрямовує читання цього користувача на primary. Для разових читань є `DB::usingWritePdo(fn () => ...)`.

Слабке місце - саме число. Дві секунди - це припущення про затримку реплікації. Якщо реплікація відстала на п'ять, користувач побачить старі дані. Якщо вона відстає на 20 мілісекунд, як буває в більшості налаштувань, то майже дві секунди кожного користувача, що щось зберіг, обслуговує primary без потреби. Збільшуєте вікно - навантажуєте primary, зменшуєте - ловите старі дані. Commit ID знімає цей вибір.

### Три методи

```php
  use Illuminate\Support\Facades\DB;

  // після запису: позиція primary
  $invoice->update(['status' => 'paid']);
  $commitId = DB::getLastCommitId();

  // пізніше, на read-з'єднанні
  DB::hasCommitId($commitId);          // одна перевірка, відповідь одразу
  DB::hasCommitId($commitId, wait: 2); // чекати до 2 секунд, поки репліка дожене

  // кілька позицій в одну, що покриває всі
  $commitId = DB::mergeCommitIds([$previousId, $commitId]);
```

- `getLastCommitId()` завжди виконується на write-з'єднанні (через `usingWritePdo()` всередині) і повертає рядок.
- `hasCommitId(string $value, int $wait = 0)` повертає `true`, якщо сервер уже застосував усе до цієї позиції. `wait` - ціле число секунд; з ним метод просить саму СУБД заблокуватися до потрібної позиції або до таймауту і повертає `false`, якщо не дочекався.
- `mergeCommitIds(array $values)` потрібен, коли перша позиція ще не дійшла до репліки, а користувач уже записав щось знову. Порожній масив дає `RuntimeException`.

Через фасад `DB` методи викликаються на з'єднанні за замовчуванням. Для іншого - `DB::connection('reporting')->hasCommitId($id)`.

### Що таке commit ID у кожній СУБД

Формат рядка залежить від драйвера, і з PR видно, яким запитом його отримано:

- **MySQL** - набір GTID з `@@global.gtid_executed`, на кшталт `3e11fa47-71ca-11e1-9e33-c80aa9429562:1-77`. Перевірка - `GTID_SUBSET()`, очікування - `WAIT_FOR_EXECUTED_GTID_SET()`, об'єднання - `GTID_SUBTRACT()` для нормалізації набору.
- **MariaDB** - позиція з `@@gtid_binlog_pos`, наприклад `0-1-1052`. Очікування - `MASTER_GTID_WAIT()`; для власних записів сервера код додатково звіряється з `@@gtid_current_pos`. Об'єднання бере найновіший GTID у кожному домені реплікації.
- **PostgreSQL** - позиція WAL з `pg_current_wal_lsn()`, наприклад `0/16B3748`. LSN лінійні, тому `mergeCommitIds()` просто бере найбільший. Очікування робить нова команда `WAIT FOR LSN`, тому `wait` працює лише з PostgreSQL 19; на попередніх версіях виклик з `wait` кидає виняток, навіть на primary.
- **SQLite і SQL Server** - не підтримуються: базовий `Connection` кидає `RuntimeException` на кожен із трьох методів.

Для коду важливо: commit ID у MySQL - не коротке число, а набір інтервалів, що може містити кілька UUID серверів. У сесії він уміщається, але колонку чи поле під нього робіть рядком без жорсткої межі довжини.

### Куди насправді йде перевірка

`hasCommitId()` - це звичайний `select`, тож він іде туди ж, куди й інші читання в цьому запиті. Іноді це primary: всередині транзакції, після запису на з'єднанні з `sticky`, або коли читання примусово спрямовані через `useWriteConnectionWhenReading()` чи `usingWritePdo()`. Тоді метод чесно відповідає `true` - primary свої коміти має, і наступні читання теж підуть на primary, тож результат усе одно правильний.

Друга деталь: з'єднання тримає один read PDO на весь запит. Якщо в секції `read` кілька хостів, Laravel вибирає один, коли відкриває з'єднання, і перевірка та подальші запити виконуються на тому самому сервері. Наступний HTTP-запит може потрапити на іншу репліку, тому результат перевірки не кешують, а повторюють на кожному запиті. Це добре розписано в [розборі Laravel News](https://laravel-news.com/laravel-read-replica-commit-ids).

А ось чого Laravel не контролює: якщо перед репліками стоїть проксі, який розподіляє вже окремі запити (ProxySQL, Pgpool-II, "reader endpoint" хмарного провайдера з балансуванням на рівні запитів), перевірка може пройти на одній репліці, а `select` даних - на іншій. Для такої схеми з'ясуйте, чи проксі тримає одне з'єднання з одним бекендом, перш ніж покладатися на `hasCommitId()`.

### Сценарій 1: commit ID у сесії замість таймера

Ідея з опису PR: після запису кладемо в сесію позицію primary, а на кожному наступному запиті питаємо репліку, чи вона її має. Має - прибираємо ключ і читаємо з репліки. Ні - читаємо з primary. Ось мінімальний `middleware` для групи `web`:

```php
  namespace App\Http\Middleware;

  use Closure;
  use Illuminate\Http\Request;
  use Illuminate\Support\Facades\DB;
  use Symfony\Component\HttpFoundation\Response;

  class ReadAfterWrite
  {
      public function handle(Request $request, Closure $next): Response
      {
          $session = $request->session();
          $pending = $session->get('db.commit_id');

          if ($pending !== null && DB::hasCommitId($pending)) {
              $session->forget('db.commit_id');
              $pending = null;
          }

          if ($pending !== null) {
              DB::useWriteConnectionWhenReading();
          }

          $response = $next($request);

          if (DB::hasModifiedRecords()) {
              $commitId = DB::getLastCommitId();

              $session->put('db.commit_id', $pending === null
                  ? $commitId
                  : DB::mergeCommitIds([$pending, $commitId]));
          }

          return $response;
      }
  }
```

```php
  // bootstrap/app.php
  ->withMiddleware(function (Middleware $middleware) {
      $middleware->web(append: [
          \App\Http\Middleware\ReadAfterWrite::class,
      ]);
  })
```

Кілька рішень у цьому коді варто проговорити:

- **Перевірка без `wait`.** У вебзапиті чекати на репліку немає сенсу: поки вона доганяє, primary вже відповів би.
- **`append` у групу `web`**, щоб `middleware` працював усередині `StartSession` і сесія зберігалася після нього.
- **`mergeCommitIds()`**, бо поки перша позиція не дійшла, користувач міг зберегти ще щось. Одна позиція в сесії покриває обидва записи.
- **Ціна** - один зайвий запит до репліки на кожному запиті з позицією в сесії і один до primary на кожному запиті, що писав. Натомість як тільки репліка має дані (зазвичай за мілісекунди), користувач одразу повертається на неї.
- Якщо реплікація зупиниться, ключ лишиться в сесії і користувач читатиме з primary. Дані будуть правильні, але варто мати моніторинг реплікації, щоб про таку зупинку дізнатися не з графіка навантаження на primary.

Тобіас Петрі в PR пропонує ще й верхню межу: тримати позицію не довше, скажімо, 30 секунд. Це страхування від нескінченного читання з primary ціною ризику старих даних після межі - вирішуйте за своїми метриками.

Обмеження ті самі, що й у `PreventStaleDatabaseReads`: потрібна сесія і захищено лише того, хто писав. Для stateless API commit ID можна віддавати клієнту, наприклад у заголовку відповіді, і приймати назад у наступному запиті, але це вже ваш власний протокол.

### Сценарій 2: завдання черги, яке не читає порожню репліку

Класична гонка: контролер створив замовлення, поставив у чергу лист, воркер узяв завдання за 10 мілісекунд і пішов на репліку, де замовлення ще немає. Сесії у воркера немає, тож позицію передаємо в саме завдання:

```php
  $order = DB::transaction(function () use ($data) {
      $order = Order::create($data);
      $order->items()->createMany($data['items']);

      return $order;
  });

  // після коміту транзакції, не всередині неї
  SendOrderConfirmation::dispatch($order->id, DB::getLastCommitId());
```

```php
  class SendOrderConfirmation implements ShouldQueue
  {
      use Queueable;

      public function __construct(
          public int $orderId,
          public string $commitId,
      ) {}

      public function handle(): void
      {
          if (DB::hasCommitId($this->commitId, wait: 2)) {
              $this->send();

              return;
          }

          // репліка не встигла - разово читаємо з primary
          DB::usingWritePdo(fn () => $this->send());
      }

      protected function send(): void
      {
          $order = Order::with('items', 'customer')->findOrFail($this->orderId);

          Mail::to($order->customer)->send(new OrderConfirmation($order));
      }
  }
```

Тут `wait` якраз доречний: завдання і так фонове, дві секунди очікування дешевші за запит до primary. Три деталі, на яких легко помилитися:

- **`getLastCommitId()` - після транзакції.** Усередині неї замовлення ще не закомічено, і позиція його не покриває.
- **У конструктор - ідентифікатор, а не модель.** Із серіалізацією моделей Laravel завантажує модель до виклику `handle()`, тобто до перевірки, і на відсталій репліці отримуєте `ModelNotFoundException`.
- **`usingWritePdo()`, а не `useWriteConnectionWhenReading()`.** Воркер тримає з'єднання між завданнями, і `usingWritePdo()` повертає попередній стан після колбека. Інакше всі наступні завдання воркера теж читатимуть з primary - та сама проблема, яку Laravel 13.36 розв'язував для `sticky` через `Worker::$flushStickyConnections`.

### Що перевірити на сервері

Без налаштувань СУБД методи не працюють, і `getLastCommitId()` кидає `RuntimeException` із назвою того, чого бракує:

- **MySQL**: `log_bin` і `gtid_mode = ON` (а `gtid_mode = ON` у MySQL вимагає й `enforce_gtid_consistency = ON`). MySQL 8 вмикає бінарний лог за замовчуванням, але GTID - ні. Увімкнення GTID на працюючому кластері - окрема процедура з кількох кроків, а не одна зміна конфігу; плануйте її разом з адміністратором бази.
- **MariaDB**: `log_bin`, який за замовчуванням вимкнено. GTID у MariaDB є завжди, окремо їх вмикати не треба.
- **PostgreSQL**: на сервері нічого вмикати не треба, але `wait` потребує PostgreSQL 19. На попередніх версіях працює лише миттєва перевірка - для вебзапитів цього досить, а в черзі доведеться повторювати перевірку самому або одразу йти на primary.
- **Керовані сервіси** (RDS, Cloud SQL, PlanetScale тощо) можуть не дозволяти змінювати ці параметри або мати власні обмеження на системні функції. Окремих прав PR не згадує, але перш ніж будувати на цьому логіку, проженіть `DB::getLastCommitId()` і `DB::hasCommitId()` на staging з тією самою конфігурацією, що й у продакшені.

Ще одна умова - самі репліки мають бути саме репліками цього primary, а не, скажімо, логічною реплікацією в іншу базу: позиція WAL чи GTID має сенс лише в межах одного ланцюжка реплікації. Для схем із кількома primary (multi-source replication у MySQL) якраз і потрібен `mergeCommitIds()`.

### Чи варто переходити

Якщо ви вже ввімкнули `PreventStaleDatabaseReads` і не бачите ні старих даних, ні помітного навантаження на primary, поспішати немає куди. Commit ID окупається, коли вікно стало компромісом: затримка реплікації часом сягає секунд, а більшість часу вона мізерна, і ви платите за найгірший випадок постійно. Тоді власний `middleware` з позицією в сесії знімає з primary майже всі такі читання і водночас не пропускає жодного випадку відставання.

Для черг перевага ще очевидніша: передати commit ID у завдання і почекати на репліку дешевше, ніж для кожного завдання йти на primary чи ловити `ModelNotFoundException`.

Почніть з перевірки конфігурації: виклик `DB::getLastCommitId()` в `php artisan tinker` на продакшен-подібному середовищі одразу покаже, чи ввімкнено все потрібне. Тобіас Петрі пише, що наступним кроком хоче перевести на commit ID і сам `PreventStaleDatabaseReads`, а також передавати позицію в завдання з `after_commit`. Поки що це лише плани з опису PR, тож до того часу код із цієї статті доведеться тримати у себе. Про інші зміни випуску - у нашому [огляді Laravel 13.40](https://laravelukraine.com/blog/laravel-1340-dovgi-zavdannia-cergi-insertbefore-dlia-middleware-i-strict-dlia-zapitu).
