- `cp .env.example .env` (если файла ещё нет) и проверьте переменные:
- `cp .env.example .env` (если файла ещё нет) и проверьте переменные:
- `GP_PORT` — внутренний порт Greenplum в Docker-сети (по умолчанию 5432, менять не нужно); внешний порт для подключения с хоста фиксирован на `5435`, поэтому локальный PostgreSQL на 5432 не помешает.
- `GP_PORT` — внутренний порт Greenplum в Docker-сети (по умолчанию 5432, менять не нужно); внешний порт для подключения с хоста фиксирован на `5435`, поэтому локальный PostgreSQL на 5432 не помешает.
- `GP_USE_AIRFLOW_CONN=true` при желании использовать Airflow Connection; `false` — fallback на ENV.
- `GP_USE_AIRFLOW_CONN=true` при желании использовать Airflow Connection; `false` — fallback на ENV.
- `make up` — поднимаем все сервисы. Важно дождаться статуса `healthy`у`pgmeta` и `greenplum` (`docker compose ps`); инициализация Airflow (`airflow-init`) произойдёт автоматически при первом старте.
- `make up` — поднимаем все сервисы. Важно дождаться статуса `healthy`у`pgmeta` и `greenplum` (`docker compose ps`); `greenplum` считается `healthy` только когда поднят и Greenplum, и PXF.
- `make logs` — следим, пока webserver и scheduler не перейдут в рабочее состояние (`Listening at: http://0.0.0.0:8080`).
- `make logs` — следим, пока webserver и scheduler не перейдут в рабочее состояние (`Listening at: http://0.0.0.0:8080`).
## 4. Smoke тесты DAG в Airflow UI
## 4. Smoke тесты DAG в Airflow UI
@@ -48,6 +48,8 @@
## 5. Проверка данных в Greenplum
## 5. Проверка данных в Greenplum
- `make gp-psql` — запустить psql в контейнере от имени `gpadmin`.
- `make gp-psql` — запустить psql в контейнере от имени `gpadmin`.
- (опционально) Проверить, что PXF действительно запущен:
# Временное ТЗ по PXF для чтения данных из bookings (черновик)
# PXF для bookings в учебном стенде (актуально)
_Этот файл внутренний, удалить перед итоговой сдачей._
Этот документ описывает **текущую реализацию** PXF в проекте: чтение данных из демо‑БД
`bookings` (Postgres, сервис `bookings-db`) в Greenplum через JDBC.
## 1. Цель и границы
## 1. Что должно работать
- Минимальная цель: настроить PXF в контейнере Greenplum так, чтобы из базы `bookings` (Postgres в сервисе `bookings-db`) можно было делать `SELECT` по одной внешней таблице в Greenplum.
- В Greenplum доступны внешние таблицы:
- На этом этапе **не** делаем загрузку в постоянные таблицы Greenplum, только чтение и ручные smoke‑проверки.
- Изменения в коде/конфигурации пока планируем «на бумаге»; реализацию и правки `docker-compose.yml`/SQL/DAG делаем отдельным шагом.
- `stg.bookings_ext` (создаётся DAG `bookings_stg_ddl`).
- PXF должен быть готов **после каждого старта** контейнера `greenplum`.
## 2. Архитектура на уровне контейнеров
## 2. Почему мы делаем свой образ Greenplum
- `bookings-db` — Postgres 16, демо‑БД `demo` из репозитория `demodb` (источник). Доступен внутри сети Docker по имени `bookings-db` и порту `5432`.
Изначально PXF‑скрипты/конфиги монтировались в контейнер как bind‑mount `:ro`.
- `greenplum` — контейнер `woblerr/greenplum:6.27.1` (GPDB 6, Ubuntu 22.04). В нём уже есть:
Базовый entrypoint образа Greenplum пытается делать `chown` файлов в
- Greenplum в режиме singlenode;
`/docker-entrypoint-initdb.d/`, из‑за чего контейнер иногда падал с ошибкой:
- установленный PXF (`/usr/local/pxf`, `pxf version release-6.10.1`);
- стартовый скрипт `/start_gpdb.sh`, который умеет включать PXF по флагу `GREENPLUM_PXF_ENABLE=true`.
- Внешний мир (IDE/pytest) подключается к Greenplum по порту `5435` на хосте (см. `docker-compose.yml`), а к `bookings-db` — по порту `${BOOKINGS_DB_PORT}` (см. `.env`).
- создание расширения `pxf` в базе `${GREENPLUM_DATABASE_NAME}` (у нас это `${GP_DB}`, по умолчанию `gp_dwh`);
- запуск `pxf cluster start` и привязку остановки/старта PXF к жизненному циклу Greenplum.
- База конфигов PXF (`PXF_BASE`) будет располагаться в `${GREENPLUM_DATA_DIRECTORY}/pxf`, в нашем compose — это `/data/pxf` на томе `greenplum_data`.
- Важно: `make down` сейчас делает `docker compose down -v`, поэтому при полном сбросе томов будут теряться и данные GP, и конфиги PXF (включая JDBC‑драйвер и `servers/*`).
## 4. JDBC‑драйвер для Postgres: где и как хранить
- Минусы: дополнительный шаг для студентов, зависимость от сети, нужно повторять после полного сброса томов.
Для учебного стенда окончательно выбираем вариант **(1) — JAR в репозитории**:
**На persistent volume (переживает рестарты):**
- В репозитории заводим каталог, например `pxf/` или `pxf/jdbc/`, и кладём туда файл `postgresql-42.7.3.jar` (фиксируем версию 42.7.3 как актуальную на момент разработки).
- `PXF_BASE` по умолчанию: `${GREENPLUM_DATA_DIRECTORY}/pxf` → в нашем compose это
- В`docker-compose.yml`(на этапе реализации) смонтируем этот JAR внутрь контейнера `greenplum` в каталог `$PXF_BASE/lib`, например:
- PXF по документации поддерживает размещение JDBC‑драйвера в `$PXF_BASE/lib` (общий для всех серверов) или в `$PXF_BASE/servers/<server>/lib` (локальный для сервера). Для простоты используем общий каталог `$PXF_BASE/lib`.
- Для студентов не будет лишних подготовительных шагов: после `make up` и инициализации конфигов PXF драйвер уже на месте.
Договорённость для реализации:
Важно: так как `PXF_BASE` лежит на томе, обновления seed‑файлов из нового образа
**не перезатирают** файлы в `PXF_BASE` автоматически (это сделано намеренно, чтобы
не ломать ручные правки студентов).
- Путь в репозитории: условно `pxf/postgresql-42.7.3.jar`.
## 4. Что происходит при старте контейнера `greenplum`
- Путь внутри контейнера: `/data/pxf/lib/postgresql-jdbc.jar` (через bind‑mount, read‑only).
- Обновление драйвера в будущем — ручная операция (заменить JAR в `pxf/` и скорректировать путь в `docker-compose.yml` при необходимости).
## 5. Сервер PXF для bookings-db (jdbc-site.xml)
1) Docker запускает контейнер с базовым entrypoint образа и командой
`/start_greenplum_with_pxf.sh` (она задана в `Dockerfile.greenplum` как `CMD`).
PXF использует концепцию «серверов» (`servers/<имя>`), где для каждого сервера хранится свой конфиг подключения (в т.ч. JDBC).
2) `/start_greenplum_with_pxf.sh` выполняет подготовку PXF:
- Внутри прописываем параметры подключения к демо‑БД `demo` в Postgres `bookings-db`.
Черновой шаблон `jdbc-site.xml` (значения логина/пароля берём из `.env.example`, блок `BOOKINGS_DB_*` — для учебного стенда допускаем хардкод тех же дефолтных значений):
4) Healthcheck сервиса `greenplum` ждёт и готовность Greenplum, и то, что PXF уже
запущен (`pxf cluster status`). Это нужно, чтобы Airflow не стартовал раньше PXF.
```xml
## 5. Управляющие переменные окружения
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<property>
Все переменные можно задать в `.env` (см. `.env.example`):
<name>jdbc.driver</name>
<value>org.postgresql.Driver</value>
</property>
<property>
- `PXF_SEED_OVERWRITE=1` — принудительно перезаписать seed‑файлы из образа в `PXF_BASE`
- `PXF_SYNC_ON_START=1` — выполнять `pxf cluster sync` при старте контейнера
</property>
(делает старт чуть дольше, но гарантирует актуальные конфиги на хостах кластера).
<property>
## 6. Быстрая ручная проверка
<name>jdbc.user</name>
<value>${BOOKINGS_DB_USER}</value>
</property>
<property>
1) Дождаться `healthy`у`greenplum`:
<name>jdbc.password</name>
<value>${BOOKINGS_DB_PASSWORD}</value>
</property>
</configuration>
`docker compose ps`
```
Замечания:
2) Проверить статус PXF (PXF CLI запускается только под пользователем `gpadmin`):
- В реальном файле `pxf/servers/bookings-db/jdbc-site.xml` логин и пароль будут прописаны строками, совпадающими с дефолтами из `.env.example` (`BOOKINGS_DB_USER=bookings`, `BOOKINGS_DB_PASSWORD=bookings`). Это упрощает старт стенда для студентов.
- Если студент поменяет креды `BOOKINGS_DB_USER`/`BOOKINGS_DB_PASSWORD` в своём `.env`, он должен **также** поменять их в `pxf/servers/bookings-db/jdbc-site.xml`, иначе PXF не сможет подключиться к источнику.
- Адрес `bookings-db:5432` — имя сервиса и внутренний порт Postgres внутри сети `docker compose`. Внешний порт (`${BOOKINGS_DB_PORT:-5434}`) здесь не используется.
- При стандартном сценарии (конфиг монтируется read‑only) PXF подхватывает `jdbc-site.xml` при первой инициализации/старте. Если конфиг внутри контейнера всё‑таки меняли вручную, для надёжности можно выполнить:
```bash
pxf cluster sync
pxf cluster restart
```
чтобы PXF подхватил новые настройки.
## 6. Внешняя таблица в Greenplum (только для чтения)
3) После применения DDL (`make ddl-gp`) проверить чтение через PXF:
Задача: завести одну external‑таблицу в Greenplum, которая читает данные из демо‑БД `demo` через PXF/JDBC.
- `make gp-psql`
Дизайн:
- Имя таблицы в Greenplum: `public.ext_bookings_bookings` (подчёркиваем, что это внешнее представление таблицы `bookings.bookings` из Postgres).
- Схема колонок должна совпадать со схемой исходной таблицы в `demo` (её нужно будет аккуратно выписать отдельным шагом, через `\d bookings.bookings` в `bookings-db`).
- Локация PXF:
- `PROFILE=JDBC` — используем JDBC‑профиль.
- `SERVER=bookings-db` — имя сервера из `jdbc-site.xml`.
Черновой шаблон DDL (без конкретных типов, заполним позже по реальной схеме; предполагается, что финальный DDL ляжет в `sql/ddl_gp.sql`, чтобы применяться через `make ddl-gp`):
- в `bookings-db` посмотреть структуру основного факт‑табличного объекта (скорее всего `bookings.bookings`) и перенести DDL;
- проверить типы дат/чисел, чтобы избежать сюрпризов на стороне GP.
- Для MVP достаточно одной таблицы; позже можно добавить ещё 1–2 внешние таблицы для примеров (например, справочники).
## 7. План тестирования (без дополнительных make‑таргетов)
Цель тестов: показать студентам, что PXF настроен корректно и позволяет читать данные; при этом не плодить отдельные `make`‑цели, а использовать уже существующие (`make up`, `make bookings-init`, `make gp-psql`).
### 7.1. Позитивный сценарий (smoke)
Предварительные условия:
- `.env` скопирован из `.env.example` и не изменял дефолтные креды для `bookings-db` (`BOOKINGS_DB_USER=bookings`, `BOOKINGS_DB_PASSWORD=bookings`).
- В`docker-compose.yml` включён PXF (`GREENPLUM_PXF_ENABLE=true` в сервисе `greenplum`).
- Для `bookings-db` уже выполнен `make bookings-init` (есть данные в `demo`).
- JAR драйвера (`pxf/postgresql-42.7.3.jar`) и файл `jdbc-site.xml` (`pxf/servers/bookings-db/jdbc-site.xml`) присутствуют в репозитории (они будут автоматически смонтированы в `/data/pxf/lib` и `/data/pxf/servers/bookings-db`).
- DDL внешней таблицы `public.ext_bookings_bookings` добавлен в `sql/ddl_gp.sql` и применяется через `make ddl-gp`.
Шаги (в будущем попадут в `TESTING.md`):
1. Поднять стенд:
- `make up`
- дождаться healthcheck‑ов `pgmeta` и `greenplum`.
3. Подготовить демо‑БД bookings:
- `make bookings-init`.
4. Применить DDL в Greenplum (создать таблицы, включая внешнюю `public.ext_bookings_bookings`):
- `make ddl-gp`.
5. Зайти в Greenplum:
- `make gp-psql`.
6. Проверить, что расширение PXF присутствует:
- `\dx pxf`.
7. Выполнить простые запросы:
- `SELECT COUNT(*) FROM public.ext_bookings_bookings;`
- `SELECT COUNT(*) FROM public.ext_bookings_bookings;`
- `SELECT * FROM public.ext_bookings_bookings LIMIT 5;`
Ожидаемый результат:
## 7. Типовые ошибки
- Запросы выполняются без ошибок, возвращают ненулевое количество строк.
- `protocol "pxf" does not exist`
- Структура данных визуально совпадает с данными в `bookings-db` (можно дополнительно открыть `bookings-psql` и сравнить).
- причина: не создано расширение `pxf` в базе Greenplum;
- решение: перезапустить `greenplum` (скрипт сделает `CREATE EXTENSION IF NOT EXISTS pxf`)
### 7.3. Идея для автоматического smoke‑теста (на будущее)
На будущее (не в рамках текущего этапа) можно добавить простой e2e‑тест в `tests/`, который:
- с помощью `psycopg2` коннектится к Greenplum (`GP_*` из `.env`);
- выполняет `SELECT 1 FROM public.ext_bookings_bookings LIMIT 1`;
- помечен как «integration» и запускается только по явному желанию (например, через отдельный маркер или переменную окружения).
Пока это остаётся идеей: сначала реализуем базовую конфигурацию PXF и ручной smoke‑чек‑лист.
## 8. Открытые вопросы / TODO
- Уточнить целевую таблицу(ы) в `demo` для внешнего представления (скорее всего `bookings.bookings`), аккуратно выписать DDL и обновить шаблон из раздела 6.
- При переносе DDL проверить типы дат/времени, чтобы не получить неожиданный сдвиг по часовому поясу (см. `docs/internal/bookings_tz.md`).
- При необходимости добавить интеграционный тест по мотивам раздела 7.3 (по отдельному маркеру/флагу).
## 9. Практические детали и нюансы
- **Таймзона**:
- Для единообразия логов и данных задаём `TZ=Europe/Moscow` (GMT+3) в `.env.example` и пробрасываем эту переменную в контейнеры `pgmeta`, `bookings-db`, `greenplum`, `airflow-webserver`, `airflow-scheduler`.
- При проверке данных через PXF имеет смысл сравнивать выборки по времени между `bookings-db` и Greenplum, опираясь на договорённости из `docs/internal/bookings_tz.md`.
- **Поведение при `make down`**:
- `make down` вызывает `docker compose down -v`, что удаляет все тома, включая `greenplum_data` (`/data` в контейнере).
- При следующем `make up` Greenplum и PXF будут инициализироваться с нуля, но:
- JAR и `jdbc-site.xml` возьмутся из репозитория и снова смонтируются в `/data/pxf/...`;
- `make ddl-gp` снова создаст внешнюю таблицу `public.ext_bookings_bookings`.
- То есть после полного ресета студенту достаточно повторить цепочку `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).
- При ошибках подключения к `bookings-db` полезно:
- проверить, что контейнер `bookings-db` работает (`docker compose ps`);
- сверить креды в `.env` и `pxf/servers/bookings-db/jdbc-site.xml`;
log_warn "pxf cli не найден: ${PXF_CLI}, пропускаем pxf cluster sync"
exit0
fi
# PXF CLI не запускается под root, поэтому выполняем синхронизацию под gpadmin.
# PXF_BASE передаём явно, т.к. `su -` сбрасывает окружение.
if ! su - "${GP_USER}" -c "PXF_BASE='${PXF_BASE}' '${PXF_CLI}' cluster sync";then
log_warn "pxf cluster sync завершился с ошибкой"
log_warn "pxf cluster sync завершился с ошибкой"
fi
else
else
log_warn"pxf не найден в PATH, пропускаем pxf cluster sync"
log_info"pxf cluster sync выполнен"
fi
fi
fi
fi
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
