From 8fb78f90863ea35428cf72e8f110877f84bd3299 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Wed, 10 Dec 2025 22:52:08 +0300 Subject: [PATCH] =?UTF-8?q?fix:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D0=BD=D1=8B=20airflow=20connections=20=D0=B8=20?= =?UTF-8?q?=D0=BE=D0=B1=D0=BD=D0=BE=D0=B2=D0=BB=D0=B5=D0=BD=D0=B0=20=D1=81?= =?UTF-8?q?=D1=82=D1=80=D1=83=D0=BA=D1=82=D1=83=D1=80=D0=B0=20=D0=B7=D0=B0?= =?UTF-8?q?=D0=BF=D1=83=D1=81=D0=BA=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 8 ++++---- README.md | 10 +++++----- TESTING.md | 7 +++---- docker-compose.yml | 6 ++++++ docs/internal/bookings_stg_readme.md | 3 +-- docs/internal/pxf_bookings.md | 4 +--- educational-tasks.md | 2 +- 7 files changed, 21 insertions(+), 19 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0fb94f8..1b9795b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,14 +11,14 @@ - `.env(.example)` — настройки окружения (реальные секреты не коммитим). ## Команды (основные) -- `make up` — поднять весь стек. -- `make airflow-init` — инициализировать мета-БД Airflow и создать пользователя. +- `make up` — поднять весь стек (Airflow инициализируется автоматически при первом старте). +- `make airflow-init` — вручную переинициализировать мета-БД Airflow и создать пользователя (обычно не нужно). - `make logs` — логи webserver и scheduler. - `make ddl-gp` — применить DDL к Greenplum. - `make gp-psql` — открыть `psql` в контейнере Greenplum от `gpadmin`. - `make down` — остановить и удалить тома (данные будут потеряны). -Пример: `make up && make airflow-init`, затем открыть `http://localhost:8080`. +Пример: `make up`, затем открыть `http://localhost:8080`. ## Локальное Python‑окружение - Используем `uv`: достаточно `uv sync` (или `make dev-sync`) — подтянет Python, создаст `.venv`, установит зависимости. @@ -70,4 +70,4 @@ - Пишите простыми словами. Добавляйте короткие комментарии к нетривиальной логике. - Избегайте больших рефакторингов и сложных паттернов — студенты только начинают. - Ошибки и логи — дружелюбные и понятные (лучше с подсказкой «что сделать дальше»). -- Перед релевантными правками валидируйте локально: `make up && make airflow-init`, затем откройте DAG в UI и/или прогоните `make test`. +- Перед релевантными правками валидируйте локально: `make up`, затем откройте DAG в UI и/или прогоните `make test`. diff --git a/README.md b/README.md index 64e3906..74287ac 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ - Установите Docker Desktop и Git. - Скопируйте настройки: `cp .env.example .env`. -- Поднимите стенд: `docker compose up -d` и инициализируйте Airflow: `docker compose run --rm airflow-init`. +- Поднимите стенд: `make up` (или `docker compose up -d` — сервис `airflow-init` запустится автоматически при первом старте). - Откройте UI: http://localhost:8080 (admin/admin). - Включите и запустите DAG `csv_to_greenplum`. Дождитесь Success. - Проверьте данные: `make gp-psql` → `SELECT COUNT(*) FROM public.orders;`. @@ -107,7 +107,7 @@ make up С `make` команды становятся короче: ```bash -make up && make airflow-init # Запуск стека +make up # Запуск стека (включая airflow-init при первом старте) make logs # Просмотр логов make gp-psql # Подключение к Greenplum ``` @@ -181,9 +181,9 @@ uv run black --check airflow tests ### Полезные команды ```bash # Основные команды -make up # Запустить весь стенд +make up # Запустить весь стенд (Airflow инициализируется автоматически при первом старте) make down # Остановить и удалить данные -make airflow-init # Инициализировать Airflow +make airflow-init # Ручной запуск инициализации Airflow (обычно не нужен) make ddl-gp # Применить DDL к Greenplum вручную make gp-psql # Подключиться к Greenplum через psql make bookings-init # Установить демобазу bookings в Postgres (по умолчанию генерирует 1 день) @@ -361,7 +361,7 @@ load_bookings_to_stg = PostgresOperator( | Не открывается порт 8080/5433/5434/5435 | Проверьте, что эти порты не заняты локальными сервисами; при необходимости остановите их или измените порты в `.env`/`docker-compose.yml` | | Нет файла в `./data` после запуска DAG | Проверьте логи задачи `generate_csv`, убедитесь, что `CSV_DIR` смонтирован в docker-compose | | Команда `make` не найдена | Используйте полные команды `docker compose` или установите make | -| Greenplum не стартует/падает при старте | Выполните `make down`, затем `make up && make airflow-init` (очищает тома и поднимает заново) | +| Greenplum не стартует/падает при старте | Выполните `make down`, затем `make up` (очищает тома и поднимает заново, включая авто‑инициализацию Airflow) | | DAG `bookings_to_gp_stage` падает на внешней таблице/подключении к bookings | Убедитесь, что запущен контейнер `bookings-db` (`docker compose ps`, при необходимости `docker compose start bookings-db`), и выполнены `make bookings-init` и `make ddl-gp` или DAG `bookings_stg_ddl` | | DAG `bookings_to_gp_stage` ругается на отсутствующие таблицы stg | Запустите DAG `bookings_stg_ddl` (или выполните `make ddl-gp`), затем повторите запуск | | DAG не видит Greenplum/DEMObase по Airflow Connections | Проверьте, что в Airflow созданы подключения `greenplum_conn` и `bookings_db` с параметрами из раздела «Настройка подключения к Greenplum в Airflow» и блока про bookings | diff --git a/TESTING.md b/TESTING.md index a8ec617..1de3db4 100644 --- a/TESTING.md +++ b/TESTING.md @@ -20,8 +20,7 @@ - `cp .env.example .env` (если файла ещё нет) и проверьте переменные: - `GP_PORT` — внутренний порт Greenplum в Docker-сети (по умолчанию 5432, менять не нужно); внешний порт для подключения с хоста фиксирован на `5435`, поэтому локальный PostgreSQL на 5432 не помешает. - `GP_USE_AIRFLOW_CONN=true` при желании использовать Airflow Connection; `false` — fallback на ENV. -- `make up` — поднимаем все сервисы. Важно дождаться статуса `healthy` у `pgmeta` и `greenplum` (`docker compose ps`). -- `make airflow-init` — миграции мета-БД и создание пользователя Airflow; занимает ~1–2 минуты. +- `make up` — поднимаем все сервисы. Важно дождаться статуса `healthy` у `pgmeta` и `greenplum` (`docker compose ps`); инициализация Airflow (`airflow-init`) произойдёт автоматически при первом старте. - `make logs` — следим, пока webserver и scheduler не перейдут в рабочее состояние (`Listening at: http://0.0.0.0:8080`). ## 4. Smoke тесты DAG в Airflow UI @@ -49,14 +48,14 @@ ## 6. Негативные сценарии и fallback - **Пустая таблица**: запустить `csv_to_greenplum_dq` до `csv_to_greenplum`. Ожидается ошибка на таске `check_orders_has_rows`. - **Проблемы с подключением**: временно изменить `GP_HOST` или `GP_PORT` на несуществующий, перезапустить `make up`, убедиться, что DAG падает с понятной ошибкой (`psycopg2.OperationalError`). -- **Fallback без Airflow Connection**: установить `GP_USE_AIRFLOW_CONN=false`, перезапустить стек (`make down && make up && make airflow-init`), удостовериться, что загрузка и DQ работают через ENV. +- **Fallback без Airflow Connection**: установить `GP_USE_AIRFLOW_CONN=false`, перезапустить стек (`make down && make up`), удостовериться, что загрузка и DQ работают через ENV. - **Дубликаты**: дважды вызвать `csv_to_greenplum` — ожидаем, что количество строк в `public.orders` не увеличится на размер CSV, а DAG `csv_to_greenplum_dq` не найдёт дублей. - **PXF и демобаза bookings** (после настройки PXF и выполнения `make ddl-gp`): временно остановить `bookings-db` (`docker compose stop bookings-db`) и попробовать выполнить `SELECT COUNT(*) FROM public.ext_bookings_bookings;` в `make gp-psql` — ожидается ошибка подключения. Затем запустить `bookings-db` (`docker compose start bookings-db`) и убедиться, что запрос снова работает. ## 7. Быстрый reset (если «что-то сломалось») - Перезапустить стенд с очисткой данных: - `make down` — остановит контейнеры и удалит тома. - - `make up && make airflow-init` — заново поднимет всё и проинициализирует Airflow. + - `make up` — заново поднимет всё и проинициализирует Airflow (через сервис airflow-init). - Иногда Greenplum не стартует после «грязных» остановок (из‑за старых внутренних файлов). Лечение: всегда делайте `make down` перед повторным `make up`. ## 8. Снятие метрик и мониторинг diff --git a/docker-compose.yml b/docker-compose.yml index b7dff34..7b23dcb 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -76,6 +76,8 @@ services: AIRFLOW__CORE__LOAD_EXAMPLES: "False" AIRFLOW__DATABASE__SQL_ALCHEMY_CONN: postgresql+psycopg2://${PG_USER}:${PG_PASSWORD}@pgmeta:5432/${PG_DB} AIRFLOW__WEBSERVER__SECRET_KEY: ${AIRFLOW__WEBSERVER__SECRET_KEY} + AIRFLOW_CONN_GREENPLUM_CONN: postgresql+psycopg2://${GP_USER}:${GP_PASSWORD}@greenplum:${GP_PORT:-5432}/${GP_DB} + AIRFLOW_CONN_BOOKINGS_DB: postgresql+psycopg2://${BOOKINGS_DB_USER}:${BOOKINGS_DB_PASSWORD}@bookings-db:5432/demo command: > bash -lc "pip install --no-cache-dir -r /opt/airflow/requirements.txt && airflow webserver" @@ -101,6 +103,8 @@ services: AIRFLOW__CORE__LOAD_EXAMPLES: "False" AIRFLOW__DATABASE__SQL_ALCHEMY_CONN: postgresql+psycopg2://${PG_USER}:${PG_PASSWORD}@pgmeta:5432/${PG_DB} AIRFLOW__WEBSERVER__SECRET_KEY: ${AIRFLOW__WEBSERVER__SECRET_KEY} + AIRFLOW_CONN_GREENPLUM_CONN: postgresql+psycopg2://${GP_USER}:${GP_PASSWORD}@greenplum:${GP_PORT:-5432}/${GP_DB} + AIRFLOW_CONN_BOOKINGS_DB: postgresql+psycopg2://${BOOKINGS_DB_USER}:${BOOKINGS_DB_PASSWORD}@bookings-db:5432/demo command: > bash -lc "pip install --no-cache-dir -r /opt/airflow/requirements.txt && airflow scheduler" @@ -124,6 +128,8 @@ services: AIRFLOW__CORE__LOAD_EXAMPLES: "False" AIRFLOW__DATABASE__SQL_ALCHEMY_CONN: postgresql+psycopg2://${PG_USER}:${PG_PASSWORD}@pgmeta:5432/${PG_DB} AIRFLOW__WEBSERVER__SECRET_KEY: ${AIRFLOW__WEBSERVER__SECRET_KEY} + AIRFLOW_CONN_GREENPLUM_CONN: postgresql+psycopg2://${GP_USER}:${GP_PASSWORD}@greenplum:${GP_PORT:-5432}/${GP_DB} + AIRFLOW_CONN_BOOKINGS_DB: postgresql+psycopg2://${BOOKINGS_DB_USER}:${BOOKINGS_DB_PASSWORD}@bookings-db:5432/demo volumes: - ./airflow/dags:/opt/airflow/dags - ./airflow/requirements.txt:/opt/airflow/requirements.txt diff --git a/docs/internal/bookings_stg_readme.md b/docs/internal/bookings_stg_readme.md index 76e9318..55e76de 100644 --- a/docs/internal/bookings_stg_readme.md +++ b/docs/internal/bookings_stg_readme.md @@ -50,8 +50,7 @@ _Внутренний файл, чтобы не забыть договорён ## 4. Как этим пользоваться студенту (черновой сценарий) 1. Поднять стенд и подготовить источники: - - `make up` - - `make airflow-init` + - `make up` (Airflow инициализируется автоматически при первом старте) - `make bookings-init` - `make ddl-gp` 2. Открыть Airflow UI (`http://localhost:8080`) и включить DAG `bookings_to_gp_stage`. diff --git a/docs/internal/pxf_bookings.md b/docs/internal/pxf_bookings.md index badc250..5199e39 100644 --- a/docs/internal/pxf_bookings.md +++ b/docs/internal/pxf_bookings.md @@ -159,8 +159,6 @@ FORMAT 'CUSTOM' (formatter='pxfwritable_import'); 1. Поднять стенд: - `make up` - дождаться healthcheck‑ов `pgmeta` и `greenplum`. -2. Инициализировать Airflow (если ещё не делали): - - `make airflow-init`. 3. Подготовить демо‑БД bookings: - `make bookings-init`. 4. Применить DDL в Greenplum (создать таблицы, включая внешнюю `public.ext_bookings_bookings`): @@ -220,7 +218,7 @@ FORMAT 'CUSTOM' (formatter='pxfwritable_import'); - При следующем `make up` Greenplum и PXF будут инициализироваться с нуля, но: - JAR и `jdbc-site.xml` возьмутся из репозитория и снова смонтируются в `/data/pxf/...`; - `make ddl-gp` снова создаст внешнюю таблицу `public.ext_bookings_bookings`. - - То есть после полного ресета студенту достаточно повторить цепочку `make up` → `make airflow-init` → `make bookings-init` → `make ddl-gp`. + - То есть после полного ресета студенту достаточно повторить цепочку `make up` → `make bookings-init` → `make ddl-gp`. - **Где искать логи при проблемах с PXF**: - Логи PXF: в контейнере `greenplum` под пользователем `gpadmin` в каталоге `${PXF_BASE}/logs` (по умолчанию `/data/pxf/logs`). - Логи Greenplum: в `${GREENPLUM_DATA_DIRECTORY}/master/.../pg_log` (например, `/data/master/gpseg-1/pg_log` для GP6). diff --git a/educational-tasks.md b/educational-tasks.md index be2792c..0ce7e3d 100644 --- a/educational-tasks.md +++ b/educational-tasks.md @@ -20,7 +20,7 @@ - где физически лежат CSV‑файлы; - какие параметры управляют размером датасета. 3. Поднимите стенд и запустите DAG: - - `make up && make airflow-init` + - `make up` (Airflow инициализируется автоматически при первом старте) - включите и запустите DAG `csv_to_greenplum` в Airflow UI. 4. Проверьте результат в Greenplum: - `make gp-psql`