Add pipline/init_db/readme.MD

2025-08-10 18:39:12 +08:00 · 2025-08-10 18:39:12 +08:00 · e1632bfeed
commit e1632bfeed
parent ae943a8414
1 changed files with 111 additions and 0 deletions
--- a/pipline/init_db/readme.MD
+++ b/pipline/init_db/readme.MD
@ -0,0 +1,111 @@
+Вот пример **описания пайплайна** (pipeline description), которое можно добавить в `.gitlab-ci.yml` в виде комментария или использовать как документацию к CI/CD-процессу. Оно описывает назначение, параметры и поведение пайплайна:
+
+---
+
+### **Описание пайплайна: Инициализация PostgreSQL из удалённых дампов**
+
+Этот пайплайн предназначен для **инициализации удалённой PostgreSQL-базы данных** с помощью схемы и данных, загружаемых из Nexus-репозитория. Он автоматически выполняет следующие действия:
+- Создаёт временную директорию для дампов.
+- Скачивает SQL-схему и архив с данными (`data.tar.gz`) с Nexus.
+- Ожидает доступности PostgreSQL-сервера.
+- Создаёт базу данных (если не существует).
+- Восстанавливает схему и (опционально) данные.
+
+---
+
+###  **Основные функции**
+- **Загрузка схемы БД** из `schema.sql` по URL.
+- **Загрузка и восстановление данных** из `data.tar.gz` (в формате `pg_dump`).
+- Поддержка опциональной загрузки данных через переменную `LOAD_DATA`.
+- Проверка доступности PostgreSQL перед восстановлением.
+- Работа с защищённым доступом к Nexus через аутентификацию (`SED_NEXUS_USER` / `SED_NEXUS_PASS`).
+
+---
+
+###  **Триггеры**
+- Пайплайн **не запускается при `push`** (например, в ветку).
+- Запускается **вручную** или через API (например, `trigger`, `schedule`, `web` и т.д.).
+
+```yaml
+workflow:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "push"
+      when: never
+    - when: always
+```
+
+>  Используется для **целенаправленной инициализации БД**, а не автоматического запуска при каждом коммите.
+
+---
+
+###  **Переменные окружения**
+
+| Переменная | Обязательная | Описание |
+|-----------|-------------|---------|
+| `POSTGRES_HOST` | Да | Хост PostgreSQL-сервера |
+| `POSTGRES_PORT` | Нет (по умолч. 5432) | Порт PostgreSQL |
+| `POSTGRES_DB` | Да | Имя базы данных для создания/восстановления |
+| `POSTGRES_USER` | Да | Пользователь с правами на создание БД и восстановление |
+| `POSTGRES_PASSWORD` | Да | Пароль пользователя |
+| `SCHEMA_SQL_URL` | Да | URL до `schema.sql` в Nexus |
+| `DATA_DUMP_TAR_GZ_URL` | Да* | URL до `data.tar.gz` (*если `LOAD_DATA=true`) |
+| `LOAD_DATA` | Нет (по умолч. `true`) | Включить/выключить восстановление данных |
+| `SED_NEXUS_USER` / `SED_NEXUS_PASS` | Да | Учётные данные для доступа к Nexus (должны быть заданы в CI/CD Variables) |
+
+>  Переменные с описанием можно редактировать в интерфейсе GitLab при запуске пайплайна (например, `LOAD_DATA` — выпадающий список).
+
+---
+
+###  **Этапы выполнения (`init_db`)**
+
+1. **`create_dump_dir`** — Создаёт директорию `/tmp/dump_data`.
+2. **`download_schema`** — Скачивает `schema.sql` с Nexus.
+3. **`download_data`** — Скачивает `data.tar.gz` (только для проверки URL, далее скачивается снова в `restore_data`).
+4. **`wait_for_postgres`** — Проверяет доступность PostgreSQL (до 150 сек).
+5. **`create_database`** — Создаёт БД, если она не существует.
+6. **`restore_schema`** — Применяет SQL-схему к БД.
+7. **`restore_data`** — Восстанавливает данные через `pg_restore` (если `LOAD_DATA != "false"`).
+
+>  Если скачивание или восстановление завершается с ошибкой — пайплайн останавливается с кодом 1.
+
+---
+
+###  **Теги выполнения**
+- Выполняется **только на раннере с тегом `mmedo`**.
+
+---
+
+###  **Использование**
+1. Убедитесь, что переменные `SED_NEXUS_USER` и `SED_NEXUS_PASS` заданы в CI/CD Settings.
+2. Запустите пайплайн вручную через GitLab UI или API.
+3. Выберите нужные параметры (например, отключите `LOAD_DATA`, если нужны только схемы).
+4. Пайплайн проинициализирует БД на указанном хосте.
+
+---
+
+###  Пример использования
+```bash
+# Запуск через API с кастомными параметрами
+curl --request POST \
+     --form "variables[POSTGRES_HOST]=pg-prod.example.com" \
+     --form "variables[POSTGRES_DB]=myapp_db" \
+     --form "variables[LOAD_DATA]=false" \
+     "https://gitlab.example.com/api/v4/projects/123/pipeline"
+```
+
+---
+
+ **Назначение:** Поддержка окружений (dev, test, staging) через быстрое разворачивание БД из эталонных дампов.  
+ **Рекомендуется использовать с осторожностью в production.**
+
+---
+
+```yaml
+# .gitlab-ci.yml
+#
+# === ПАЙПЛАЙН: Инициализация PostgreSQL из Nexus ===
+# Полное описание: см. ниже
+# ...
+``` 
+
+Или хранить отдельно в `docs/ci-pipeline-init-db.md`.