Provision
—— XP

Практика: цепочка база → миграция → приложение

практика~40 минут+425 XP

В прошлой практике таблицу создали руками в psql, а приложение запускалось «после базы» только в смысле порядка запуска контейнеров. Исправим оба места: таблицу будет создавать отдельный сервис миграции, а приложение дождётся и готовности базы, и окончания миграции.

Начнём с самого простого сервиса миграции, который запускается, и будем смотреть, где он нас обманывает: ошибку выдаёт за успех, крутится бесконечно, стартует раньше базы. Каждую находку закроем одной-двумя строками. В конце сломаем цепочку нарочно и посмотрим, как выглядит сбой.

Шаг 1. Файл миграции

Миграция — файл с командами SQL, которые приводят таблицы к нужному виду. Положим его в репозиторий рядом с описанием стенда.

ubuntu@stand:~$
mkdir -p ~/infra/stand/migrations

В файл — та же команда, что ты вводил руками в прошлой практике.

nano ~/infra/stand/migrations/001-visits.sql
CREATE TABLE visits (id serial PRIMARY KEY);

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

Шаг 2. Самый простой сервис миграции

Миграцию выполнит тот же образ PostgreSQL: в нём есть клиент psql. Добавь новый сервис в раздел services, между app и db.

в compose.yaml, раздел services
  migrate:
    image: postgres:17-alpine
    command: ["psql", "-f", "/migrations/001-visits.sql"]
    environment:
      PGHOST: db
      PGUSER: provision
      PGPASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./migrations:/migrations:ro
    networks:
      - stand

Разберём. command заменяет команду образа: вместо сервера базы запускается клиент, который выполнит файл (-f) и выйдет. Переменные PGHOST, PGUSER и PGPASSWORD psql читает сам: куда, кем и с каким паролем подключаться. Каталог с миграциями подключается внутрь, а :ro в конце делает его доступным только на чтение — миграции незачем что-то в нём менять. Сеть stand — та же, что у базы: без неё миграция попала бы в сеть default и не нашла бы db по имени.

Проверим, что Compose понял описание. Флаг --services у config печатает только список сервисов.

ubuntu@stand:~$
cd ~/infra/stand
ubuntu@stand:~$
docker compose config --services
ubuntu@stand:~$
db
app
migrate

Три сервиса. Если вместо списка ошибка, почти всегда это отступ в добавленном блоке.

Шаг 3. Ошибка, а код 0

Поднимаем стек. База и приложение уже работают, Compose добавит только новый сервис.

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
[+] Running 3/3
 ✔ Container provision-app-1      Running
 ✔ Container provision-db-1       Running
 ✔ Container provision-migrate-1  Started

Флаг -a у ps показывает и завершившиеся контейнеры: без него разовую задачу после выхода не видно вовсе.

ubuntu@stand:~$
docker compose ps -a
ubuntu@stand:~$
NAME                  SERVICE   STATUS
provision-app-1       app       Up 15 seconds (health: starting)
provision-db-1        db        Up 15 seconds
provision-migrate-1   migrate   Exited (0) 3 seconds ago

Exited (0) — задача завершилась, код 0 означает успех. Но заглянем в журнал миграции.

ubuntu@stand:~$
docker compose logs migrate
ubuntu@stand:~$
migrate-1  | psql:/migrations/001-visits.sql:1: ERROR:  relation "visits" already exists

Таблица уже есть с прошлой практики, и команда упала с ошибкой. А код всё равно 0. Так psql устроен по умолчанию: он сообщает об ошибке, идёт к следующей строке файла и в конце выходит с успехом. Для миграции это опасно — Compose и всё, что ждёт миграцию, поверят, что она прошла.

Шаг 4. Остановиться на первой ошибке

Переменная ON_ERROR_STOP=1 велит psql остановиться на первой ошибке и выйти с ненулевым кодом. Передаётся она флагом -v. Замени строку command.

в compose.yaml, у сервиса migrate
    command: ["psql", "-v", "ON_ERROR_STOP=1", "-f", "/migrations/001-visits.sql"]

Поднимаем снова: описание сервиса изменилось, и Compose пересоздаст его контейнер.

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
[+] Running 3/3
 ✔ Container provision-app-1      Running
 ✔ Container provision-db-1       Running
 ✔ Container provision-migrate-1  Started
ubuntu@stand:~$
docker compose ps -a migrate
ubuntu@stand:~$
NAME                  SERVICE   STATUS
provision-migrate-1   migrate   Exited (3) 3 seconds ago

Теперь честно: код 3. У psql он означает «ошибка в выполняемом файле». Бывают ещё 1 — фатальная ошибка самого psql — и 2 — не удалось подключиться к серверу; код 2 мы скоро увидим.

Шаг 5. Миграция, которую можно повторять

