From aaa44103fa13980032829b9b0fe5e3954aee2583 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Wed, 15 Oct 2025 12:30:51 +0300 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D1=80=D0=B0=D0=B1=D0=BE=D1=82?= =?UTF-8?q?=D0=BA=D0=B8=20=D0=B4=D0=BE=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD?= =?UTF-8?q?=D1=82=D0=B0=D1=86=D0=B8=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- airflow-greenplum/AGENTS.md | 92 +++++++++++++++++++----------------- airflow-greenplum/README.md | 32 +++++++++++++ airflow-greenplum/TESTING.md | 19 +++++--- 3 files changed, 94 insertions(+), 49 deletions(-) diff --git a/airflow-greenplum/AGENTS.md b/airflow-greenplum/AGENTS.md index 87eea40..bbfc4ce 100644 --- a/airflow-greenplum/AGENTS.md +++ b/airflow-greenplum/AGENTS.md @@ -1,51 +1,57 @@ -# Repository Guidelines +# Repository Guidelines (для агентa и контрибьюторов) -## Project Structure & Module Organization -- `airflow/dags/` — Airflow DAGs (e.g., `airflow/dags/kafka_to_greenplum.py`). -- `airflow/requirements.txt` — Python deps installed inside Airflow containers. -- `sql/` — database DDL and helpers (e.g., `sql/ddl_gp.sql`). -- `docker-compose.yml` — Greenplum, Kafka, Airflow, Postgres (metadata DB). -- `Makefile` — local DX commands; see targets below. -- `.env(.example)` — runtime configuration; never commit real secrets. +Эта репа — учебный стенд для студентов (менти), которые только начинают с Airflow/Greenplum и Python. Пожалуйста, держите решения простыми, стабильными и хорошо объяснёнными. -## Build, Test, and Development Commands -- `make up` — start the full stack. -- `make airflow-init` — migrate metadata DB and create admin user. -- `make logs` — follow webserver and scheduler logs. -- `make ddl-gp` — apply DDL to Greenplum. -- `make gp-psql` — open `psql` in the GP container. -- `make down` — stop stack and remove volumes. -Example: `make up && make airflow-init` then open `http://localhost:8080`. +## Структура проекта +- `airflow/dags/` — DAG-файлы (например, `csv_to_greenplum.py`, `data_quality_greenplum.py`). +- `airflow/requirements.txt` — зависимости, которые ставятся внутри контейнеров Airflow. +- `sql/` — DDL и вспомогательные SQL (например, `sql/ddl_gp.sql`). +- `docker-compose.yml` — Greenplum, Airflow, Postgres (мета-БД). +- `Makefile` — удобные команды для локальной работы. +- `.env(.example)` — настройки окружения (реальные секреты не коммитим). -## Локальное Python-окружение -- Окружением управляет `uv`: достаточно выполнить `uv sync` (или `make dev-sync`), чтобы подтянуть нужный Python, создать `.venv` и установить зависимости. -- `make dev-setup` пригодится, когда нужно перепинить версию Python или прогреть кэш (вызовет `uv python install` + `uv python pin` перед `uv sync`). -- Команды разработчика: `make test`, `make lint`, `make fmt` (под капотом выполняются через `uv run`). -- Не используем `pip install --user`; если пакеты попали в user-site, удаляем через `pip uninstall ` и проверяем `pip list --user`. -- В IDE выбираем интерпретатор из `.venv` (`.venv\Scripts\python.exe` на Windows, `.venv/bin/python` на Linux/macOS). +## Команды (основные) +- `make up` — поднять весь стек. +- `make airflow-init` — инициализировать мета-БД Airflow и создать пользователя. +- `make logs` — логи webserver и scheduler. +- `make ddl-gp` — применить DDL к Greenplum. +- `make gp-psql` — открыть `psql` в контейнере Greenplum от `gpadmin`. +- `make down` — остановить и удалить тома (данные будут потеряны). -## Coding Style & Naming Conventions -- Python: PEP 8, 4-space indents, `snake_case` for functions/vars, DAG IDs lower_snake_case. -- Imports: stdlib → third-party → local; prefer one module per line. -- SQL: uppercase keywords, `snake_case` identifiers, end statements with `;`. -- Filenames: DAGs as `_to_.py` (e.g., `kafka_to_greenplum.py`). -- Formatting: if available, use `black` (88 cols) and `isort`; otherwise keep existing style. -- Language: комментарии, docstrings и документацию (README, описания PR/Issues) пишем на русском; имена идентификаторов и код — на английском. +Пример: `make up && make airflow-init`, затем открыть `http://localhost:8080`. -## Testing Guidelines -- No test suite yet. If adding tests, use `pytest` under `tests/` with `test_*.py`. -- Prefer unit tests for Python callables used by tasks; mock env vars and external systems. -- Run locally with `pytest -q`. +## Локальное Python‑окружение +- Используем `uv`: достаточно `uv sync` (или `make dev-sync`) — подтянет Python, создаст `.venv`, установит зависимости. +- `make dev-setup` полезен при смене версии Python (выполнит `uv python install` + `uv python pin` перед `uv sync`). +- Проверки: `make test`, `make lint`, `make fmt` (выполняются через `uv run`). +- Не используем `pip install --user`; если что‑то попало в user‑site — удалить `pip uninstall ` и проверить `pip list --user`. +- В IDE выбираем интерпретатор из `.venv`. -## Commit & Pull Request Guidelines -- Use Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:` etc. Example: `feat(dags): load orders to Greenplum`. -- Keep PRs focused; include a description, run steps, and relevant screenshots (e.g., DAG graph or task logs). -- Link issues; update `README.md` and DDL when behavior or schema changes. +## Стиль кода +- Python: PEP 8, 4 пробела, `snake_case`; `dag_id` — `lower_snake_case`. +- Импорты: stdlib → third‑party → local, по одному модулю в строке. +- SQL: ключевые слова UPPERCASE, идентификаторы `snake_case`, завершаем `;`. +- Форматирование: `black` (88 cols) и `isort`. Если не уверены — запустите `make fmt`. +- Язык: комментарии, docstring и документацию — на русском; имена идентификаторов — на английском. -## Security & Configuration Tips -- Configure via `.env`; do not hardcode credentials. Common vars: `GP_USER`, `GP_PASSWORD`, `GP_DB`, `GP_PORT`, `PG_*`, `AIRFLOW_*`. -- Be cautious with `make down` (removes volumes). Pin images/deps; prefer digests for critical images. +## Тестирование +- Тесты лежат в `tests/` (pytest). Запуск: `make test`. +- Есть юнит‑тесты для `helpers/greenplum.py` и smoke‑тесты DAG‑структуры (`tests/test_dags_smoke.py`). +- Smoke‑тесты DAG автоматически пропускаются, если Airflow не установлен в venv. +- Для ручного прогона стенда см. `TESTING.md` (пошаговый чек‑лист для студентов). -## Agent-Specific Notes -- Keep changes minimal and localized; do not rename Make targets without updating docs. -- Validate by running `make up`, `make airflow-init`, and inspecting the DAG in Airflow. +## Pull Requests +- Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`. Пример: `feat(dags): load orders to Greenplum`. +- Держите изменения минимальными и локальными. Не переименовывайте Make‑таргеты без обновления документации. +- В описании PR добавляйте скрин DAG‑графа или логи задач, если менялась логика. +- При изменении схемы/поведения — обновляйте `README.md` и `sql/ddl_gp.sql`. + +## Безопасность и конфигурация +- Все настройки — через `.env`; креды в коде не хардкодим. Частые переменные: `GP_*`, `PG_*`, `AIRFLOW_*`, `CSV_*`. +- `make down` удаляет тома — предупреждайте студентов, что данные пропадут. + +## Для агента (особенности аудитории) +- Пишите простыми словами. Добавляйте короткие комментарии к нетривиальной логике. +- Избегайте больших рефакторингов и сложных паттернов — студенты только начинают. +- Ошибки и логи — дружелюбные и понятные (лучше с подсказкой «что сделать дальше»). +- Перед релевантными правками валидируйте локально: `make up && make airflow-init`, затем откройте DAG в UI и/или прогоните `make test`. diff --git a/airflow-greenplum/README.md b/airflow-greenplum/README.md index 5b2e791..428e29e 100644 --- a/airflow-greenplum/README.md +++ b/airflow-greenplum/README.md @@ -10,6 +10,19 @@ - Как загружать данные в Greenplum пакетами и избегать дублей - Как проверять качество данных в автоматизированных pipeline - Основы проектирования ETL/ELT процессов + +## 👩‍🎓 Для студентов (10‑минутный чек‑лист) + +- Установите Docker Desktop и Git. +- Скопируйте настройки: `cp .env.example .env`. +- Поднимите стенд: `docker compose up -d` и инициализируйте Airflow: `docker compose run --rm airflow-init`. +- Откройте UI: http://localhost:8080 (admin/admin). +- Включите и запустите DAG `csv_to_greenplum`. Дождитесь Success. +- Проверьте данные: `make gp-psql` → `SELECT COUNT(*) FROM public.orders;`. +- Дополнительно: запустите `greenplum_data_quality` — все проверки должны быть зелёные. + +Если что‑то не работает — смотрите «Типичные проблемы» и «Быстрый reset» ниже. + ## Локальное окружение разработчика Локальным окружением управляет [uv](https://docs.astral.sh/uv/) — он скачивает нужный Python и создаёт `.venv` на основе `pyproject.toml` / `uv.lock`. @@ -93,6 +106,17 @@ SELECT * FROM public.orders LIMIT 5; CSV-файлы после выполнения DAG остаются в директории `./data`. Их можно открыть любым редактором или изучить через pandas. +### Быстрый reset + +Если после изменений что‑то «сломалось»: + +```bash +make down # Остановить и стереть данные в контейнерах +make up && make airflow-init +``` + +Это помогает, когда Greenplum не стартует из‑за «грязной» остановки и внутренних файлов. + --- ## 🛠️ Подробная настройка (для уверенных пользователей) @@ -213,6 +237,7 @@ make logs # Следить за логами Airflow | Ошибка подключения к Greenplum | Убедитесь, что контейнер `greenplum` стал статусом `healthy` (проверьте `docker compose ps`) | | Нет файла в `./data` после запуска DAG | Проверьте логи задачи `generate_csv`, убедитесь, что `CSV_DIR` смонтирован в docker-compose | | Команда `make` не найдена | Используйте полные команды `docker compose` или установите make | +| Greenplum не стартует/падает при старте | Выполните `make down`, затем `make up && make airflow-init` (очищает тома и поднимает заново) | --- @@ -239,5 +264,12 @@ make logs # Следить за логами Airflow 3. **Попробуйте другие источники** — замените генератор данных на чтение из файла или API 4. **Изучите Airflow deeper** — добавьте зависимости между задачами, настройте расписания +--- + +## ✅ Тестирование + +- Локальные проверки: `make test` (pytest). Для форматирования — `make fmt`, для проверки — `make lint`. +- Пошаговый сценарий с Docker (включая негативные кейсы и reset) — см. `TESTING.md`. + Удачи в изучении Data Engineering! 🚀 diff --git a/airflow-greenplum/TESTING.md b/airflow-greenplum/TESTING.md index 920f7ec..c07262b 100644 --- a/airflow-greenplum/TESTING.md +++ b/airflow-greenplum/TESTING.md @@ -1,6 +1,8 @@ -# План тестирования +# План тестирования (для студентов) -Документ описывает, как проверить актуальное состояние проекта Airflow ↔ Greenplum после серии изменений. Все шаги проверены локально на Windows в PowerShell; команды приведены в ожидаемом порядке. +Этот документ — пошаговый чек‑лист, как проверить, что всё работает: от «быстрых локальных проверок» до запуска стенда в Docker и просмотра данных в Greenplum. Подходит начинающим: просто выполняйте шаги по порядку. + +Если что‑то пошло не так, смотрите раздел «Быстрый reset» ниже. ## 1. Быстрая проверка окружения - `uv sync` — подтягиваем Python и зависимости из `pyproject.toml`/`uv.lock`. @@ -48,17 +50,22 @@ - **Fallback без Airflow Connection**: установить `GP_USE_AIRFLOW_CONN=false`, перезапустить стек (`make down && make up && make airflow-init`), удостовериться, что загрузка и DQ работают через ENV. - **Дубликаты**: дважды вызвать `csv_to_greenplum` — ожидаем, что количество строк в `public.orders` не увеличится на размер CSV, а DAG `greenplum_data_quality` не найдёт дублей. -## 7. Снятие метрик и мониторинг +## 7. Быстрый reset (если «что-то сломалось») +- Перезапустить стенд с очисткой данных: + - `make down` — остановит контейнеры и удалит тома. + - `make up && make airflow-init` — заново поднимет всё и проинициализирует Airflow. +- Иногда Greenplum не стартует после «грязных» остановок (из‑за старых внутренних файлов). Лечение: всегда делайте `make down` перед повторным `make up`. + +## 8. Снятие метрик и мониторинг - Контейнеры: `docker compose ps`, `docker stats` (по желанию). - Логи задач: в Airflow UI → конкретный таск → Log. - Хостовые CSV: каталог `data/` (можно открыть любой файл и убедиться в структуре). -## 8. Завершение работы +## 9. Завершение работы - `make down` — выключает сервисы и удаляет тома (перезапишет данные в Greenplum!). - При необходимости сохранить данные: скопировать CSV из `data/` и дампы из контейнера до `make down`. -## Текущий статус (обновлено агентом) +## Текущий статус (пример успешного прогона) - `uv run pytest -q` — 11 passed, 2 smoke-теста DAG пропущены (Airflow не установлен в venv). - `make lint` — падает, потому что `airflow/dags/*.py` не отформатированы black/isort. После `make fmt` проблема уйдёт. - Docker-стенд не запускался в рамках этой сессии; ожидается, что инструкции выше обеспечат полноценную проверку. -