188 lines
12 KiB
Markdown
188 lines
12 KiB
Markdown
# airflow-dwh-gp-lab
|
||
|
||
> Этот стенд можно использовать самостоятельно, но он также является курсовой работой
|
||
> плана обучения [Data Engineering Roadmap](https://github.com/dementev-dev/de-roadmap).
|
||
> Нужна помощь? Обратитесь к автору материалов — ментору [@dementev_dev](https://t.me/dementev_dev).
|
||
|
||
Учебный стенд для лабораторных по Data Engineering: **Airflow** оркестрирует загрузку данных из демо‑БД
|
||
**bookings** (Postgres) в **Greenplum**.
|
||
|
||
## Зачем этот стенд
|
||
|
||
Основная цель стенда — дать вам удобное место для лабораторных работ и будущей курсовой:
|
||
вы построите небольшое аналитическое хранилище данных (DWH) на базе **Greenplum** и закрепите навыки:
|
||
|
||
- моделирования данных (слои DWH, модели, витрины);
|
||
- построения ETL/ELT;
|
||
- работы с Airflow и Greenplum.
|
||
|
||
В курсовой у нас один источник данных — демо‑БД **bookings**. В стенде уже есть готовые учебные примеры
|
||
загрузки **bookings → STG → ODS → DDS → DM** в Greenplum, чтобы вы могли сфокусироваться
|
||
на DWH‑части и не тратить время на инфраструктуру.
|
||
|
||
## Что внутри
|
||
|
||
- **Airflow** (UI: http://localhost:8080, по умолчанию; логин/пароль: admin/admin)
|
||
- **Greenplum** (single‑node для обучения; внешний порт по умолчанию `5435`)
|
||
- **bookings-db** (Postgres с демо‑БД `demo`; внешний порт по умолчанию `5434`)
|
||
- **PXF** как “транспорт” между Postgres и Greenplum (уже настроен в образе)
|
||
|
||
## Требования
|
||
|
||
Стенд запускается в Docker и поднимает несколько сервисов (Airflow + Greenplum + 2×Postgres),
|
||
поэтому важны ресурсы и настройки Docker.
|
||
|
||
| Ресурс | Минимум | Рекомендуем |
|
||
|---|---:|---:|
|
||
| CPU | 2 ядра | 4+ ядер |
|
||
| RAM | 8 GB | 16 GB |
|
||
| Диск | 25–30 GB свободного места | 40+ GB (SSD) |
|
||
|
||
Работает на **Linux**, а на **Windows** — при использовании **WSL2**.
|
||
|
||
Потребуется `make`, Docker (`docker`) и Docker Compose (`docker compose`) или Docker Desktop.
|
||
Для первого запуска нужен доступ в интернет (скачать образы и зависимости).
|
||
Порты `8080`, `5433`, `5434`, `5435` должны быть свободны (или измените их в `.env`).
|
||
Порты настраиваются в `.env`: `AIRFLOW_WEB_PORT`, `PGMETA_PORT`, `BOOKINGS_DB_PORT`, `GP_HOST_PORT`.
|
||
|
||
Про PXF и технические детали стенда: [docs/stack.md](docs/stack.md).
|
||
|
||
## Быстрый старт (основной сценарий: bookings → STG → ODS → DDS → DM)
|
||
|
||
1) Скопируйте настройки:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2) Поднимите стенд:
|
||
|
||
```bash
|
||
make up
|
||
# если make не установлен: docker compose up -d
|
||
```
|
||
|
||
3) Инициализируйте демо‑БД bookings:
|
||
|
||
```bash
|
||
make bookings-init # быстрое восстановление из seed-дампа (~18 сек), рекомендуется
|
||
# make bookings-generate # альтернатива: полная генерация с нуля (занимает часы)
|
||
```
|
||
|
||
4) Подготовьте объекты DWH в Greenplum (выберите один вариант):
|
||
|
||
- Учебный вариант: в Airflow UI запустите DAG'и по порядку — `bookings_stg_ddl`, `bookings_ods_ddl`, `bookings_dds_ddl`, `bookings_dm_ddl`;
|
||
- Технический шорткат: `make ddl-gp` (применяет DDL для STG, ODS, DDS и DM разом).
|
||
|
||
5) Запустите DAG'и загрузки данных по порядку:
|
||
|
||
- `bookings_to_gp_stage` — загрузка в STG
|
||
- `bookings_to_gp_ods` — загрузка в ODS
|
||
- `bookings_to_gp_dds` — загрузка в DDS
|
||
- `bookings_to_gp_dm` — загрузка в DM (витрины)
|
||
|
||
6) Проверьте результат в Greenplum:
|
||
|
||
```bash
|
||
make gp-psql
|
||
-- внутри psql:
|
||
SELECT COUNT(*) FROM stg.bookings;
|
||
SELECT COUNT(*) FROM ods.bookings;
|
||
SELECT COUNT(*) FROM dds.dim_airports;
|
||
SELECT COUNT(*) FROM dds.fact_flight_sales;
|
||
SELECT COUNT(*) FROM dm.sales_report;
|
||
-- Остальные DDS/DM-таблицы пока пусты — вы реализуете их в задании.
|
||
```
|
||
|
||
Порядок повторных запусков и переходов между слоями описан в
|
||
[руководстве по запуску DAG](docs/dag_execution_order.md).
|
||
|
||
7) Разберитесь в данных и приступайте к заданию:
|
||
|
||
Стенд работает, данные загружены. Откройте
|
||
[руководство о структуре DWH](docs/design/db_schema.md): на примере поездки
|
||
оно проведет от билетов и сегментов к факту и витрине. Рядом держите
|
||
[интерактивную карту](docs/design/architecture-map.html) — локальный файл
|
||
`docs/design/architecture-map.html` нужно открыть в браузере; в Gitea HTML
|
||
показывается как исходный текст. Затем переходите к
|
||
[учебным заданиям](docs/assignment/README.md): начните с приема справочника
|
||
через PXF, после него — загрузки ODS.
|
||
|
||
## DAG-и в стенде
|
||
|
||
Основные (для потока bookings → DWH):
|
||
|
||
- `bookings_stg_ddl` — создаёт/обновляет весь STG слой для bookings (9 таблиц: bookings, tickets, airports, airplanes,
|
||
routes, seats, flights, segments, boarding_passes; включая внешние `*_ext` через PXF);
|
||
- `bookings_to_gp_stage` — генерирует учебный день в `bookings-db`, затем загружает данные в STG и выполняет DQ‑проверки.
|
||
- `lab_pxf_airports` — готовит общий снимок четырех справочников для [лабораторной PXF](docs/assignment/pxf_airports.md); использует те же SQL и DQ, без генерации транзакций.
|
||
- `bookings_ods_ddl` — создаёт/обновляет ODS-таблицы по домену bookings.
|
||
- `bookings_to_gp_ods` — заменяет снимки справочников и обновляет транзакционные таблицы ODS из STG; выполняет DQ-проверки.
|
||
- `bookings_dds_ddl` — создаёт/обновляет DDS-таблицы (`dim_*`, `fact_flight_sales`) по домену bookings.
|
||
- `bookings_to_gp_dds` — загружает данные из ODS в DDS (SCD1/SCD2 + факт) и выполняет DQ‑проверки.
|
||
- `bookings_dm_ddl` — создаёт/обновляет DM-витрины (sales_report, route_performance, passenger_loyalty, airport_traffic, monthly_overview).
|
||
- `bookings_to_gp_dm` — загружает данные из DDS в DM (агрегированные витрины).
|
||
|
||
## Полезные команды
|
||
|
||
```bash
|
||
make up # поднять стек
|
||
make logs # логи airflow-webserver и airflow-scheduler
|
||
make gp-psql # psql в Greenplum
|
||
make bookings-psql # psql в демо-БД bookings (Postgres)
|
||
make ddl-gp # применить DDL STG+ODS+DDS+DM к Greenplum вручную (вместо DDL-DAG)
|
||
make down # остановить и удалить контейнеры/сети (volumes сохраняются)
|
||
make clean # полный reset: удалить контейнеры/сети и volumes (данные будут потеряны)
|
||
```
|
||
|
||
## Подключение через DBeaver (опционально)
|
||
|
||
Перед подключением убедитесь, что стенд поднят (`make up`).
|
||
|
||
### Greenplum
|
||
|
||
- `Host`: `localhost`
|
||
- `Port`: значение `GP_HOST_PORT` из `.env` (по умолчанию `5435`)
|
||
- `Database`: значение `GP_DB` из `.env` (по умолчанию `gp_dwh`)
|
||
- `Username`: значение `GP_USER` (по умолчанию `gpadmin`)
|
||
- `Password`: значение `GP_PASSWORD` (по умолчанию `gpadmin`)
|
||
|
||
### bookings-db (Postgres, демо-БД `demo`)
|
||
|
||
- `Host`: `localhost`
|
||
- `Port`: значение `BOOKINGS_DB_PORT` из `.env` (по умолчанию `5434`)
|
||
- `Database`: `demo`
|
||
- `Username`: значение `BOOKINGS_DB_USER` (по умолчанию `bookings`)
|
||
- `Password`: значение `BOOKINGS_DB_PASSWORD` (по умолчанию `bookings`)
|
||
|
||
## Документация
|
||
|
||
- [Структура DWH: от бронирования до витрины](docs/design/db_schema.md)
|
||
- [От карты к SQL загрузки](docs/design/reading_the_pipeline.md)
|
||
- [Учебные задания: порядок работы и проверка](docs/assignment/README.md)
|
||
- [Интерактивная карта таблиц и связей](docs/design/architecture-map.html)
|
||
- [Дополнительные заметки и технические детали](docs/README.md)
|
||
- [Детали по STG DAG](docs/bookings_to_gp_stage.md)
|
||
- [Детали по ODS DAG](docs/bookings_to_gp_ods.md)
|
||
- [Детали по DDS DAG](docs/bookings_to_gp_dds.md)
|
||
- [Детали по DM DAG](docs/bookings_to_gp_dm.md)
|
||
|
||
Для работы над репозиторием: [проверки разработки и стенда](TESTING.md).
|
||
|
||
## Типичные проблемы и решения
|
||
|
||
| Проблема | Решение |
|
||
|----------|---------|
|
||
| Airflow UI не открывается | Дождитесь сообщения `Listening at: http://0.0.0.0:8080` в логах (`make logs`) |
|
||
| `database "demo" does not exist` в bookings‑DAG | Вы сделали reset с удалением volumes (`make clean` / `docker compose down -v`). Запустите `make bookings-init` (быстрое восстановление из дампа, ~18 сек) и повторите DAG. |
|
||
| Ошибка `bookings.jobs должен быть >= 1` | Проверьте значение `BOOKINGS_JOBS` в `.env` — оно должно быть целым числом >= 1. По умолчанию `BOOKINGS_JOBS=1` (синхронная генерация). При `BOOKINGS_JOBS>1` генерация идёт параллельно через dblink. |
|
||
| Ошибка подключения к Greenplum | Убедитесь, что контейнер `greenplum` имеет статус `healthy` (`docker compose ps`) |
|
||
| `protocol "pxf" does not exist` | Перезапустите `greenplum` и повторите `bookings_stg_ddl`/`make ddl-gp` — расширение `pxf` создаётся автоматически при старте контейнера. |
|
||
| DAG `bookings_to_gp_stage` ругается на отсутствующие таблицы stg | Запустите `bookings_stg_ddl` (или выполните `make ddl-gp`), затем повторите запуск |
|
||
| Порты 8080/5433/5434/5435 заняты | Остановите локальные сервисы или измените порты в `.env` |
|
||
|
||
## Благодарности
|
||
|
||
- **Postgres Pro** — за демо‑БД bookings и генератор данных `demodb`: https://github.com/postgrespro/demodb (лицензия MIT: https://github.com/postgrespro/demodb/blob/main/LICENSE).
|
||
- **woblerr** — за Docker-сборку Greenplum: https://github.com/woblerr/docker-greenplum (образ: `woblerr/greenplum`, лицензия MIT: https://github.com/woblerr/docker-greenplum/blob/master/LICENSE).
|