Синхронизация параметров ¶

Для администраторов: Описание процесса синхронизации параметров, различий между типами параметров и потенциальных проблем при работе с заполненными таблицами.

Введение ¶

Синхронизация параметров — это процесс автоматического создания и обновления структуры таблиц в базе данных в соответствии с определением параметров в системе. При синхронизации создаются или обновляются:

Таблицы фактов (fact-tables) для хранения основных данных
Таблицы ревизий (revision tables) для хранения истории изменений
Представления (views) для вычисляемых параметров
Индексы для оптимизации запросов

Типы параметров и их синхронизация ¶

Обычные параметры ¶

Обычные параметры содержат физические данные, хранящиеся в таблицах фактов.

Что происходит при синхронизации: - Создаётся таблица фактов с колонками для всех измерений и мер - Создаются таблицы ревизий для мер, поддерживающих ревизии - Создаются индексы для оптимизации запросов - Устанавливаются права доступа

Пример структуры таблицы фактов:

CREATE TABLE fact_sales (
    id BIGINT PRIMARY KEY,
    dim_store INTEGER,           -- измерение "Магазин"
    dim_product INTEGER,         -- измерение "Товар"
    dim_date INTEGER,            -- измерение "Дата"
    m_quantity INTEGER,          -- мера "Количество"
    m_revenue DOUBLE PRECISION   -- мера "Выручка"
);

Вычисляемые параметры ¶

Вычисляемые параметры не содержат физических данных, а предоставляют доступ к данным через SQL-запросы.

Что происходит при синхронизации: - НЕ создаётся таблица фактов - Создаётся обычное представление (view) или материализованное представление (materialized view) - Структура представления соответствует ожидаемым измерениям и мерам

Пример создания представления:

CREATE VIEW fact_sales_calculated AS
SELECT 
    dim_store,
    dim_product,
    dim_date,
    SUM(quantity) as m_total_quantity,
    SUM(revenue) as m_total_revenue
FROM fact_sales_raw
GROUP BY dim_store, dim_product, dim_date;

Синхронизация таблиц ревизий ¶

Когда создаются таблицы ревизий ¶

Таблицы ревизий создаются автоматически при синхронизации параметра, если:

Параметр поддерживает ревизии (supports_revisions_flag = True)
Мера не является вычисляемой (is_calculated = False)

Структура таблицы ревизий ¶

CREATE TABLE revision_sales_revenue (
    id BIGINT PRIMARY KEY,
    fact_id BIGINT,              -- ссылка на основную таблицу фактов
    revision_id BIGINT,          -- номер ревизии
    value DOUBLE PRECISION       -- значение меры (тип зависит от типа меры)
);

Что происходит с таблицами ревизий при синхронизации ¶

Создаётся автоматически: - ✅ Новая таблица ревизий при добавлении меры - ✅ Индексы для оптимизации запросов - ✅ Уникальные ограничения

НЕ обновляется автоматически: - ❌ Тип колонки value при изменении типа меры - ❌ Структура существующих таблиц (добавление/удаление колонок)

Важно: Если тип меры изменился, существующая таблица ревизий сохранит старый тип колонки value. Для обновления типа потребуется пересоздание таблицы.

Синхронизация заполненных таблиц ¶

Потенциальные проблемы ¶

При синхронизации параметра с заполненными данными могут возникнуть следующие ситуации:

1. Изменение структуры таблицы ¶

Добавление новой меры: - ✅ Безопасно: Новая колонка добавляется с значением NULL для существующих строк - ✅ Данные сохраняются: Все существующие данные остаются нетронутыми

Удаление меры: - ⚠️ Опасно: Колонка удаляется вместе со всеми данными - ⚠️ Требует подтверждения: Система запросит подтверждение для заполненных таблиц

Изменение типа меры: - ⚠️ Может быть опасно: При несовместимости типов данных - ⚠️ Fallback механизм: Система попытается безопасно изменить тип, при неудаче — пересоздаст колонку

2. Изменение измерений ¶

Добавление измерения: - ✅ Безопасно: Новая колонка добавляется с значением NULL - ✅ Индексы обновляются: Создаются новые индексы

