# Правило — Формирование проекта 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`

```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` — экспорт/импорт дампа