From 86435c282d903ae1b42c6678e68ec76b76c713fc Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Tue, 9 Dec 2025 09:35:31 +0300 Subject: [PATCH] =?UTF-8?q?=D0=A3=D1=82=D0=BE=D1=87=D0=BD=D0=B5=D0=BD?= =?UTF-8?q?=D0=B8=D1=8F=20=D0=BF=D0=BB=D0=B0=D0=BD=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/internal/pxf_bookings.md | 65 ++++++++++++++++++++++++++--------- 1 file changed, 48 insertions(+), 17 deletions(-) diff --git a/docs/internal/pxf_bookings.md b/docs/internal/pxf_bookings.md index 05d40c7..c5ebb0a 100644 --- a/docs/internal/pxf_bookings.md +++ b/docs/internal/pxf_bookings.md @@ -45,13 +45,17 @@ _Этот файл внутренний, удалить перед итогов Для учебного стенда окончательно выбираем вариант **(1) — JAR в репозитории**: -- В репозитории заводим каталог, например `pxf/` или `pxf/jdbc/`, и кладём туда файл `postgresql-42.7.3.jar` (конкретная версия будет зафиксирована отдельно). +- В репозитории заводим каталог, например `pxf/` или `pxf/jdbc/`, и кладём туда файл `postgresql-42.7.3.jar` (фиксируем версию 42.7.3 как актуальную на момент разработки). - В `docker-compose.yml` (на этапе реализации) смонтируем этот JAR внутрь контейнера `greenplum` в каталог `$PXF_BASE/lib`, например: - `./pxf/postgresql-42.7.3.jar:/data/pxf/lib/postgresql-jdbc.jar:ro`. - PXF по документации поддерживает размещение JDBC‑драйвера в `$PXF_BASE/lib` (общий для всех серверов) или в `$PXF_BASE/servers//lib` (локальный для сервера). Для простоты используем общий каталог `$PXF_BASE/lib`. - Для студентов не будет лишних подготовительных шагов: после `make up` и инициализации конфигов PXF драйвер уже на месте. -Открытый момент: конкретный путь/имя каталога в репозитории (`pxf/`, `docker/pxf/` и т.п.) и точная версия драйвера будут приняты при переходе к реализации; важно только, что JAR хранится в Git и монтируется в `/data/pxf/lib` как read‑only. +Договорённость для реализации: + +- Путь в репозитории: условно `pxf/postgresql-42.7.3.jar`. +- Путь внутри контейнера: `/data/pxf/lib/postgresql-jdbc.jar` (через bind‑mount, read‑only). +- Обновление драйвера в будущем — ручная операция (заменить JAR в `pxf/` и скорректировать путь в `docker-compose.yml` при необходимости). ## 5. Сервер PXF для bookings-db (jdbc-site.xml) @@ -60,11 +64,13 @@ PXF использует концепцию «серверов» (`servers/<им План: - Создать сервер с именем `bookings-db` (название привязываем к сервису Docker, чтобы не путаться). -- Конфиг лежит в файле: - - `$PXF_BASE/servers/bookings-db/jdbc-site.xml`. +- Конфиг храним в репозитории, например в файле: + - `pxf/servers/bookings-db/jdbc-site.xml`. +- В контейнере этот файл будет доступен как: + - `/data/pxf/servers/bookings-db/jdbc-site.xml` (bind‑mount read‑only). - Внутри прописываем параметры подключения к демо‑БД `demo` в Postgres `bookings-db`. -Черновой шаблон `jdbc-site.xml` (значения логина/пароля берём из `.env`, блок `BOOKINGS_DB_*`): +Черновой шаблон `jdbc-site.xml` (значения логина/пароля берём из `.env.example`, блок `BOOKINGS_DB_*` — для учебного стенда допускаем хардкод тех же дефолтных значений): ```xml @@ -95,9 +101,10 @@ PXF использует концепцию «серверов» (`servers/<им Замечания: -- Здесь `${BOOKINGS_DB_USER}` и `${BOOKINGS_DB_PASSWORD}` — просто напоминание, что значения нужно взять из `.env`; в реальном файле будут жёстко записаны строки (допустимо для локального учебного стенда). +- В реальном файле `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 @@ -116,7 +123,7 @@ PXF использует концепцию «серверов» (`servers/<им - `PROFILE=JDBC` — используем JDBC‑профиль. - `SERVER=bookings-db` — имя сервера из `jdbc-site.xml`. -Черновой шаблон DDL (без конкретных типов, заполним позже по реальной схеме): +Черновой шаблон DDL (без конкретных типов, заполним позже по реальной схеме; предполагается, что финальный DDL ляжет в `sql/ddl_gp.sql`, чтобы применяться через `make ddl-gp`): ```sql CREATE EXTERNAL TABLE public.ext_bookings_bookings ( @@ -141,23 +148,28 @@ FORMAT 'CUSTOM' (formatter='pxfwritable_import'); Предварительные условия: -- `.env` скопирован из `.env.example` и актуален (`BOOKINGS_DB_*`, `GP_*` выставлены). +- `.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`. -2. (Первый раз) Установить JDBC‑драйвер и настроить сервер: - - зайти в контейнер `greenplum` и под `gpadmin` выполнить команды из раздела 4 и 5 (скачивание JAR, создание `jdbc-site.xml`, `pxf cluster sync && restart`). -3. Зайти в Greenplum: +2. Инициализировать Airflow (если ещё не делали): + - `make airflow-init`. +3. Подготовить демо‑БД bookings: + - `make bookings-init`. +4. Применить DDL в Greenplum (создать таблицы, включая внешнюю `public.ext_bookings_bookings`): + - `make ddl-gp`. +5. Зайти в Greenplum: - `make gp-psql`. -4. Проверить, что расширение PXF присутствует: +6. Проверить, что расширение PXF присутствует: - `\dx pxf`. -5. Создать внешнюю таблицу `public.ext_bookings_bookings` (DDL из раздела 6, уже с реальными колонками). -6. Выполнить простые запросы: +7. Выполнить простые запросы: - `SELECT COUNT(*) FROM public.ext_bookings_bookings;` - `SELECT * FROM public.ext_bookings_bookings LIMIT 5;` @@ -195,5 +207,24 @@ FORMAT 'CUSTOM' (formatter='pxfwritable_import'); ## 8. Открытые вопросы / TODO - Уточнить целевую таблицу(ы) в `demo` для внешнего представления (скорее всего `bookings.bookings`), аккуратно выписать DDL и обновить шаблон из раздела 6. -- Принять окончательное решение по версии JDBC‑драйвера и зафиксировать ссылку в документации (с учётом возможного обновления Postgres 16). -- Решить, хотим ли мы автоматизировать шаги установки драйвера/создания `jdbc-site.xml` через init‑скрипт в `/docker-entrypoint-initdb.d` или оставить их полностью ручными для наглядности. +- При переносе 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 airflow-init` → `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`; + - посмотреть сообщения в `/data/pxf/logs`.