From 1efeb58449429198a40c6fa754c29959898adcf8 Mon Sep 17 00:00:00 2001
From: Dmitry Dementev <me@dementev.space>
Date: Thu, 8 Jan 2026 23:14:53 +0300
Subject: [PATCH] =?UTF-8?q?=D0=B4=D0=B8=D0=B0=D0=B3=D0=BD=D0=BE=D1=81?=
 =?UTF-8?q?=D1=82=D0=B8=D0=BA=D0=B0=20=D0=BF=D1=80=D0=BE=D0=B1=D0=BB=D0=B5?=
 =?UTF-8?q?=D0=BC=D1=8B=20=D1=81=20pxf?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 TODO.md                       |  1 +
 docs/internal/pxf_bookings.md | 45 +++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/TODO.md b/TODO.md
index f95ede5..2c55d2f 100644
--- a/TODO.md
+++ b/TODO.md
@@ -24,6 +24,7 @@
   - при необходимости доработать init‑скрипты в `pxf/init/` и/или документацию,
     чтобы порядок действий для ментей был однозначным и воспроизводимым;
   - добавить краткий раздел в README/TESTING о типичных ошибках PXF/Greenplum и шагах по их устранению.
+  - диагностика текущего кейса: `docs/internal/pxf_bookings.md` (раздел «Известная проблема»).
 
 - Разобраться с генератором demodb:
   - после `make bookings-init` таблица `bookings.bookings` остаётся пустой;
diff --git a/docs/internal/pxf_bookings.md b/docs/internal/pxf_bookings.md
index 0283146..3b2061f 100644
--- a/docs/internal/pxf_bookings.md
+++ b/docs/internal/pxf_bookings.md
@@ -101,6 +101,51 @@
   - причина: файлы уже лежат в `PXF_BASE` на томе, а seed из образа по умолчанию не перетирает их;
   - решение: `make build` + restart `greenplum` + (при необходимости) `PXF_SEED_OVERWRITE=1`.
 
+## 9. Известная проблема: `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 “уже настроенным” и
+пропускает создание расширения.
+
+Отдельно `/start_greenplum_with_pxf.sh` пытается выполнить `CREATE EXTENSION IF NOT EXISTS pxf`
+в фоне, но это может “не попасть” в окно готовности базы (гонка при старте), поэтому после старта:
+- PXF может быть “running” (`pxf cluster status`), но
+- `protocol pxf` в базе ещё не создан.
+
+### Как проверить
+
+- `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'';\"'"`
+
+Если команда ничего не вернула — расширение не создано.
+
+### Временный workaround (ручной)
+
+1) Создать расширение:
+`docker compose exec greenplum bash -lc "su - gpadmin -c '/usr/local/greenplum-db/bin/psql -d gp_dwh -c \"CREATE EXTENSION IF NOT EXISTS pxf;\"'"`
+
+2) Повторить DDL:
+`make ddl-gp`
+
+### Что чинить в коде (идея фикса)
+
+Сделать создание расширения `pxf` независимым от наличия `pxf-env.sh`:
+- либо убрать/изменить условие в `/start_gpdb.sh` (в образе),
+- либо перестать копировать `pxf-env.sh` в ensure‑скрипте и дать базовому скрипту создать его,
+- либо сделать retry‑логику `CREATE EXTENSION pxf` надёжной (повторять попытки и проверять результат).
+
 ## 8. Связанные файлы
 
 - `Dockerfile.greenplum`