Kit.Db/rules/pg/db-project-rule.md

Правило — Формирование проекта PostgreSQL БД

---

Структура проекта

projects/pg/{project_name}/
  readme.md
  settings/
    connection.json
  {schema}/
    tables/
    functions/
    scripts/
    init/
    {schema}.psql
  deploy/
  _docs/
    diagrams/
    openapi.yaml
    architecture.md

---

Правила

1. Схема = модуль

Каждая схема PostgreSQL — это отдельная папка-модуль в корне проекта.

2. Таблицы

• Путь: {schema}/tables/
• Формат: .psql
• Одна таблица = один файл
• Именование: {table_name}.psql (например user.psql, cabinet.psql)
• Содержимое: CREATE TABLE с комментариями

3. Функции

• Путь: {schema}/functions/{function_name}/
• Каждая функция — отдельная папка
• Внутри: файл .psql с телом функции
• Именование папки: по имени функции (например user_select_by_ids/)

4. Скрипты

• Путь: {schema}/scripts/
• SQL-скрипты (миграции, seed-данные, утилиты)
• Именование миграций: YYYY-MM-DD_description.sql

5. Init

• Путь: {schema}/init/
• Скрипты инициализации: создание схемы, расширений, начальных данных
• Выполняются один раз при первом развёртывании

6. Deploy

• Путь: deploy/ (в корне проекта)
• Инфраструктура развёртывания: docker-compose, bat-файлы, shell-скрипты
• НЕ SQL-миграции

7. Главный файл модуля

• Путь: {schema}/{schema}.psql
• Точка входа — подключает все таблицы и функции модуля
• Порядок: сначала таблицы, потом функции

8. Post-deploy

• Путь: {schema}/{schema}.post-deploy.psql
• Скрипты, выполняемые после деплоя (seed-данные, обновление зависимостей)

9. Диаграммы

• Путь: _docs/diagrams/
• Формат: Mermaid .md файлы
• Обязательные диаграммы:
  • er-diagram.md — ER-диаграмма всех таблиц схемы (связи, типы, ключи)
• Правила формирования:
  • Каждая таблица — блок erDiagram с перечислением полей и типов
  • Связи между таблицами отображаются через ||--o{, |--|{ и т.д.
  • Внешние ключи помечаются комментариями
  • LEGACY-таблицы помечаются %% LEGACY в комментарии
  • Имена таблиц: schema.table (например auth.user)
  • Типы данных: PostgreSQL → Mermaid (serial→int, text→string, timestamptz→datetime, boolean→bool, integer[]→int[])

---

Пример: проект kit_auth_pg

projects/pg/kit_auth_pg/
  readme.md
  settings/
    connection.json
  auth/
    tables/
      user.psql
      cabinet.psql
      user_cabinet.psql
    functions/
      user_select_by_ids/
        user_select_by_ids.psql
      user_create/
        user_create.psql
    scripts/
      seed_roles.sql
      2026-07-08_user-select-by-ids.sql
    init/
      create_schema.psql
    auth.psql
    auth.post-deploy.psql
  deploy/
    docker-compose.yml
    up.bat
    down.bat
    restart.bat
    init.sh
  _docs/
    diagrams/
    openapi.yaml
    architecture.md

---

Настройки подключения

Файл: settings/connection.json

{
  "host": "localhost",
  "port": 5432,
  "database": "{database_name}",
  "username": "postgres",
  "password": ""
}

---

Инструменты

• apply-psql.sh — применить SQL к БД
• up.bat / down.bat — запуск/остановка контейнера
• docker-compose.yml — конфигурация контейнера
• export.bat / import.bat — экспорт/импорт дампа