re:re:actable
Урок 033 минуты чтения

Как управлять порядком запуска через depends_on и healthcheck

На этой странице
Кратко

depends_on в короткой форме (depends_on: [db]) лишь гарантирует, что контейнер db запущен раньше api, — но не что PostgreSQL уже принимает подключения. Чтобы дождаться готовности, нужна длинная форма с условием: service_healthy (зависимость прошла healthcheck) или service_completed_successfully (одноразовая задача вроде миграций завершилась с кодом 0). Даже так приложение должно уметь переподключаться: база может перезапуститься в любой момент.

Вопрос

Как в Compose запустить сервисы в правильном порядке и дождаться готовности зависимостей?

Короткая форма — только порядок

services:
  api:
    build: .
    depends_on:
      - db
  db:
    image: postgres:18

Compose создаст и запустит db раньше api. Но PostgreSQL инициализируется несколько секунд, и api может упасть с ECONNREFUSED.

Длинная форма — готовность

services:
  api:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true          # перезапустить api, если db перезапустили через Compose
      redis:
        condition: service_started
 
  db:
    image: postgres:18
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s
 
  redis:
    image: redis:8-alpine
УсловиеЖдёт
service_startedКонтейнер запущен (поведение короткой формы)
service_healthyHealthcheck зависимости вернул healthy
service_completed_successfullyЗависимость завершилась с кодом 0

Если зависимость так и не стала healthy, docker compose up завершится с ошибкой — это лучше, чем API, который молча работает без базы.

Миграции перед стартом

services:
  migrate:
    build: .
    command: ["npx", "prisma", "migrate", "deploy"]
    depends_on:
      db:
        condition: service_healthy
 
  api:
    build: .
    depends_on:
      migrate:
        condition: service_completed_successfully
db (healthy) ──▶ migrate (exit 0) ──▶ api

Остановка

При docker compose down и stop порядок обратный: сначала api, потом db. Так API успевает закрыть соединения до остановки базы.

Почему приложению всё равно нужен retry

depends_on работает только при запуске через Compose. Он не поможет, если:

  • база перезапустилась через час работы;
  • сеть кратковременно пропала;
  • в production используется другая платформа, не знающая про depends_on.

Поэтому клиент БД настраивают с повторными подключениями и экспоненциальной задержкой, а healthcheck API помечает сервис unhealthy, пока соединения нет.

Старые решения

Раньше в command добавляли скрипты wait-for-it.sh или dockerize, которые опрашивали порт. С условиями service_healthy это обычно не нужно — к тому же открытый порт не означает, что база готова.

Частые ошибки

  • Считать, что depends_on: [db] ждёт готовности.
  • Указать service_healthy без healthcheck у зависимости — Compose выдаст ошибку.
  • Запускать миграции в command каждой реплики API.
  • Полагаться только на Compose и не писать логику переподключения.

Что важно помнить

  • Порядок ≠ готовность; готовность даёт только healthcheck.
  • service_completed_successfully — способ встроить одноразовые задачи (миграции, seed) в граф запуска.
  • restart: true в depends_on перезапускает зависимый сервис при перезапуске зависимости через Compose.

Мини-шпаргалка

  • depends_on: [db] — только порядок.
  • condition: service_healthy + healthcheck — готовность.
  • condition: service_completed_successfully — миграции.
  • Остановка — в обратном порядке.
  • Retry в коде обязателен.

Документация

Docker: Control startup and shutdown order, Docker Compose: depends_on.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам