SQLite не принимает новый статус: как изменить CHECK и не потерять данные
Приложение обновили, а база осталась прежней. Один новый статус ломает запись задач — и простой ALTER TABLE здесь не поможет. Разбираем миграцию на работающем примере.
Схема SQLite — самостоятельная часть приложения. Обновление Python-кода не меняет ограничения уже созданной таблицы. Для изменения CHECK обычно требуется перестроить таблицу и проверить результат.
Ошибка появляется не там, где её ищут
Представьте сервис, который создаёт задачи со статусами new и active. Разработчики добавляют третий статус — resolved. В интерфейсе он уже существует, обработчики обновлены, тесты бизнес-логики проходят. Но при первой попытке закрыть задачу SQLite отвечает: CHECK constraint failed. Приложение пытается записать значение, которого не было в правилах исходной таблицы.
Здесь легко совершить неправильное исправление: повторить CREATE TABLE IF NOT EXISTS с расширенным списком статусов. Команда выполнится без ошибки, но существующая таблица никуда не исчезнет и не изменится. CREATE TABLE IF NOT EXISTS не является миграцией схемы. Значение resolved по-прежнему будет отклоняться.
Этот класс отказа мы воспроизвели в изолированной SQLite-базе на сервере NOVA: запись со статусом active существовала, попытка заменить статус на resolved завершилась нарушением CHECK. Исходную производственную базу в эксперименте не изменяли.
CREATE TABLE tasks (
id INTEGER PRIMARY KEY,
status TEXT NOT NULL
CHECK (status IN ('new', 'active'))
);
INSERT INTO tasks VALUES (1, 'active');
UPDATE tasks SET status='resolved' WHERE id=1;
-- CHECK constraint failedПеред изменениями: проверить не только данные
Посмотрите фактическую схему, а не только декларацию в коде приложения. Таблица могла быть создана год назад, когда список статусов был короче. Запрос к sqlite_schema покажет SQL, который хранится в самом файле базы. Сравните его с желаемым состоянием и отдельно выпишите ограничения, индексы и триггеры.
Если на таблицу ссылаются другие таблицы, простой рецепт «создать копию, удалить старую» может нарушить внешние ключи. На результат также влияют индексы, триггеры и представления, которые обращаются к старой таблице. SQLite описывает для таких изменений отдельную 12-шаговую процедуру generalized ALTER TABLE. Пример ниже намеренно ограничен таблицей без внешних ключей, индексов, триггеров и представлений; переносить его на сложную схему без адаптации нельзя.
Перед миграцией сохраните согласованную резервную копию. Копирование открытого SQLite-файла командой cp — плохой универсальный рецепт, особенно при работе в режиме WAL. Для живой базы используйте SQLite Backup API или корректно организованную остановку сервиса; после этого проверьте, что копия действительно открывается.
SELECT sql FROM sqlite_schema
WHERE type='table' AND name='tasks';
PRAGMA foreign_key_list(tasks);
PRAGMA index_list(tasks);
PRAGMA integrity_check;Перестройка таблицы: небольшой рабочий пример
В нашей минимальной модели нет дочерних таблиц, внешних ключей, вторичных индексов, триггеров и представлений. Поэтому миграцию можно выполнить в транзакции: создать таблицу с новым ограничением, перенести записи, удалить старую таблицу и переименовать новую. Если любой шаг завершится ошибкой, транзакцию можно откатить.
Не копируйте шаблон вслепую: в настоящей миграции безопаснее явно перечислить колонки и значения по умолчанию. Убедитесь, что не потеряли свойства AUTOINCREMENT, UNIQUE, внешние ключи, триггеры, индексы и специфические ограничения. Никакая успешная команда ALTER TABLE сама по себе этого не гарантирует.
Результат демонстрации на NOVA: до миграции изменение статуса завершалось ошибкой CHECK; после перестройки та же строка получила resolved, а PRAGMA integrity_check вернула ok. Это подтверждает работоспособность именно примера, но не заменяет тестирования вашей схемы.
Если исходная схема использует внешние ключи, порядок действий принципиален: сначала сохраните их исходное состояние и отключите контроль внешних ключей командой PRAGMA foreign_keys=OFF до BEGIN, затем выполните перестройку в транзакции, восстановите индексы, триггеры и представления, запустите PRAGMA foreign_key_check и только после COMMIT верните PRAGMA foreign_keys в исходное состояние. Само отключение внешних ключей внутри уже открытой транзакции не сработает. Следуйте полной процедуре SQLite, а не сокращённому примеру выше.
BEGIN IMMEDIATE;
CREATE TABLE tasks_next (
id INTEGER PRIMARY KEY,
status TEXT NOT NULL
CHECK (status IN ('new','active','resolved'))
);
INSERT INTO tasks_next(id,status)
SELECT id,status FROM tasks;
DROP TABLE tasks;
ALTER TABLE tasks_next RENAME TO tasks;
COMMIT;
UPDATE tasks SET status='resolved' WHERE id=1;
PRAGMA integrity_check;Почему нужен тест обновления существующей базы
Частая ловушка автоматических тестов: они каждый раз создают новую пустую базу по последней версии схемы. Такое тестирование подтверждает, что свежая установка работает, но ничего не говорит о переходе со старой версии. Ошибка проявится только у владельца уже существующего файла. Тест миграции должен начинаться именно с прежней схемы и реальных допустимых состояний.
Минимальный набор проверок: сохранились ли все строки, проходит ли новый статус, отклоняются ли прежние недопустимые значения, не изменились ли внешние ключи и индексы, выдерживает ли система повторный запуск процедуры. Отдельно проверьте неуспешный сценарий — искусственно оборвите транзакцию и убедитесь, что исходная база не осталась наполовину перестроенной.
После миграции проверьте PRAGMA foreign_key_check и PRAGMA integrity_check. Первая ищет нарушения связности, вторая проверяет целостность структуры файла. Обе важны, но ни одна не доказывает, что приложение сохранило все бизнес-смыслы: например, что отчёты по статусам не перестали считать завершённые задачи.
PRAGMA foreign_key_check;
PRAGMA integrity_check;
SELECT COUNT(*) AS rows_after FROM tasks;
SELECT status, COUNT(*) FROM tasks GROUP BY status;Как предупредить такую аварию при следующем выпуске
У схемы базы должна быть своя версия, а у приложения — явный порядок миграций. В SQLite для этого можно использовать PRAGMA user_version или отдельную таблицу истории. При старте приложение сравнивает версию файла с ожидаемой, выполняет необходимые миграции один раз и только после проверки открывает рабочий режим.
Для значимых изменений полезна репетиция на копии производственной базы без чувствительных данных. Так проявляются старые значения, забытые индексы и особенности данных, которых нет в тестовых фикстурах. Не стоит автоматически применять потенциально разрушительные миграции на единственной копии файла — особенно когда сервис должен постоянно оставаться доступным.
Здесь главное не хитрость SQLite, а дисциплина обновлений. Исходный код и существующая база живут в разных временных слоях. Если меняется допустимое состояние приложения, нужно продумать путь перехода для уже сохранённых данных. Иначе самый безобидный новый пункт в интерфейсе способен остановить фоновую службу.