В прошлой практике таблицу создали руками в psql, а приложение запускалось «после базы» только в смысле порядка запуска контейнеров. Исправим оба места: таблицу будет создавать отдельный сервис миграции, а приложение дождётся и готовности базы, и окончания миграции.
Начнём с самого простого сервиса миграции, который запускается, и будем смотреть, где он нас обманывает: ошибку выдаёт за успех, крутится бесконечно, стартует раньше базы. Каждую находку закроем одной-двумя строками. В конце сломаем цепочку нарочно и посмотрим, как выглядит сбой.
Шаг 1. Файл миграции
Миграция — файл с командами SQL, которые приводят таблицы к нужному виду. Положим его в репозиторий рядом с описанием стенда.
mkdir -p ~/infra/stand/migrationsВ файл — та же команда, что ты вводил руками в прошлой практике.
CREATE TABLE visits (id serial PRIMARY KEY);Номер в имени файла задаёт порядок: следующая миграция будет 002-…, и выполнять их надо по очереди.
Шаг 2. Самый простой сервис миграции
Миграцию выполнит тот же образ PostgreSQL: в нём есть клиент psql. Добавь новый сервис в раздел services, между app и db.
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 печатает только список сервисов.
cd ~/infra/standdocker compose config --servicesdb app migrate
Три сервиса. Если вместо списка ошибка, почти всегда это отступ в добавленном блоке.
Шаг 3. Ошибка, а код 0
Поднимаем стек. База и приложение уже работают, Compose добавит только новый сервис.
docker compose up -d[+] Running 3/3 ✔ Container provision-app-1 Running ✔ Container provision-db-1 Running ✔ Container provision-migrate-1 Started
Флаг -a у ps показывает и завершившиеся контейнеры: без него разовую задачу после выхода не видно вовсе.
docker compose ps -aNAME 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 означает успех. Но заглянем в журнал миграции.
docker compose logs migratemigrate-1 | psql:/migrations/001-visits.sql:1: ERROR: relation "visits" already existsТаблица уже есть с прошлой практики, и команда упала с ошибкой. А код всё равно 0. Так psql устроен по умолчанию: он сообщает об ошибке, идёт к следующей строке файла и в конце выходит с успехом. Для миграции это опасно — Compose и всё, что ждёт миграцию, поверят, что она прошла.
Шаг 4. Остановиться на первой ошибке
Переменная ON_ERROR_STOP=1 велит psql остановиться на первой ошибке и выйти с ненулевым кодом. Передаётся она флагом -v. Замени строку command.
command: ["psql", "-v", "ON_ERROR_STOP=1", "-f", "/migrations/001-visits.sql"]Поднимаем снова: описание сервиса изменилось, и Compose пересоздаст его контейнер.
docker compose up -d[+] Running 3/3 ✔ Container provision-app-1 Running ✔ Container provision-db-1 Running ✔ Container provision-migrate-1 Started
docker compose ps -a migrateNAME SERVICE STATUS provision-migrate-1 migrate Exited (3) 3 seconds ago
Теперь честно: код 3. У psql он означает «ошибка в выполняемом файле». Бывают ещё 1 — фатальная ошибка самого psql — и 2 — не удалось подключиться к серверу; код 2 мы скоро увидим.
Шаг 5. Миграция, которую можно повторять
Миграция будет выполняться при каждом подъёме стека, а таблица после первого раза уже есть. Значит, сама команда должна спокойно переносить повтор. В SQL для этого есть IF NOT EXISTS: таблица уже есть — ничего не делать. Перепиши файл.
CREATE TABLE IF NOT EXISTS visits (id serial PRIMARY KEY);docker compose up -d[+] Running 3/3 ✔ Container provision-app-1 Running ✔ Container provision-db-1 Running ✔ Container provision-migrate-1 Started
docker compose logs migratemigrate-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), и теперь этому нулю можно верить. Данные на месте.
curl -s localhost:8012/items{"visits":1}Свойство «повтор ничего не ломает» называется идемпотентностью. Его требуют от любой миграции, которую запускают автоматически. В настоящих проектах номера выполненных миграций ещё и записывают в отдельную таблицу, чтобы не выполнять их повторно вовсе, — так работают Flyway, Liquibase, Alembic и другие инструменты миграций. Нам пока хватит одного файла.
Шаг 6. Разовой задаче не нужен перезапуск
У app и db стоит restart: unless-stopped, и рука тянется скопировать его в новый сервис. Попробуем: допиши эту строку сервису migrate, после блока volumes.
restart: unless-stoppeddocker compose up -d[+] Running 3/3 ✔ Container provision-app-1 Running ✔ Container provision-db-1 Running ✔ Container provision-migrate-1 Started
Подожди секунд двадцать и посмотри на миграцию.
docker compose ps -a migrateNAME SERVICE STATUS provision-migrate-1 migrate Restarting (0) 5 seconds ago
Restarting: миграция закончила работу, а Docker запустил её снова, потому что так велит политика. Сколько раз — покажет docker inspect.
docker inspect -f '{{.RestartCount}}' provision-migrate-18Восемь запусков за двадцать секунд, и так без конца. Задача, которая должна завершиться, с такой политикой не завершится никогда — а приложение, которое её ждёт, не дождётся. Замени строку.
restart: "no"Кавычки обязательны: без них YAML прочитает no как «ложь», а не как слово. "no" — это и так значение по умолчанию, строку можно было не писать вовсе. Мы пишем её явно, чтобы следующий читатель файла увидел решение и не «исправил» его по примеру соседей. Есть и промежуточный вариант — on-failure: перезапускать только при ненулевом коде. Для миграции он тоже плох: сломанная миграция будет крутиться так же бесконечно.
docker compose up -d[+] 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.
depends_on: db: condition: service_started migrate: condition: service_completed_successfully
service_started — то же, что делала короткая запись: контейнер запущен. service_completed_successfully — контейнер завершился с кодом 0. Проверим цепочку с самого начала: снимем стек целиком и поднимем.
docker compose down[+] Running 4/4 ✔ Container provision-app-1 Removed ✔ Container provision-migrate-1 Removed ✔ Container provision-db-1 Removed ✔ Network provision_stand Removed
docker compose up -d[+] Running 2/3 ✔ Container provision-db-1 Started ✘ Container provision-migrate-1 service "migrate" didn't complete successfully: exit 2
Приложение не запустилось — условие сработало. Но почему упала миграция?
docker compose logs migratemigrate-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.
healthcheck: test: ["CMD-SHELL", "pg_isready -U provision"]
CMD-SHELL — выполнить строку через оболочку внутри контейнера. Теперь пусть ждут здоровья. Миграции — новый блок, приложению — замена условия у db.
depends_on: db: condition: service_healthy
db: condition: service_healthy
Снова с начала, и замерим время: команда time перед любой другой меряет, сколько та работала.
docker compose down[+] Running 4/4 ✔ Container provision-app-1 Removed ✔ Container provision-migrate-1 Removed ✔ Container provision-db-1 Removed ✔ Network provision_stand Removed
time docker compose up -d[+] 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 об этом не знает. Допиши параметры к блоку проверки.
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 сначала запускается временно, только на сокете, чтобы создать пользователя и базу, а потом перезапускается. Проверка через сокет объявила бы базу готовой в этот промежуток, и миграция пришла бы к серверу, который вот-вот выключится. По сети временный сервер не слушает — проверка дождётся настоящего. Подробнее — в уроке про готовность.
docker compose down[+] Running 4/4 ✔ Container provision-app-1 Removed ✔ Container provision-migrate-1 Removed ✔ Container provision-db-1 Removed ✔ Network provision_stand Removed
time docker compose up -d[+] Running 3/3 ✔ Container provision-db-1 Healthy ✔ Container provision-migrate-1 Exited ✔ Container provision-app-1 Started real 0m6.993s
Семь секунд вместо тридцати двух. Состояние всех трёх сервисов:
docker compose ps -aNAME 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.
echo 'SELEC 1;' >> migrations/001-visits.sqlСнимаем стек и поднимаем заново, чтобы цепочка прошла с начала.
docker compose down[+] Running 4/4 ✔ Container provision-app-1 Removed ✔ Container provision-migrate-1 Removed ✔ Container provision-db-1 Removed ✔ Network provision_stand Removed
docker compose up -d[+] Running 2/3 ✔ Container provision-db-1 Healthy ✘ Container provision-migrate-1 service "migrate" didn't complete successfully: exit 3
Приложение не запустилось: условие service_completed_successfully не выполнено. Причина — в журнале миграции.
docker compose logs migratemigrate-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 удаляет строки, где встретилось это слово.
sed -i '/SELEC/d' migrations/001-visits.sqldocker compose up -d[+] Running 3/3 ✔ Container provision-db-1 Healthy ✔ Container provision-migrate-1 Exited ✔ Container provision-app-1 Started
Шаг 11. Уронить базу на ходу
Теперь сбой после старта. Останавливаем только базу.
docker compose stop dbПриложение живо? Флаг -o /dev/null у curl выбрасывает тело ответа, -w '%{http_code}' печатает только код.
curl -s -o /dev/null -w '%{http_code}' localhost:8012/health200Проверка здоровья в базу не ходит, и это правильно: иначе Docker посчитал бы больным приложение, когда болеет база. А адрес с данными?
curl -s -w ' %{http_code}' localhost:8012/items{"error":"database unavailable"} 503Приложение честно отвечает кодом 503 и не падает. Посмотрим, что с ним сделал Compose.
docker compose psNAME SERVICE STATUS provision-app-1 app Up 2 seconds (health: starting)
Приложение не перезапускалось: Up 2 seconds идёт с подъёма в прошлом шаге. depends_on действует только на старте. Возвращаем базу.
docker compose start dbcurl -s localhost:8012/items{"visits":1}Соединение восстановилось само: приложение подключается к базе на каждый запрос.
Шаг 12. Отчёт и коммит
Запиши, что увидел при двух сбоях.
nano ~/devops-lab/reports/compose-chain.txtсломанная миграция: migrate exit 3, app не запустился причина нашлась в docker compose logs migrate, строка 2 база остановлена на ходу: /health 200, /items 503 app не перезапускался, после start db всё вернулось
git -C ~/infra add standgit -C ~/infra commit -m "stand: миграция"Если что-то не работает
Цепочка ломается в предсказуемых местах.
Что спросят на собеседовании
- Почему миграцию запускают отдельным сервисом, а не руками?Руками её однажды забудут. Отдельный сервис выполняется при каждом подъёме, а приложение не стартует, пока он не завершится с кодом 0.
- Зачем миграции IF NOT EXISTS?Миграция выполняется при каждом up. Без идемпотентности второй запуск упадёт на уже существующей таблице и остановит всю цепочку.