From 4515577b4ae97ea51e4254228af8d28bbc2cf514 Mon Sep 17 00:00:00 2001
From: Dmitry Dementev <me@dementev.space>
Date: Tue, 9 Dec 2025 09:57:52 +0300
Subject: [PATCH] =?UTF-8?q?=D0=A1=D0=BC=D0=B5=D0=BD=D0=B0=20=D0=B2=D0=BD?=
 =?UTF-8?q?=D0=B5=D1=88=D0=BD=D0=B5=D0=B3=D0=BE=20=D0=BF=D0=BE=D1=80=D1=82?=
 =?UTF-8?q?=D0=B0=20GreenPlum?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                     | 52 ++++++++++++++++++++++++++++++++++-
 TESTING.md                    |  2 +-
 docker-compose.yml            |  5 ++--
 docs/internal/pxf_bookings.md |  2 +-
 4 files changed, 55 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index a5799b3..894182d 100644
--- a/README.md
+++ b/README.md
@@ -199,7 +199,7 @@ docker compose -f docker-compose.yml exec bookings-db bash -lc 'PGPASSWORD="$POS
 - `GP_USER` — пользователь (по умолчанию: gpadmin)
 - `GP_PASSWORD` — пароль (по умолчанию: gpadmin)
 - `GP_DB` — база данных (по умолчанию: gpadmin)
-- `GP_PORT` — порт (по умолчанию: 5432)
+- `GP_PORT` — порт Greenplum внутри Docker-сети (по умолчанию: 5432, менять обычно не нужно; внешний порт на хосте для подключения клиентов — 5435).
 
 ### Демо-БД bookings (Postgres)
 - `BOOKINGS_DB_USER` — пользователь Postgres для демобазы (по умолчанию: bookings)
@@ -247,6 +247,56 @@ docker compose -f docker-compose.yml exec bookings-db bash -lc 'PGPASSWORD="$POS
 
 ---
 
+## 🧩 Подключение к базам через DBeaver
+
+Ниже — краткая инструкция, как подключиться к Greenplum и демо-БД bookings из DBeaver. Перед этим убедитесь, что стенд запущен:
+
+- `cp .env.example .env` (если ещё не делали)
+- `make up`
+- `make bookings-init`
+- `make ddl-gp`
+
+### Greenplum (аналитическая БД)
+
+1. Откройте DBeaver → **New Database Connection**.
+2. Выберите драйвер **PostgreSQL** (или **Greenplum**, если он есть в вашей версии DBeaver).
+3. На вкладке **Main** заполните поля (по умолчанию):
+   - `Host`: `localhost`
+   - `Port`: `5435` (внешний порт Greenplum на хосте)
+   - `Database`: значение `GP_DB` (по умолчанию `gpadmin`)
+   - `Username`: значение `GP_USER` (по умолчанию `gpadmin`)
+   - `Password`: значение `GP_PASSWORD` (по умолчанию `gpadmin`)
+4. Нажмите **Test Connection** → **OK**, затем **Finish**.
+
+После подключения:
+
+- Основные таблицы лаба — в схеме `public` базы `gpadmin` (например, `public.orders`).
+- После настройки PXF и выполнения `make ddl-gp` станет доступна внешняя таблица `public.ext_bookings_bookings` — чтение из демо-БД bookings через PXF.
+
+### bookings-db (демо-БД источника)
+
+Для работы с исходными данными (демо-БД `demo`) достаточно стандартного PostgreSQL-подключения.
+
+1. Откройте DBeaver → **New Database Connection** → драйвер **PostgreSQL**.
+2. На вкладке **Main** укажите (значения по умолчанию из `.env.example`):
+   - `Host`: `localhost`
+   - `Port`: значение `BOOKINGS_DB_PORT` из `.env` (по умолчанию `5434`)
+   - `Database`: `demo`
+   - `Username`: `BOOKINGS_DB_USER` (по умолчанию `bookings`)
+   - `Password`: `BOOKINGS_DB_PASSWORD` (по умолчанию `bookings`)
+3. Нажмите **Test Connection** → **OK**, затем **Finish**.
+
+После подключения:
+
+- Основные таблицы находятся в схеме `bookings` базы `demo` (например, `bookings.bookings`, `bookings.tickets`, `bookings.flights` и т.д.).
+- Можно сравнивать данные:
+  - между `bookings.bookings` в Postgres и `public.ext_bookings_bookings` в Greenplum;
+  - между временем (`book_date`) в UTC в `demo` и локальным временем в Greenplum (учитывая `TZ=Europe/Moscow`).
+
+> Если вы меняли порты или креды в `.env`, не забудьте подставить те же значения в настройках соединений в DBeaver.
+
+---
+
 ## 🆘 Типичные проблемы и решения
 
 | Проблема | Решение |
diff --git a/TESTING.md b/TESTING.md
index 23324ab..ff6fcb5 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -18,7 +18,7 @@
 
 ## 3. Подготовка Docker-стенда
 - `cp .env.example .env` (если файла ещё нет) и проверьте переменные:
-  - `GP_PORT` не конфликтует с локальным PostgreSQL.
+  - `GP_PORT` — внутренний порт Greenplum в Docker-сети (по умолчанию 5432, менять не нужно); внешний порт для подключения с хоста фиксирован на `5435`, поэтому локальный PostgreSQL на 5432 не помешает.
   - `GP_USE_AIRFLOW_CONN=true` при желании использовать Airflow Connection; `false` — fallback на ENV.
 - `make up` — поднимаем все сервисы. Важно дождаться статуса `healthy` у `pgmeta` и `greenplum` (`docker compose ps`).
 - `make airflow-init` — миграции мета-БД и создание пользователя Airflow; занимает ~1–2 минуты.
diff --git a/docker-compose.yml b/docker-compose.yml
index 4cff3d9..d69da27 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -50,10 +50,9 @@ services:
       GREENPLUM_PASSWORD: ${GP_PASSWORD:-gpadmin}
       GREENPLUM_DATABASE_NAME: ${GP_DB:-gpadmin}
       GREENPLUM_PXF_ENABLE: "true"
-      # GP_PORT: ${GP_PORT:-5432}
-    # Порты: внешний 5432
+    # Порты: внешний 5435 (на хосте)
     ports:
-      - "${GP_PORT}:5432"
+      - "5435:5432"
     volumes:
       - ./sql:/sql:ro
       - ./pxf/postgresql-42.7.3.jar:/pxf-local/postgresql-42.7.3.jar:ro
diff --git a/docs/internal/pxf_bookings.md b/docs/internal/pxf_bookings.md
index c5ebb0a..2c67262 100644
--- a/docs/internal/pxf_bookings.md
+++ b/docs/internal/pxf_bookings.md
@@ -15,7 +15,7 @@ _Этот файл внутренний, удалить перед итогов
   - Greenplum в режиме singlenode;
   - установленный PXF (`/usr/local/pxf`, `pxf version release-6.10.1`);
   - стартовый скрипт `/start_gpdb.sh`, который умеет включать PXF по флагу `GREENPLUM_PXF_ENABLE=true`.
-- Внешний мир (IDE/pytest) подключается к Greenplum по порту `${GP_PORT}` с хоста, а к `bookings-db` — по порту `${BOOKINGS_DB_PORT}` (см. `.env`).
+- Внешний мир (IDE/pytest) подключается к Greenplum по порту `5435` на хосте (см. `docker-compose.yml`), а к `bookings-db` — по порту `${BOOKINGS_DB_PORT}` (см. `.env`).
 
 ## 3. Включение PXF в нашем стенде (дизайн)