SQLite: После обновления приложения миграция SQLite останавливается

#Симптом и границы применимости

После обновления приложения миграция схемы SQLite останавливается на ALTER TABLE, дублирующей колонке или неудачном пересоздании таблицы. Нужно определить применённую версию схемы, сохранить рабочую базу целиком и сделать миграцию повторяемой.

#Как отличить возможные причины

#Пошаговая диагностика и безопасное исправление

1. 1. Остановите повторное применение миграцииОтключите автозапуск проблемной миграции на тестовой копии и сохраните точное первое сообщение об ошибке. Не выполняйте её многократно на рабочем файле: часть операций могла уже измениться.

1. 2. Сделайте штатную резервную копию базыДля работающего приложения используйте SQLite Backup API либо команду .backup в sqlite3 с гарантированным доступом к файлу; нельзя просто копировать только .db при активном WAL и ожидать все последние транзакции.

   Linux · Терминал (Bash)С осторожностьюКопировать всёВыделить

   Терминал на тесте; укажите реальный существующий тестовый файл и отдельный путь резервной копии. Проверьте её открытие.

   sqlite3 ./app-test.db ".backup './app-test-before-migration.db'"

   Команда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.

1. 3. Проверьте версию движка и схемыОткройте sqlite3 для тестовой базы и запросите sqlite_version, user_version и список таблиц. user_version — соглашение приложения, а не автоматически обновляемый SQLite номер.
2. В sqlite3, чтение структуры

   SQLКомандаКопировать всёВыделить

   В sqlite3, чтение структуры. Подключайтесь к копии.

   SELECT sqlite_version();

   PRAGMA user_version;

   SELECT name, type FROM sqlite_schema WHERE type IN ('table','index') ORDER BY name;

1. 4. Проверьте фактическую структуру проблемной таблицыВыполните PRAGMA table_info и сравните со скриптом миграции. Если колонка уже есть, повторный ALTER TABLE ADD COLUMN не нужен; убедитесь, что её тип и ограничения совпадают с ожидаемыми.

   SQLКомандаКопировать всёВыделить

   sqlite3, чтение; orders — условное имя.

   PRAGMA table_info(orders);

1. 5. Изучите ограничения текущего ALTER TABLESQLite поддерживает разные подмножества ALTER TABLE в зависимости от версии; сложная переделка таблицы часто требует безопасного создания новой таблицы, переноса данных, проверки ограничений и переименования. Не применяйте случайный SQL из старой версии.

1. 6. Сделайте миграцию атомарной и повторяемойНа тесте оберните поддерживаемые изменения в явную транзакцию, предварительно проверяйте структуру и обновляйте PRAGMA user_version только после успеха всех операций. При ошибке выполняйте ROLLBACK, а не вручную редактируйте sqlite_schema.

1. 7. Проверьте целостность после миграцииНа тестовом файле выполните PRAGMA integrity_check и foreign_key_check, сравните COUNT(*) важных таблиц со снимком. integrity_check не заменяет проверку внешних ключей, поэтому нужны обе команды.

   SQLКомандаКопировать всёВыделить

   sqlite3; чтение. integrity_check должен вернуть ok, foreign_key_check — ни одной строки.

   PRAGMA integrity_check;

   PRAGMA foreign_key_check;

1. 8. Выполните повторный прогон и планируйте выпускЗапустите миграцию вторично на отдельной копии уже обновлённой базы: она должна корректно распознать применённую версию и не пытаться создавать те же колонки. Только после этого согласуйте окно обслуживания и откат из проверенной копии.

#Как проверить, что проблема устранена

Миграция на копии проходит один раз; повторный запуск ничего не портит; PRAGMA integrity_check возвращает ok, данные и схема соответствуют требованиям выпуска.

#Если исправление не помогло

Если ALTER TABLE недоступен в версии библиотеки, выясните фактическую версию SQLite в приложении, а не только в системной sqlite3 CLI; для PHP/Python могут быть разные сборки.