db-schema-keeper

name	db-schema-keeper
description	Протокол для любых задач, связанных с базой данных. Использовать этот навык когда пользователь просит создать миграцию, добавить/изменить/удалить колонку, таблицу, индекс или внешний ключ, а также когда задаёт вопрос о структуре БД. Триггерные слова: таблица, колонка, индекс, миграция, схема БД, foreign key, ALTER TABLE, CREATE TABLE.
allowed-tools	Read, Write, Edit, Bash

db-schema-keeper

Навык обеспечивает единый протокол работы со схемой базы данных проекта. Файл docs/database/schema.sql является единственным источником истины о структуре БД. Читать его до выполнения любого действия, обновлять после каждого изменения структуры.

Протокол выполнения

Строго соблюдать следующий порядок шагов при каждом обращении к задаче, связанной с БД:

Шаг 1. Прочитать схему

Всегда читать docs/database/schema.sql первым действием — до ответа на любой вопрос и до любых изменений:

Read: docs/database/schema.sql

Это обязательный шаг даже для вопросов только на чтение (read-only). Схема содержит актуальное состояние всех таблиц, колонок, индексов, внешних ключей и связей.

Шаг 2. Выполнить задачу

После прочтения схемы выполнить то, о чём просит пользователь:

• Вопрос о структуре — ответить на основе прочитанного schema.sql.
• Создание миграции — написать SQL-миграцию в соответствии с существующей схемой. Файлы миграций размещать в migrations/sql/ с именем вида VersionYYYYMMDDHHmmss_<описание>.sql.
• Изменение структуры — внести изменения в docs/database/schema.sql через инструмент Edit, отражая реальное новое состояние схемы.

Шаг 3. Обновить schema.sql (только при изменении структуры)

Если задача изменяла структуру БД (добавление, изменение или удаление таблицы, колонки, индекса, внешнего ключа, ограничения), обновить docs/database/schema.sql инструментом Edit, чтобы файл отражал актуальное состояние.

Для вопросов только на чтение этот шаг пропускать.

Шаг 4. Дописать строку в changelog (только при изменении структуры)

После обновления schema.sql добавить строку changelog в конец файла.

Перед записью получить имя автора из git:

git config user.name

Затем дописать строку:

-- YYYY-MM-DD | <git user.name> | <краткое описание изменения на английском>

Если секции changelog в файле ещё нет, создать её перед записью:

-- =============================================================================
-- ## Changelog
-- =============================================================================

-- YYYY-MM-DD | <git user.name> | <краткое описание изменения на английском>

Правила changelog

• Формат строго: -- YYYY-MM-DD | <git user.name> | <description>
• Автор: всегда брать из git config user.name, не подставлять имя вручную
• Дата: текущая дата в формате YYYY-MM-DD
• Описание: кратко на английском, например:
  • added deleted_at (timestamptz) to users
  • created table core.orders with FK to core.users
  • added index idx_tasks_assignee on core.tasks(assignee_id)
• Запись добавляется ТОЛЬКО при изменении структуры, не для read-only запросов

Примеры

Пример 1: изменение структуры таблицы

Запрос: "Добавь колонку deleted_at в таблицу core.tasks"

1. Read docs/database/schema.sql
2. Найти определение core.tasks, добавить колонку через Edit
3. Обновить docs/database/schema.sql — дописать deleted_at TIMESTAMPTZ NULL в определение таблицы
4. Добавить в changelog:

   -- 2026-04-16 | Alexey Gaybovich | added deleted_at (timestamptz nullable) to core.tasks
   

Пример 2: создание новой таблицы и миграции

Запрос: "Напиши миграцию для новой таблицы core.comments"

1. Read docs/database/schema.sql
2. Написать SQL-миграцию, создать файл migrations/sql/Version20260416000001_create_core_comments.sql
3. Добавить определение таблицы в docs/database/schema.sql через Edit
4. Добавить в changelog:

   -- 2026-04-16 | Alexey Gaybovich | created table core.comments with FK to core.tasks
   

Пример 3: вопрос только на чтение

Запрос: "Какие индексы есть на таблице core.tasks?"

1. Read docs/database/schema.sql
2. Найти и перечислить все индексы на core.tasks
3. Шаг 3 и Шаг 4 пропустить — schema.sql не обновляется, changelog не пишется

Частые ошибки

Ошибка: приступать к задаче без чтения schema.sql. Решение: всегда начинать с Read docs/database/schema.sql, даже если структура кажется очевидной.

Ошибка: обновить schema.sql, но забыть дописать changelog. Решение: changelog — обязательная часть протокола при любом изменении структуры.

Ошибка: писать changelog на русском языке. Решение: описание в changelog всегда на английском языке, кратко и конкретно.

Ошибка: добавить запись в changelog при read-only запросе. Решение: changelog пишется только при фактическом изменении структуры БД.