Уточнения планов

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/<server>/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
 <?xml version="1.0" encoding="UTF-8"?>
@@ -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‑драйвер и настроить сервер:
+2. Инициализировать Airflow (если ещё не делали):
-   - зайти в контейнер `greenplum` и под `gpadmin` выполнить команды из раздела 4 и 5 (скачивание JAR, создание `jdbc-site.xml`, `pxf cluster sync && restart`).
+   - `make airflow-init`.
-3. Зайти в Greenplum:
+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, уже с реальными колонками).
+7. Выполнить простые запросы:
-6. Выполнить простые запросы:
    - `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).
+- При переносе DDL проверить типы дат/времени, чтобы не получить неожиданный сдвиг по часовому поясу (см. `docs/internal/bookings_tz.md`).
-- Решить, хотим ли мы автоматизировать шаги установки драйвера/создания `jdbc-site.xml` через init‑скрипт в `/docker-entrypoint-initdb.d` или оставить их полностью ручными для наглядности.
+- При необходимости добавить интеграционный тест по мотивам раздела 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`.