152 lines
4.2 KiB
Markdown
152 lines
4.2 KiB
Markdown
# Правило — Формирование проекта 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` — экспорт/импорт дампа |