Удаление измерения: - ⚠️ Опасно: Колонка удаляется вместе с данными - ⚠️ Проверка уникальности: Система проверяет, не нарушится ли уникальность

Механизм подтверждения ¶

Для безопасной работы с заполненными таблицами система использует механизм подтверждения:

# Пример вызова с принудительной синхронизацией
parameter.sync(force=True)

Без force=True: - Система проверит наличие данных в таблице - При обнаружении структурных изменений выбросит исключение SyncConfirmationRequired - Потребует явного подтверждения через force=True

С force=True: - Система выполнит все структурные изменения - ⚠️ Внимание: Может привести к потере данных при несовместимых изменениях

Когда запускать синхронизацию ¶

Автоматическая синхронизация ¶

Синхронизация запускается автоматически в следующих случаях:

При загрузке параметров через команду loadparameters
При инициализации проекта через команду initializeproject
При создании нового параметра через админку
При изменении структуры параметра (добавление/удаление измерений или мер)
При изменении ключевых полей измерений или мер

Синхронизация через админку ¶

Автоматическая синхронизация при изменениях¶

При работе с параметрами в админке Django синхронизация запускается автоматически:

При сохранении параметра — автоматически запускается скрипт синхронизации
При изменении измерения — автоматически синхронизируется связанный параметр
При изменении меры — автоматически синхронизируется связанный параметр

Если при автоматической синхронизации возникает ошибка "попытка изменить заполненную таблицу", система: 1. Показывает информативное сообщение о проблеме 2. Запрашивает подтверждение пользователя 3. После подтверждения выполняет синхронизацию с принудительным изменением структуры

Ручной запуск синхронизации¶

В админке можно вручную запустить синхронизацию:

Для одного параметра — откройте параметр для редактирования и сохраните изменения
Для нескольких параметров — выберите параметры в списке и используйте действие "Synchronize parameters"

При ручном запуске синхронизация выполняется асинхронно через Celery, что позволяет: - Не блокировать интерфейс админки - Получить ссылку на задачу для отслеживания прогресса - Просматривать логи выполнения в админке Celery

Ручная синхронизация ¶

Ручная синхронизация может потребоваться в следующих случаях:

После изменения структуры параметра (добавление/удаление мер или измерений)
После изменения типа меры (особенно для таблиц ревизий)
После изменения вычисляемых мер (для обновления представлений)
При возникновении ошибок в структуре таблиц

Команды для синхронизации ¶

Через Django shell¶

# Синхронизация конкретного параметра
python manage.py shell
>>> from planiqum.core.parameters.models import Parameter
>>> param = Parameter.objects.get(key='sales')
>>> param.sync()

# Синхронизация всех параметров
>>> from planiqum.core.parameters.models import Parameter
>>> Parameter.objects.sync_all()

# Принудительная синхронизация (с подтверждением)
>>> param.sync(force=True)

Через скрипт синхронизации¶

# Синхронизация через скрипт (рекомендуется)
python manage.py shell
>>> from planiqum.core.scripts.models import Script
>>> script = Script.objects.get(app_name="src.planiqum.core.parameters", shortname="sync_parameters")

# Синхронная синхронизация
>>> result = script.execute(async_=False, parameter_ids=[1, 2, 3], force=False)

# Асинхронная синхронизация (через Celery)
>>> task = script.execute(async_=True, parameter_ids=[1, 2, 3], force=False)
>>> print(f"Задача запущена: {task.id}")

Через админку¶

Синхронизация одного параметра — откройте параметр и сохраните изменения
Синхронизация нескольких параметров — выберите параметры в списке и используйте действие "Synchronize parameters"
Просмотр логов — используйте ссылку на задачу Celery для отслеживания прогресса

Мониторинг и диагностика ¶

Логи синхронизации ¶

Все операции синхронизации записываются в логи Django с уровнем INFO:

