Чому depends_on не гарантує, що база готова, і як це виправити?

depends_on: [db] у звичайній формі гарантує лише порядок запуску контейнерів: db стартує раніше за app. Але «контейнер запущено» - не «база приймає з'єднання». PostgreSQL ще кілька секунд ініціалізується, а застосунок уже пробує підключитися й падає.

Рішення - healthcheck + умова:

services:
  db:
    image: postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER}"]
      interval: 5s
      timeout: 3s
      retries: 10

  app:
    build: .
    depends_on:
      db:
        condition: service_healthy

Тепер app стартує лише тоді, коли healthcheck бази почав проходити.

Інші умови:

• service_started - поведінка за замовчуванням.
• service_completed_successfully - дочекатися, поки разовий контейнер завершиться з кодом 0. Зручно для міграцій: окремий сервіс migrate запускається, виконує php artisan migrate --force і завершується, а app стартує після нього.

Але на цьому не зупиняються: depends_on працює лише при старті через Compose. База може перезапуститися пізніше, а на проді застосунок часто запускають оркестратором без Compose. Тому застосунок сам має бути стійким до тимчасової недоступності залежностей: повторні спроби підключення, коректні помилки, а не падіння при першому ж збої.

Healthcheck для самого застосунку (наприклад, на маршрут /up у Laravel) потрібен і проксі, і оркестратору - щоб не відправляти трафік у контейнер, що ще не готовий.

Докладніше в документації: Порядок запуску в Compose