airflow-greenplum/AGENTS.md

Repository Guidelines (для агентa и контрибьюторов)

Эта репа — учебный стенд для студентов (менти), которые только начинают с Airflow/Greenplum и Python. Пожалуйста, держите решения простыми, стабильными и хорошо объяснёнными.

Структура проекта

• airflow/dags/ — DAG-файлы (например, csv_to_greenplum.py, csv_to_greenplum_dq.py).
• airflow/requirements.txt — зависимости, которые ставятся внутри контейнеров Airflow.
• sql/ — DDL и вспомогательные SQL (например, sql/ddl_gp.sql).
• docker-compose.yml — Greenplum, Airflow, Postgres (мета-БД).
• Makefile — удобные команды для локальной работы.
• .env(.example) — настройки окружения (реальные секреты не коммитим).

Команды (основные)

• make up — поднять весь стек (Airflow инициализируется автоматически при первом старте).
• make stop — остановить контейнеры, не трогая данные.
• make down — остановить и удалить контейнеры/сети (тома сохраняются).
• make clean — полный reset: остановить и удалить контейнеры/сети и тома (все данные будут потеряны).
• make airflow-init — вручную переинициализировать мета-БД Airflow и создать пользователя (обычно не нужно).
• make logs — логи webserver и scheduler.
• make ddl-gp — применить DDL к Greenplum.
• make gp-psql — открыть psql в контейнере Greenplum от gpadmin.

Пример: make up, затем открыть http://localhost:8080.

Локальное 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 <package> и проверить pip list --user.
• В IDE выбираем интерпретатор из .venv.

Стиль кода

• 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 и документацию — на русском; имена идентификаторов — на английском.

Структура и нейминг SQL (слои DWH)

• В каталоге sql/ придерживаемся слоёв DWH:
  • sql/src/ — скрипты, работающие с исходными системами (например, bookings_generate_day_if_missing.sql);
  • sql/stg/ — скрипты для стейджинга (bookings_ddl.sql, bookings_load.sql, bookings_dq.sql);
  • в будущем можно добавить sql/ods/, sql/dds/, sql/dm/ по мере роста стенда.
• Именование файлов: {объект}_{роль}.sql, где:
  • объект — логическое имя сущности (bookings, orders, и т.п.);
  • роль — ddl (создание/изменение объектов), load (загрузка/инкремент), dq (проверки качества данных) и т.п.
• Общие DDL-скрипты (например, sql/ddl_gp.sql) могут подключать файловые DDL через \i, но сами определения таблиц живут рядом с объектом (sql/stg/bookings_ddl.sql и т.п.).

Airflow + SQL

• В учебных DAG’ах, где основная логика — в SQL, по умолчанию используем PostgresOperator + Airflow Connections:
  • DAG оркестрирует шаги и подключение к БД;
  • SQL-скрипты лежат в sql/... и подключаются по пути (sql='sql/stg/bookings_load.sql').
• Сложную ручную работу с подключениями (psycopg2, ENV-фоллбеки) используем только там, где реально много Python-логики и это помогает учебной цели.

Тестирование

• Тесты лежат в tests/ (pytest). Запуск: make test.
• Есть юнит‑тесты для helpers/greenplum.py и smoke‑тесты DAG‑структуры (tests/test_dags_smoke.py).
• Smoke‑тесты DAG автоматически пропускаются, если Airflow не установлен в venv.
• Для ручного прогона стенда см. TESTING.md (пошаговый чек‑лист для студентов).

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, затем откройте DAG в UI и/или прогоните make test.