Миграция будет выполняться при каждом подъёме стека, а таблица после первого раза уже есть. Значит, сама команда должна спокойно переносить повтор. В SQL для этого есть IF NOT EXISTS: таблица уже есть — ничего не делать. Перепиши файл.

nano ~/infra/stand/migrations/001-visits.sql
CREATE TABLE IF NOT EXISTS visits (id serial PRIMARY KEY);
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
[+] Running 3/3
 ✔ Container provision-app-1      Running
 ✔ Container provision-db-1       Running
 ✔ Container provision-migrate-1  Started
ubuntu@stand:~$
docker compose logs migrate
ubuntu@stand:~$
migrate-1  | psql:/migrations/001-visits.sql:1: ERROR:  relation "visits" already exists
migrate-1  | psql:/migrations/001-visits.sql:1: NOTICE:  relation "visits" already exists, skipping
migrate-1  | CREATE TABLE

Первая строка — от прошлого запуска: журнал контейнера хранит все его запуски, пока контейнер не удалят. Свежие строки — две нижние: NOTICE … skipping, то есть «таблица есть, пропускаю», и CREATE TABLE без ошибки. docker compose ps -a migrate покажет Exited (0), и теперь этому нулю можно верить. Данные на месте.

ubuntu@stand:~$
curl -s localhost:8012/items
ubuntu@stand:~$
{"visits":1}

Свойство «повтор ничего не ломает» называется идемпотентностью. Его требуют от любой миграции, которую запускают автоматически. В настоящих проектах номера выполненных миграций ещё и записывают в отдельную таблицу, чтобы не выполнять их повторно вовсе, — так работают Flyway, Liquibase, Alembic и другие инструменты миграций. Нам пока хватит одного файла.

Шаг 6. Разовой задаче не нужен перезапуск

У app и db стоит restart: unless-stopped, и рука тянется скопировать его в новый сервис. Попробуем: допиши эту строку сервису migrate, после блока volumes.

в compose.yaml, у сервиса migrate
    restart: unless-stopped
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
[+] Running 3/3
 ✔ Container provision-app-1      Running
 ✔ Container provision-db-1       Running
 ✔ Container provision-migrate-1  Started

Подожди секунд двадцать и посмотри на миграцию.

ubuntu@stand:~$
docker compose ps -a migrate
ubuntu@stand:~$
NAME                  SERVICE   STATUS
provision-migrate-1   migrate   Restarting (0) 5 seconds ago

Restarting: миграция закончила работу, а Docker запустил её снова, потому что так велит политика. Сколько раз — покажет docker inspect.

ubuntu@stand:~$
docker inspect -f '{{.RestartCount}}' provision-migrate-1
ubuntu@stand:~$
8

Восемь запусков за двадцать секунд, и так без конца. Задача, которая должна завершиться, с такой политикой не завершится никогда — а приложение, которое её ждёт, не дождётся. Замени строку.

в compose.yaml, у сервиса migrate
    restart: "no"

Кавычки обязательны: без них YAML прочитает no как «ложь», а не как слово. "no" — это и так значение по умолчанию, строку можно было не писать вовсе. Мы пишем её явно, чтобы следующий читатель файла увидел решение и не «исправил» его по примеру соседей. Есть и промежуточный вариант — on-failure: перезапускать только при ненулевом коде. Для миграции он тоже плох: сломанная миграция будет крутиться так же бесконечно.

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
[+] Running 3/3
 ✔ Container provision-app-1      Running
 ✔ Container provision-db-1       Running
 ✔ Container provision-migrate-1  Started

Шаг 7. Приложение ждёт миграцию

Пока что приложению всё равно, прошла миграция или нет. Короткая запись depends_on: [db] умеет только одно — запустить контейнер после контейнера. Длинная запись добавляет условие. У сервиса app замени блок depends_on.

в compose.yaml, у сервиса app
    depends_on:
      db:
        condition: service_started
      migrate:
        condition: service_completed_successfully

service_started — то же, что делала короткая запись: контейнер запущен. service_completed_successfully — контейнер завершился с кодом 0. Проверим цепочку с самого начала: снимем стек целиком и поднимем.

ubuntu@stand:~$
docker compose down
ubuntu@stand:~$
[+] Running 4/4
 ✔ Container provision-app-1      Removed
 ✔ Container provision-migrate-1  Removed
 ✔ Container provision-db-1       Removed
 ✔ Network provision_stand        Removed
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
[+] Running 2/3
 ✔ Container provision-db-1       Started
 ✘ Container provision-migrate-1  service "migrate" didn't complete successfully: exit 2

Приложение не запустилось — условие сработало. Но почему упала миграция?

ubuntu@stand:~$
docker compose logs migrate
ubuntu@stand:~$
migrate-1  | psql: error: connection to server at "db" (192.168.64.3), port 5432 failed: Connection refused
migrate-1  | 	Is the server running on that host and accepting TCP/IP connections?