[2024-08-25 14:19:08] INFO|django-logger|Начинаем синхронизацию параметра 'sales'
[2024-08-25 14:19:08] INFO|django-logger|Таблица fact_sales существует, обновляем структуру
[2024-08-25 14:19:08] INFO|django-logger|Добавляем колонку: ALTER TABLE fact_sales ADD COLUMN m_new_measure INTEGER
[2024-08-25 14:19:08] INFO|django-logger|Колонка m_new_measure успешно добавлена
[2024-08-25 14:19:08] INFO|django-logger|Таблица fact_sales успешно синхронизирована

Проверка структуры таблиц ¶

Для проверки текущей структуры таблиц можно использовать SQL-запросы:

-- Проверка структуры таблицы фактов
SELECT column_name, data_type, is_nullable 
FROM information_schema.columns 
WHERE table_name = 'fact_sales' 
ORDER BY ordinal_position;

-- Проверка индексов
SELECT indexname, indexdef 
FROM pg_indexes 
WHERE tablename = 'fact_sales';

-- Проверка таблиц ревизий
SELECT table_name 
FROM information_schema.tables 
WHERE table_name LIKE 'revision_%';

Устранение проблем ¶

Ошибка "Model class django_celery_results.models.TaskResult doesn't declare an explicit app_label" ¶

Проблема: При использовании действия "Synchronize parameters" в админке возникает ошибка:

RuntimeError: Model class django_celery_results.models.TaskResult doesn't declare an explicit app_label and isn't in an application in INSTALLED_APPS.

Причина: В проекте используется кастомная версия django_celery_results, но в коде используется импорт из стандартной библиотеки.

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

# Неправильно:
from django_celery_results.models import TaskResult

# Правильно:
from planiqum.core.django_celery_results.models import TaskResult

Статус: Исправлено в версии системы.

Умная логика безопасности ¶

Система синхронизации автоматически определяет опасность операций только для заполненных таблиц:

Удаление колонки id¶

❌ Всегда требует подтверждения при наличии данных в таблице
Причина: нарушение структуры таблицы и потеря связей

Удаление колонок измерений (dim_)¶

❌ Требует подтверждения при наличии данных в таблице
✅ Безопасно если таблица пустая
Причина: потеря связности данных с иерархиями

Удаление колонок мер (m_)¶

✅ Безопасно если колонка содержит только NULL значения
❌ Требует подтверждения если есть реальные данные
Система автоматически проверяет наличие данных

Изменение типа колонок¶

✅ Безопасно если колонка содержит только NULL значения
❌ Требует подтверждения если есть реальные данные
Причина: возможная потеря или искажение данных при преобразовании

Полный отчет об опасных операциях¶

Система предоставляет детальный отчет с группировкой по типам операций:

Обнаружено 4 опасных операций:

🆔 Удаление колонки id:
  • id: Удаление колонки id может привести к потере данных и нарушению структуры таблицы

🗂️ Удаление колонок измерений:
  • dim_product: Удаление колонки измерения может привести к потере данных

📊 Удаление колонок мер с данными:
  • m_sales_qty: Удаление колонки меры с данными приведет к потере данных

🔧 Изменение колонок с данными:
  • m_revenue: Изменение типа колонки с данными может привести к потере данных

Таблица: fact__sales (1096 записей)
Используйте force=True для принудительного выполнения.

Оптимизация производительности¶

✅ Проверки только для заполненных таблиц: Система выполняет анализ безопасности только если в таблице есть записи
✅ Пустые таблицы: Все операции с пустыми таблицами считаются безопасными и выполняются без подтверждения
✅ Добавление колонок: Больше не считается опасной операцией

Принудительное выполнение¶

Используйте force=True для пропуска всех проверок безопасности
⚠️ Осторожно: может привести к потере данных

См. также ¶

Синхронизация параметров (для разработчиков) — подробности технической реализации
Параметры — общая информация о параметрах
Вычисляемые меры — работа с вычисляемыми мерами
Импорт параметров — автоматическая синхронизация при загрузке

Заключение ¶

Синхронизация параметров — это мощный механизм автоматического управления структурой данных в Planiqum. Понимание принципов работы синхронизации поможет администраторам безопасно управлять параметрами и избежать потери данных.

Рекомендация: При работе с критически важными параметрами всегда создавайте резервные копии перед синхронизацией и тщательно тестируйте изменения на копиях данных.