74 lines
4.4 KiB
Markdown
74 lines
4.4 KiB
Markdown
# Руководство по миграциям базы данных
|
||
|
||
## Общая информация
|
||
|
||
Система миграций базы данных предназначена для поддержания структуры базы данных в актуальном состоянии и обеспечения возможности обновления между версиями приложения.
|
||
|
||
## Структура миграций
|
||
|
||
Миграции размещены в папке `backend/db/migrations/` и именуются по схеме `XXX_descriptive_name.sql`, где XXX - порядковый номер миграции.
|
||
|
||
### Категории миграций
|
||
|
||
1. **Основные структурные миграции** (001-013) - создание базовых таблиц и первоначальной структуры
|
||
2. **Функциональные миграции** - изменения, связанные с конкретными функциями
|
||
3. **Рефакторинг и оптимизация** (019+) - улучшение существующей структуры
|
||
|
||
## Важные миграции
|
||
|
||
### 019_identity_system_refactor.sql
|
||
|
||
Комплексная миграция, объединяющая несколько предыдущих миграций (014-018) для улучшения системы идентификации пользователей:
|
||
|
||
- Создание таблицы `guest_user_mapping` для связи гостевых идентификаторов с пользователями
|
||
- Добавление прямой связи между сообщениями и пользователями через поле `user_id`
|
||
- Очистка дублирующихся данных между таблицами `users` и `user_identities`
|
||
- Нормализация формата идентификаторов (приведение к нижнему регистру)
|
||
- Добавление ограничений и триггеров для поддержания целостности данных
|
||
|
||
## Применение миграций
|
||
|
||
При развертывании новой версии приложения миграции применяются автоматически через скрипт `backend/db/run-migrations.js`. Порядок применения определяется порядковым номером в имени файла.
|
||
|
||
## Создание новых миграций
|
||
|
||
1. **Именование**: Используйте следующий свободный порядковый номер и описательное имя
|
||
2. **Идемпотентность**: Миграции должны быть безопасны для повторного выполнения
|
||
3. **Проверки**: Добавляйте проверки существования объектов перед их созданием
|
||
4. **Тестирование**: Проверяйте миграцию на тестовой базе данных перед применением
|
||
|
||
Пример правильной идемпотентной миграции:
|
||
|
||
```sql
|
||
-- Создание таблицы, если она не существует
|
||
CREATE TABLE IF NOT EXISTS example_table (
|
||
id SERIAL PRIMARY KEY,
|
||
name VARCHAR(255) NOT NULL
|
||
);
|
||
|
||
-- Добавление колонки, если она отсутствует
|
||
DO $$
|
||
BEGIN
|
||
IF NOT EXISTS (
|
||
SELECT 1 FROM information_schema.columns
|
||
WHERE table_name = 'example_table' AND column_name = 'new_column'
|
||
) THEN
|
||
ALTER TABLE example_table ADD COLUMN new_column INTEGER;
|
||
END IF;
|
||
END $$;
|
||
```
|
||
|
||
## Архивация устаревших миграций
|
||
|
||
Устаревшие миграции, объединенные в более новые версии, перемещаются в папку `backend/db/migrations/archive/`. Для архивации используйте скрипт `backend/scripts/cleanup_migrations.sh`.
|
||
|
||
## Диагностические функции
|
||
|
||
Для проверки состояния базы данных и корректности миграций созданы следующие диагностические функции SQL:
|
||
|
||
- `verify_identity_system()` - проверка состояния системы идентификации пользователей
|
||
|
||
Пример использования:
|
||
```sql
|
||
SELECT * FROM verify_identity_system();
|
||
``` |