Код 2 — не удалось подключиться. Миграция стартовала одновременно с базой, а PostgreSQL ещё поднимался и не принимал подключения. Запущенный контейнер ещё не готовая база.

Шаг 8. База сообщает о готовности

Нужна проверка здоровья, как у приложения в Dockerfile. В образе PostgreSQL для этого есть утилита pg_isready: она отвечает кодом 0, когда сервер принимает подключения. Добавь сервису db блок healthcheck, с тем же отступом, что у volumes.

в compose.yaml, у сервиса db
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U provision"]

CMD-SHELL — выполнить строку через оболочку внутри контейнера. Теперь пусть ждут здоровья. Миграции — новый блок, приложению — замена условия у db.

в compose.yaml, у сервиса migrate
    depends_on:
      db:
        condition: service_healthy
в compose.yaml, у сервиса app, внутри depends_on
      db:
        condition: service_healthy

Снова с начала, и замерим время: команда time перед любой другой меряет, сколько та работала.

ubuntu@stand:~$
docker compose down
ubuntu@stand:~$
[+] Running 4/4
 ✔ Container provision-app-1      Removed
 ✔ Container provision-migrate-1  Removed
 ✔ Container provision-db-1       Removed
 ✔ Network provision_stand        Removed
ubuntu@stand:~$
time docker compose up -d
ubuntu@stand:~$
[+] Running 3/3
 ✔ Container provision-db-1       Healthy
 ✔ Container provision-migrate-1  Exited
 ✔ Container provision-app-1      Started
real    0m32.112s

Порядок виден прямо в выводе: база стала Healthy, миграция отработала и вышла, только потом стартовало приложение. Но тридцать две секунды на подъём — слишком долго для базы, которая готова через пару секунд.

Шаг 9. Как часто проверять

По умолчанию Docker проверяет здоровье раз в 30 секунд, и первая проверка тоже наступает через 30. Всё это время база готова, а Compose об этом не знает. Допиши параметры к блоку проверки.

в compose.yaml, у сервиса db
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U provision"]
      interval: 5s
      retries: 10
      start_period: 10s

interval: 5s — проверять каждые пять секунд. retries: 10 — сколько неудач подряд терпеть, прежде чем объявить базу unhealthy (по умолчанию 3). start_period: 10s — неудачи в первые десять секунд не считаются: база на пустом томе сначала создаёт файлы, и это не авария.

Флаг -h 127.0.0.1 направляет проверку по сети, а не через внутренний сокет. На пустом томе PostgreSQL сначала запускается временно, только на сокете, чтобы создать пользователя и базу, а потом перезапускается. Проверка через сокет объявила бы базу готовой в этот промежуток, и миграция пришла бы к серверу, который вот-вот выключится. По сети временный сервер не слушает — проверка дождётся настоящего. Подробнее — в уроке про готовность.

ubuntu@stand:~$
docker compose down
ubuntu@stand:~$
[+] Running 4/4
 ✔ Container provision-app-1      Removed
 ✔ Container provision-migrate-1  Removed
 ✔ Container provision-db-1       Removed
 ✔ Network provision_stand        Removed
ubuntu@stand:~$
time docker compose up -d
ubuntu@stand:~$
[+] Running 3/3
 ✔ Container provision-db-1       Healthy
 ✔ Container provision-migrate-1  Exited
 ✔ Container provision-app-1      Started
real    0m6.993s

Семь секунд вместо тридцати двух. Состояние всех трёх сервисов:

ubuntu@stand:~$
docker compose ps -a
ubuntu@stand:~$
NAME                  SERVICE   STATUS
provision-app-1       app       Up 2 seconds (health: starting)
provision-db-1        db        Up 8 seconds (healthy)
provision-migrate-1   migrate   Exited (0) 2 seconds ago

Exited (0) у миграции — выполненная работа, а не авария. (healthy) у базы — результат проверки из этого шага.

Шаг 10. Сломать миграцию

Цепочка готова, проверим её на сбое. Испортим файл миграции: допишем строку с опечаткой в команде SQL.

ubuntu@stand:~$
echo 'SELEC 1;' >> migrations/001-visits.sql

Снимаем стек и поднимаем заново, чтобы цепочка прошла с начала.

ubuntu@stand:~$
docker compose down
ubuntu@stand:~$
[+] Running 4/4
 ✔ Container provision-app-1      Removed
 ✔ Container provision-migrate-1  Removed
 ✔ Container provision-db-1       Removed
 ✔ Network provision_stand        Removed
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
[+] Running 2/3
 ✔ Container provision-db-1       Healthy
 ✘ Container provision-migrate-1  service "migrate" didn't complete successfully: exit 3

Приложение не запустилось: условие service_completed_successfully не выполнено. Причина — в журнале миграции.

