docs(main): очистка docs, адаптация для студентов, починка ссылок
Шаг 5 плана main/solution split: - Удалены внутренние документы с main: plans/, archive/, PRD, assignment_design, pxf_bookings, bookings_tz, benchmarks, TODO.md - AGENTS.md: убраны упоминания plans/archive, agent-dag-testing - Починены 19 битых markdown-ссылок во всех оставшихся файлах - bookings_ods_design: airplanes/seats помечены как студенческие, обновлён DAG-граф (routes без зависимости от airplanes) - bookings_dds_design: обновлено описание DQ факта (student SK) - bookings_to_gp_dds: обновлена DQ-семантика для main - qa-plan: уточнено — ods.airplanes/seats пусты by design на main Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
@@ -1,75 +0,0 @@
|
||||
# Бенчмарк генерации bookings: параллельность и тюнинг PostgreSQL
|
||||
|
||||
> Дата: 2026-03-09
|
||||
> Железо: Intel Core i7-11800H @ 2.30GHz (8 ядер / 16 потоков), игровой ноутбук
|
||||
> Среда: WSL2, Docker Desktop, PostgreSQL 16 в контейнере
|
||||
> Данные: seed-дамп 60 дней (~500k bookings, ~180k boarding_passes, ~1.2M tickets)
|
||||
|
||||
## Контекст
|
||||
|
||||
Генератор demodb (`postgrespro/demodb`) использует очередь событий `gen.events` с обработкой через `process_queue()`. При `jobs>1` воркеры запускаются через `dblink_send_query` и конкурируют за очередь через `SELECT ... FOR UPDATE SKIP LOCKED`.
|
||||
|
||||
Задача: найти оптимальную конфигурацию для `make bookings-generate-day` (инкремент +1 день).
|
||||
|
||||
## Методика
|
||||
|
||||
- Между экспериментами: `make bookings-init BOOKINGS_JOBS=N` (восстановление из seed-дампа, ~18 сек).
|
||||
- Замер: `time make bookings-generate-day BOOKINGS_JOBS=N`.
|
||||
- Контроль: `max(book_date)` должен сдвинуться на +1 день.
|
||||
- Тюнинг PG: `ALTER SYSTEM SET` + `docker compose restart bookings-db`.
|
||||
|
||||
Параметры тюнинга PostgreSQL:
|
||||
```
|
||||
shared_buffers = 512MB (дефолт: 128MB)
|
||||
work_mem = 64MB (дефолт: 4MB)
|
||||
maintenance_work_mem = 256MB (дефолт: 64MB)
|
||||
effective_cache_size = 1GB (дефолт: 4GB)
|
||||
wal_buffers = 16MB (дефолт: -1, авто)
|
||||
checkpoint_completion_target = 0.9 (дефолт: 0.9)
|
||||
random_page_cost = 1.1 (дефолт: 4.0)
|
||||
```
|
||||
|
||||
## Результаты
|
||||
|
||||
| # | Тюнинг PG | sync_commit | Jobs | Время | vs baseline |
|
||||
|---|-----------|-------------|------|--------|--------------|
|
||||
| 1 | нет | on | 1 | 2m 48s | **baseline** |
|
||||
| 2 | нет | on | 2 | 8m 36s | 3× хуже |
|
||||
| 3 | да | on | 1 | 3m 01s | шум |
|
||||
| 4 | да | on | 2 | 8m 42s | 3× хуже |
|
||||
| 5 | да | off | 1 | 2m 50s | шум |
|
||||
| 6 | да | off | 2 | 8m 39s | 3× хуже |
|
||||
|
||||
Повторный инкремент (прогретый кэш): 5m 03s (jobs=2), не замерялся (jobs=1).
|
||||
|
||||
## Выводы
|
||||
|
||||
### 1. jobs=1 оптимален для инкрементов
|
||||
|
||||
Для генерации +1 дня параллельность через dblink **контрпродуктивна**:
|
||||
- Два воркера конкурируют за одну очередь `gen.events` через `FOR UPDATE SKIP LOCKED` — это row-level lock contention.
|
||||
- Overhead: dblink-соединения, синхронизация через `gen.stat_jobs`, polling через `dblink_is_busy()`.
|
||||
- На WSL2 дополнительно: виртуализированный I/O не масштабируется при параллельных записях.
|
||||
|
||||
При генерации с нуля (`make bookings-generate`, десятки тысяч событий) jobs>1 **может** давать прирост, но не тестировалось в этом бенчмарке.
|
||||
|
||||
### 2. Тюнинг PostgreSQL не влияет
|
||||
|
||||
Увеличение shared_buffers в 4 раза, work_mem в 16 раз и т.д. не дало измеримого эффекта. Узкое место — не буферы и не I/O, а сама логика генератора: последовательная обработка событий с COMMIT после каждого.
|
||||
|
||||
### 3. synchronous_commit=off не влияет
|
||||
|
||||
Генератор делает COMMIT после каждого события (~сотни раз за день). Ожидалось, что `synchronous_commit=off` ускорит запись WAL. Эффект не обнаружен — вероятно, WAL-буферы и так справляются при одном потоке.
|
||||
|
||||
### 4. VACUUM-ивенты — отдельная проблема
|
||||
|
||||
Генератор вставляет в очередь событие `VACUUM` каждую неделю модельного времени. Обработчик запускает `VACUUM ANALYZE` всей базы через `dblink_exec`. При 500k+ строках это занимает минуты. Решение: `DELETE FROM gen.events WHERE type = 'VACUUM'` перед `continue()` в инкрементальных скриптах.
|
||||
|
||||
## Итоговая конфигурация
|
||||
|
||||
```
|
||||
BOOKINGS_JOBS=1 # синхронно, без dblink — ~3 мин на +1 день
|
||||
BOOKINGS_INIT_DAYS=60 # seed-дамп покрывает ~34 дня бронирований + boarding_passes
|
||||
```
|
||||
|
||||
Тюнинг PostgreSQL не требуется для текущих объёмов данных.
|
||||
@@ -1,29 +0,0 @@
|
||||
# Временное ТЗ по блоку bookings (для текущей разработки)
|
||||
|
||||
_Внутренний файл для наставника: поясняет, как устроен источник `bookings-db` и генерация данных. Студентам обычно не нужен._
|
||||
|
||||
- Контейнер `bookings-db` — отдельный сервис Postgres из `docker-compose.yml`, база по умолчанию `demo` (из upstream demodb), без переименований.
|
||||
- Доступ снаружи не блокируем (порт `5434` по умолчанию), чтобы позже читать через PXF и подключаться из Greenplum.
|
||||
- Инициализация: два способа:
|
||||
- `make bookings-init` (рекомендуется): быстрое восстановление из seed-дампа (~18 сек).
|
||||
- `make bookings-generate` (для разработчиков): полная генерация с нуля — клонирует demodb с закреплённым коммитом, накладывает патчи (`engine`: `jobs=1` синхронно + `busy()` игнорирует свой pid; `install.sql`: `DROP DATABASE IF EXISTS`, `connstr` без хардкода), ждёт `pg_isready`, ставит `gen.connstr` и GUC `bookings.start_date/init_days/jobs`, затем запускает `/bookings/generate_next_day.sql` через `psql -f`. Значения по умолчанию: стартовая дата 2017-01-01, `init_days=60`, `jobs=2`.
|
||||
- Генерация следующего дня: `make bookings-generate-day` прогоняет тот же SQL (читает GUC, вызывает `generate/continue`, ждёт `busy()`, закрывает dblink). При `jobs=1` всё синхронно, без dblink.
|
||||
- Исходники demodb: клонируем по требованию с фиксированным хешем, кладём в `bookings/demodb/` (в `.gitignore`), патчи лежат в `bookings/patches/` и применяются автоматически при `make bookings-generate`.
|
||||
- Документация: в README описаны команды (`bookings-init`, `bookings-generate`, проверка данных, генерация дня), параметры `.env`; настройка PXF/ETL — следующий этап.
|
||||
|
||||
## Текущее состояние
|
||||
- `make bookings-init` — быстрое восстановление из seed-дампа (~18 сек), рекомендуется для студентов.
|
||||
- `make bookings-generate` — полная генерация с нуля: автоматически применяет патчи (`engine_jobs1_sync.patch`, `install_drop_if_exists.patch`), ждёт готовности Postgres через `pg_isready`, запускает `install.sql`, выставляет `gen.connstr`/GUC и вызывает `generate_next_day.sql` через `psql -f`.
|
||||
- Дефолты: `BOOKINGS_START_DATE=2017-01-01`, `BOOKINGS_INIT_DAYS=60`, `BOOKINGS_JOBS=2`. При `jobs=1` генерация идёт синхронно без dblink, `busy()` не учитывает текущую сессию.
|
||||
- `.env.example`/README обновлены под новые дефолты; каталог `bookings/demodb/` в `.gitignore`.
|
||||
- Патчи лежат в `bookings/patches/` и накладываются при `bookings-clone-demodb`.
|
||||
|
||||
## Текущее состояние тестов/проблем
|
||||
- Чистый прогон `make bookings-init` (восстановление из seed-дампа) проходит за ~18 секунд.
|
||||
- Чистый прогон `make bookings-generate` (после `docker compose down -v` и удаления `bookings/demodb`) проходит за ~1,5 минуты: база ставится, `busy()` → `f`, `bookings.bookings` от `2017-01-01 00:00:18` до `2017-01-01 23:59:59`.
|
||||
- Ранее зависание на `busy()` при `jobs=1` лечится патчем: `process_queue` теперь синхронный, а `busy()` игнорирует текущий backend.
|
||||
- Данных пока только на 1 день по умолчанию, чтобы генерация не занимала много времени.
|
||||
|
||||
## Идеи/следующие шаги
|
||||
- Если понадобится больше дней — увеличивать `BOOKINGS_INIT_DAYS`, но помнить, что генерация может идти долго; контролировать через `SELECT busy();`.
|
||||
- Следующий этап — PXF/ETL в Greenplum; текущая задача — лишь подготовить источник bookings.
|
||||
@@ -1,201 +0,0 @@
|
||||
# PXF для bookings в учебном стенде (актуально)
|
||||
|
||||
Этот документ описывает **текущую реализацию** PXF в проекте: чтение данных из демо‑БД
|
||||
`bookings` (Postgres, сервис `bookings-db`) в Greenplum через JDBC.
|
||||
|
||||
## 1. Что должно работать
|
||||
|
||||
- В Greenplum доступны внешние таблицы:
|
||||
- `public.ext_bookings_bookings` (создаётся `make ddl-gp`);
|
||||
- `stg.bookings_ext` (создаётся DAG `bookings_stg_ddl`).
|
||||
- PXF должен быть готов **после каждого старта** контейнера `greenplum`.
|
||||
|
||||
## 2. Почему мы делаем свой образ Greenplum
|
||||
|
||||
Изначально PXF‑скрипты/конфиги монтировались в контейнер как bind‑mount `:ro`.
|
||||
Базовый entrypoint образа Greenplum пытается делать `chown` файлов в
|
||||
`/docker-entrypoint-initdb.d/`, из‑за чего контейнер иногда падал с ошибкой:
|
||||
|
||||
`chown: changing ownership ... Read-only file system`
|
||||
|
||||
Снять `:ro` тоже нежелательно — можно получить проблемы с правами на файлах хоста
|
||||
(файл становится `root`, IDE перестаёт сохранять, появляются лишние изменения в git).
|
||||
|
||||
Решение для учебного стенда:
|
||||
|
||||
- собрать **свой образ** Greenplum (`Dockerfile.greenplum`);
|
||||
- «вшить» в образ seed‑файлы и скрипты PXF;
|
||||
- на каждом старте контейнера идемпотентно докладывать файлы в `PXF_BASE`,
|
||||
который живёт на persistent volume.
|
||||
|
||||
## 3. Где что хранится
|
||||
|
||||
**Внутри образа (immutable):**
|
||||
|
||||
- seed для PXF: `/opt/pxf-seed/` (JDBC‑JAR и `servers/bookings-db/jdbc-site.xml`);
|
||||
- скрипты:
|
||||
- `/opt/pxf-scripts/ensure_pxf_bookings.sh` (подготовка `PXF_BASE`);
|
||||
- `/start_greenplum_with_pxf.sh` (startup wrapper).
|
||||
|
||||
**На persistent volume (переживает рестарты):**
|
||||
|
||||
- `PXF_BASE` по умолчанию: `${GREENPLUM_DATA_DIRECTORY}/pxf` → в нашем compose это
|
||||
`/data/pxf` на томе `greenplum_data`.
|
||||
|
||||
Важно: так как `PXF_BASE` лежит на томе, обновления seed‑файлов из нового образа
|
||||
**не перезатирают** файлы в `PXF_BASE` автоматически (это сделано намеренно, чтобы
|
||||
не ломать ручные правки студентов).
|
||||
|
||||
## 4. Что происходит при старте контейнера `greenplum`
|
||||
|
||||
1) Docker запускает контейнер с базовым entrypoint образа и командой
|
||||
`/start_greenplum_with_pxf.sh` (она задана в `Dockerfile.greenplum` как `CMD`).
|
||||
|
||||
2) `/start_greenplum_with_pxf.sh` выполняет подготовку PXF:
|
||||
|
||||
- запускает ensure‑скрипт `/opt/pxf-scripts/ensure_pxf_bookings.sh`;
|
||||
- параллельно пытается выполнить `CREATE EXTENSION IF NOT EXISTS pxf`
|
||||
в базе `${GP_DB}` (по умолчанию `gp_dwh`), когда Greenplum начинает принимать
|
||||
подключения.
|
||||
|
||||
3) Затем управление передаётся оригинальному старту Greenplum: `exec /start_gpdb.sh`.
|
||||
|
||||
4) Healthcheck сервиса `greenplum` ждёт и готовность Greenplum, и то, что PXF уже
|
||||
запущен (`pxf cluster status`). Это нужно, чтобы Airflow не стартовал раньше PXF.
|
||||
|
||||
## 5. Управляющие переменные окружения
|
||||
|
||||
Все переменные можно задать в `.env` (см. `.env.example`):
|
||||
|
||||
- `PXF_SEED_OVERWRITE=1` — принудительно перезаписать seed‑файлы из образа в `PXF_BASE`
|
||||
(обычно нужно после правок в каталоге `pxf/`).
|
||||
- `PXF_SYNC_ON_START=1` — выполнять `pxf cluster sync` при старте контейнера
|
||||
(делает старт чуть дольше, но гарантирует актуальные конфиги на хостах кластера).
|
||||
|
||||
## 6. Быстрая ручная проверка
|
||||
|
||||
1) Дождаться `healthy` у `greenplum`:
|
||||
|
||||
`docker compose ps`
|
||||
|
||||
2) Проверить статус PXF (PXF CLI запускается только под пользователем `gpadmin`):
|
||||
|
||||
`docker compose exec greenplum bash -lc "su - gpadmin -c '/usr/local/pxf/bin/pxf cluster status'"`
|
||||
|
||||
3) После применения DDL (`make ddl-gp`) проверить чтение через PXF:
|
||||
|
||||
- `make gp-psql`
|
||||
- `SELECT COUNT(*) FROM public.ext_bookings_bookings;`
|
||||
|
||||
## 7. Типовые ошибки
|
||||
|
||||
- `protocol "pxf" does not exist`
|
||||
- причина: не создано расширение `pxf` в базе Greenplum;
|
||||
- решение: перезапустить `greenplum` (скрипт сделает `CREATE EXTENSION IF NOT EXISTS pxf`)
|
||||
или выполнить вручную `CREATE EXTENSION pxf;`.
|
||||
- `Connection refused` к порту `5888`
|
||||
- причина: PXF не поднялся/не успел подняться;
|
||||
- решение: проверить `pxf cluster status`, посмотреть логи PXF в `/data/pxf/logs`,
|
||||
перезапустить сервис `greenplum`.
|
||||
- PXF «не подхватывает» изменения конфигов
|
||||
- причина: файлы уже лежат в `PXF_BASE` на томе, а seed из образа по умолчанию не перетирает их;
|
||||
- решение: `make build` + restart `greenplum` + (при необходимости) `PXF_SEED_OVERWRITE=1`.
|
||||
|
||||
## 8. Известная проблема: `protocol "pxf" does not exist` на «холодном старте» (исправлено)
|
||||
|
||||
Раньше (воспроизводилось в `./scripts/e2e_smoke.sh`) при первом `make ddl-gp` можно было получить:
|
||||
|
||||
`ERROR: protocol "pxf" does not exist`
|
||||
|
||||
### Почему так происходило
|
||||
|
||||
В базовом `/start_gpdb.sh` из образа Greenplum создание расширения `pxf` связано с проверкой
|
||||
файла `${PXF_BASE}/conf/pxf-env.sh`:
|
||||
|
||||
- если `pxf-env.sh` **отсутствует**, скрипт выполняет `pxf cluster prepare/register` и затем
|
||||
`CREATE EXTENSION IF NOT EXISTS pxf`;
|
||||
- если `pxf-env.sh` **уже существует**, этот блок **пропускается**, и расширение может не появиться.
|
||||
|
||||
При этом наш ensure‑скрипт `pxf/init/10_pxf_bookings.sh` копировал `pxf-env.sh` в `${PXF_BASE}`
|
||||
ещё до запуска Greenplum, из‑за чего базовый скрипт считал PXF “уже настроенным” и
|
||||
пропускал создание расширения.
|
||||
|
||||
### Что изменили
|
||||
|
||||
- создание `extension pxf` вынесено в `start_greenplum_with_pxf.sh` и обёрнуто ретраями;
|
||||
- `pxf-env.sh` по‑прежнему копируется в `PXF_BASE`, чтобы `/start_gpdb.sh` не пытался выполнять
|
||||
`pxf cluster prepare` на непустом `PXF_BASE`;
|
||||
- healthcheck `greenplum` ждёт не только PXF, но и наличие `extension pxf`.
|
||||
- добавлен экспорт `PGPASSWORD` для `pxf cluster start`, чтобы `docker compose stop/start`
|
||||
не ломал запуск из‑за `password authentication failed` для `gpadmin`.
|
||||
|
||||
### Если ошибка всё ещё возникает
|
||||
|
||||
1) Пересоберите образ и перезапустите контейнер `greenplum`:
|
||||
`make build && make down && make up`
|
||||
|
||||
2) Проверьте наличие extension:
|
||||
`docker compose exec greenplum bash -lc "su - gpadmin -c '/usr/local/greenplum-db/bin/psql -d gp_dwh -t -A -c \"SELECT extname FROM pg_extension WHERE extname = ''pxf'';\"'"`
|
||||
|
||||
## 9. Связанные файлы
|
||||
|
||||
- `Dockerfile.greenplum`
|
||||
- `docker-compose.yml` (сервис `greenplum`: `build`, `hostname`, env, healthcheck)
|
||||
- `pxf/init/10_pxf_bookings.sh` (ensure‑логика)
|
||||
- `pxf/init/start_greenplum_with_pxf.sh` (старт контейнера)
|
||||
- `docs/stack.md` (раздел «Greenplum + PXF: свой образ»)
|
||||
|
||||
## 10. Известная проблема: после `docker compose stop/start` Greenplum может упасть (auth для PXF)
|
||||
|
||||
### Симптом
|
||||
|
||||
После `docker compose stop`, затем `docker compose start` контейнер `greenplum` иногда уходит в `Exited (1)`.
|
||||
В логах видно, что GPDB поднялся, но упал на старте PXF:
|
||||
|
||||
- `INFO - pxf cluster start`
|
||||
- `ERROR: Could not connect to GPDB`
|
||||
- `FATAL: password authentication failed for user "gpadmin"`
|
||||
|
||||
### Текущее понимание причины (почему это “иногда”)
|
||||
|
||||
1) При старте GPDB образ `woblerr/greenplum` генерирует/дописывает `pg_hba.conf` на persistent volume.
|
||||
2) В `pg_hba.conf` присутствует trust‑правило для **конкретного IP** контейнера в docker‑сети
|
||||
(пример из диагностики: `host all gpadmin 172.21.0.2/32 trust`).
|
||||
3) После `docker compose stop/start` Docker может выдать контейнеру **другой IP** (например, `172.21.0.3`).
|
||||
Тогда trust‑правило больше не подходит, и подключение начинает идти по `md5`.
|
||||
4) `pxf cluster start` подключается к GPDB по TCP на `host=gpdbsne` (hostname контейнера),
|
||||
то есть попадает именно в `pg_hba.conf` (а не в local‑auth).
|
||||
5) В результате при “не совпавшем IP” получаем `md5` + пароль (возможно пустой/не тот) → падение на `28P01`.
|
||||
|
||||
Эта проблема выглядит флапающей, потому что IP после `stop/start` иногда совпадает с захардкоженным trust‑/32,
|
||||
а иногда нет.
|
||||
|
||||
### Как подтвердить при следующем воспроизведении
|
||||
|
||||
1) Посмотреть логи `greenplum`:
|
||||
`docker compose logs --tail=200 greenplum`
|
||||
|
||||
2) Найти реальный IP клиента в master‑логах GPDB (на томе):
|
||||
`Password does not match ...` обычно содержит адрес вида `172.21.0.X`.
|
||||
|
||||
3) Сравнить его с trust‑строкой в `pg_hba.conf` на томе:
|
||||
`/data/master/gpseg-1/pg_hba.conf`
|
||||
|
||||
Если IP в ошибке (например, `172.21.0.3`) **не** совпадает с trust‑/32 (например, `172.21.0.2/32`) —
|
||||
это почти наверняка корень падения.
|
||||
|
||||
### Что с этим делать дальше (варианты решения, без реализации здесь)
|
||||
|
||||
Основная цель — убрать зависимость от “случайного IP после stop/start”:
|
||||
|
||||
- заставить `pxf cluster start` подключаться к GPDB через `127.0.0.1` (тогда работает существующий trust на localhost);
|
||||
- или перестать добавлять в `pg_hba.conf` trust на конкретный `172.21.0.2/32` и заменить на более стабильное правило
|
||||
(например, на подсеть docker‑сети или на `samehost`);
|
||||
- или закрепить IP контейнера в compose (static IP), чтобы он не “плавал”;
|
||||
- или отказаться от `stop/start` в пользу сценария, который не меняет сетевое окружение (но это хуже для UX студентов).
|
||||
|
||||
### Что реализовано
|
||||
|
||||
- В `pxf/init/start_greenplum_with_pxf.sh` добавлен шаг, который на каждом старте
|
||||
обеспечивает в `pg_hba.conf` trust‑правило `host all gpadmin samehost trust`
|
||||
(вставка перед `host all all 0.0.0.0/0 md5`), и делает `pg_ctl reload`, если GPDB уже запущен.
|
||||
@@ -77,7 +77,7 @@ UNION ALL SELECT 'stg.seats', COUNT(*) FROM stg.seats
|
||||
UNION ALL SELECT 'stg.boarding_passes', COUNT(*) FROM stg.boarding_passes
|
||||
ORDER BY 1;
|
||||
|
||||
-- ODS: все 9 таблиц не пустые
|
||||
-- ODS: эталонные таблицы не пустые (на main ods.airplanes и ods.seats пусты by design)
|
||||
SELECT 'ods.bookings' AS tbl, COUNT(*) FROM ods.bookings
|
||||
UNION ALL SELECT 'ods.tickets', COUNT(*) FROM ods.tickets
|
||||
UNION ALL SELECT 'ods.segments', COUNT(*) FROM ods.segments
|
||||
|
||||
Reference in New Issue
Block a user