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

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

---

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

projects/sl3/{project_name}/
  readme.md
  settings/
    connection.json
  {module}/
    tables/
    scripts/
    init/
    {module}.sql
  deploy/
  _docs/
    diagrams/
    openapi.yaml
    architecture.md

---

Правила

1. Модуль

Каждый функциональный модуль — отдельная папка в корне проекта.

SQLite не поддерживает схемы, поэтому модуль = логическая группа объектов.

2. Таблицы

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

3. Скрипты

• Путь: {module}/scripts/
• Произвольные SQL-скрипты (запросы, утилиты, seed-данные)
• SQLite не поддерживает хранимые процедуры — вся логика в скриптах

4. Init

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

5. Deploy

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

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

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

7. Диаграммы

• Путь: _docs/diagrams/
• Формат: Mermaid .md файлы
• Обязательные диаграммы:
  • er-diagram.md — ER-диаграмма всех таблиц модуля (связи, типы, ключи)
• Правила формирования:
  • Каждая таблица — блок erDiagram с перечислением полей и типов
  • Связи между таблицами отображаются через ||--o{, |--|{ и т.д.
  • Внешние ключи помечаются комментариями
  • LEGACY-таблицы помечаются %% LEGACY в комментарии
  • Типы данных: SQLite → Mermaid (INTEGER→int, TEXT→string, REAL→real, BLOB→blob)

---

Особенности SQLite

• Нет хранимых функций и процедур — папка functions/ не используется
• Нет схем — все объекты в одном пространстве имён
• Один файл БД = один проект
• Типы данных ограничены: INTEGER, TEXT, REAL, BLOB, NUMERIC
• PRAGMA настройки размещаются в init/

---

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

projects/sl3/kit_example_sl3/
  readme.md
  settings/
    connection.json
  main/
    tables/
      users.sql
      sessions.sql
      roles.sql
    scripts/
      seed_roles.sql
      2026-07-08_add-email-column.sql
    init/
      create_indexes.sql
      set_pragmas.sql
    main.sql
  deploy/
    docker-compose.yml
    up.bat
    down.bat
  _docs/
    diagrams/
    openapi.yaml
    architecture.md

---

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

Файл: settings/connection.json

{
  "database": "{database_name}.db",
  "journal_mode": "WAL",
  "foreign_keys": true
}

---

Инструменты

• sqlite3 {database}.db < {script}.sql — выполнить скрипт
• .dump — экспорт всей БД
• .read — выполнить файл SQL