ubuntu@stand:~$
docker compose logs migrate
ubuntu@stand:~$
migrate-1  | psql:/migrations/001-visits.sql:1: NOTICE:  relation "visits" already exists, skipping
migrate-1  | psql:/migrations/001-visits.sql:2: ERROR:  syntax error at or near "SELEC"
migrate-1  | LINE 1: SELEC 1;
migrate-1  |         ^

Строка 2 файла, точное место ошибки. Убираем её: sed с командой /SELEC/d удаляет строки, где встретилось это слово.

ubuntu@stand:~$
sed -i '/SELEC/d' migrations/001-visits.sql
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
[+] Running 3/3
 ✔ Container provision-db-1       Healthy
 ✔ Container provision-migrate-1  Exited
 ✔ Container provision-app-1      Started

Шаг 11. Уронить базу на ходу

Теперь сбой после старта. Останавливаем только базу.

ubuntu@stand:~$
docker compose stop db

Приложение живо? Флаг -o /dev/null у curl выбрасывает тело ответа, -w '%{http_code}' печатает только код.

ubuntu@stand:~$
curl -s -o /dev/null -w '%{http_code}' localhost:8012/health
ubuntu@stand:~$
200

Проверка здоровья в базу не ходит, и это правильно: иначе Docker посчитал бы больным приложение, когда болеет база. А адрес с данными?

ubuntu@stand:~$
curl -s -w ' %{http_code}' localhost:8012/items
ubuntu@stand:~$
{"error":"database unavailable"} 503

Приложение честно отвечает кодом 503 и не падает. Посмотрим, что с ним сделал Compose.

ubuntu@stand:~$
docker compose ps
ubuntu@stand:~$
NAME              SERVICE   STATUS
provision-app-1   app       Up 2 seconds (health: starting)

Приложение не перезапускалось: Up 2 seconds идёт с подъёма в прошлом шаге. depends_on действует только на старте. Возвращаем базу.

ubuntu@stand:~$
docker compose start db
ubuntu@stand:~$
curl -s localhost:8012/items
ubuntu@stand:~$
{"visits":1}

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

Шаг 12. Отчёт и коммит

Запиши, что увидел при двух сбоях.

ubuntu@stand:~$
nano ~/devops-lab/reports/compose-chain.txt
пример отчёта
сломанная миграция: migrate exit 3, app не запустился
  причина нашлась в docker compose logs migrate, строка 2
база остановлена на ходу: /health 200, /items 503
  app не перезапускался, после start db всё вернулось
ubuntu@stand:~$
git -C ~/infra add stand
ubuntu@stand:~$
git -C ~/infra commit -m "stand: миграция"

Если что-то не работает

Цепочка ломается в предсказуемых местах.

Симптом и причина
dependency failed to start: container provision-db-1 is unhealthy
Проверка базы не проходит: в pg_isready не тот пользователь или start_period слишком мал.
migrate: password authentication failed
PGPASSWORD не совпадает с паролем базы: проверь подстановку в docker compose config.
migrate: No such file or directory
Каталог migrations не смонтирован или файл назван иначе.
services.migrate Additional property … is not allowed
Блок сдвинут: ключ оказался не на том уровне отступа.

Что спросят на собеседовании

  • Почему миграцию запускают отдельным сервисом, а не руками?
    Руками её однажды забудут. Отдельный сервис выполняется при каждом подъёме, а приложение не стартует, пока он не завершится с кодом 0.
  • Зачем миграции IF NOT EXISTS?
    Миграция выполняется при каждом up. Без идемпотентности второй запуск упадёт на уже существующей таблице и остановит всю цепочку.
Практика 02+425 XP

Собрать цепочку «база готова → миграция отработала → приложение стартовало» и увидеть, как стенд ведёт себя при двух разных сбоях.

  • База проходит проверку здоровья
  • Миграция отработала и завершилась
  • Приложение работает
  • Приложение читает таблицу, созданную миграцией
  • Порядок описан условиями готовности
  • Миграция не перезапускается
  • Отчёт о сбоях составлен
Команда сдачи — выполни на своей машине
команда
cd ~/infra/stand 2>/dev/null || echo NOSTAND; docker compose ps -a --format 'SVC={{.Service}} STATE={{.State}} EXIT={{.ExitCode}} HEALTH={{.Health}}'; echo "ITEMS=$(curl -s localhost:8012/items)"; grep -E 'condition|restart: .no' compose.yaml; cat ~/devops-lab/reports/compose-chain.txt

Нашёл ошибку или непонятное место? Наведи на абзац — слева появится «+», нажми и напиши, что не так. Замечание увидит автор курса.Нашёл ошибку или непонятное место? Нажми «+» справа от заголовка раздела и напиши, что не так. Замечание увидит автор курса.