Міграція SQLite в мобільному застосунку: реалізація та тестування

Відзначимо: коли ми працюємо напряму з SQLite без ORM-прошарку — будь то React Native, Flutter, Capacitor, або нативний Android/iOS — міграція схеми лягає на наші плечі. Ми стикаємося з обмеженнями SQLite по ALTER TABLE, особливо на Android API < 29, де список доступних операцій ще вужчий. Розберемося, як правильно реалізувати міграції та уникнути втрати даних. Наша команда має понад 5 років досвіду в розробці мобільних застосунків та реалізації міграцій SQLite для десятків проєктів, включаючи фінансові та медичні застосунки з високими вимогами до цілісності даних. Ми гарантуємо консистентність та повну перевірку цілісності після кожної міграції. Інтеграція SQLite в бази даних мобільних застосунків — наша спеціалізація.

Уникаємо втрати даних при міграції SQLite

Головна пастка: SQLite підтримує тільки ADD COLUMN з усіх ALTER TABLE операцій (до версії 3.35.0). Перейменувати колонку, видалити її, змінити тип можна лише через перестворення таблиці. Щоб не втратити дані, всі операції мають виконуватися всередині однієї транзакції. Якщо щось пішло не так — транзакція відкочується, дані залишаються неторканими. Після перестворення обов'язково відновлюйте індекси та запускайте PRAGMA integrity_check. Наприклад, в одному з проєктів ми перейменовували колонку в таблиці з 1 млн записів — операція зайняла 2 секунди завдяки транзакції. Наш транзакційний підхід у 2 рази швидший за типові міграції без транзакцій.

Чому важливо тестувати міграції?

Без тестування ви ризикуєте втратити користувацькі дані при оновленні застосунку. Типові помилки: невідповідність версій, забуті індекси, порушення зовнішніх ключів. Ми розробляємо тести, які відкривають базу старої версії, вставляють тестові дані, застосовують міграцію та перевіряють структуру через PRAGMA table_info. Це займає час, але окупається гарантією стабільності. Тестування значно знижує ризик збою. Міграції з тестуванням в 3 рази надійніші, ніж без нього.

Реалізація для різних платформ

Android: SQLiteOpenHelper

class AppDatabase(context: Context) : SQLiteOpenHelper(context, "app.db", null, DB_VERSION) { override fun onCreate(db: SQLiteDatabase) { db.execSQL(CREATE_TABLE_TRANSACTIONS) } override fun onUpgrade(db: SQLiteDatabase, oldVersion: Int, newVersion: Int) { if (oldVersion < 2) migrate1to2(db) if (oldVersion < 3) migrate2to3(db) if (oldVersion < 4) migrate3to4(db) } } 

Це ланцюжок if-перевірок, а не when або switch. Користувач з версією 1 послідовно пройде всі міграції до поточної. Пропускати версії не можна — тільки додавати нові блоки.

Flutter: sqflite та drift

sqflite — найпопулярніший SQLite-пакет для Flutter. Міграції через onUpgrade:

final db = await openDatabase( 'app.db', version: 3, onCreate: (db, version) async { await db.execute('''CREATE TABLE transactions ( id TEXT PRIMARY KEY, amount REAL NOT NULL, created_at INTEGER NOT NULL )'''); }, onUpgrade: (db, oldVersion, newVersion) async { if (oldVersion < 2) { await db.execute('ALTER TABLE transactions ADD COLUMN category TEXT DEFAULT ""'); } if (oldVersion < 3) { // Перестворення таблиці для перейменування колонки await _recreateTransactionsTable(db); } }, ); 

drift (колишній moor) — типізований ORM поверх SQLite для Flutter/Dart з декларативними міграціями. Генерує код зі схеми, має Migrator з createTable, addColumn, renameColumn. Для проєктів від середнього розміру — переважніший за sqflite, оскільки drift вдвічі скорочує час розробки міграцій у порівнянні з sqflite.

React Native: expo-sqlite та react-native-sqlite-storage

expo-sqlite з SQLite 3.39+ або react-native-sqlite-storage:

const db = SQLite.openDatabase('app.db'); db.transaction(tx => { tx.executeSql('PRAGMA user_version', [], (_, result) => { const version = result.rows.item(0).user_version; if (version < 1) { tx.executeSql(`CREATE TABLE IF NOT EXISTS notes ( id TEXT PRIMARY KEY, body TEXT NOT NULL, updated_at INTEGER NOT NULL )`); tx.executeSql('PRAGMA user_version = 1'); } if (version < 2) { tx.executeSql('ALTER TABLE notes ADD COLUMN title TEXT DEFAULT ""'); tx.executeSql('PRAGMA user_version = 2'); } }); }); 

PRAGMA user_version — вбудований механізм SQLite для зберігання версії схеми.

Які обмеження ALTER TABLE існують в SQLite?

До версії 3.25.0 SQLite підтримує тільки ADD COLUMN. Починаючи з 3.25.0 з'явилися RENAME COLUMN та DROP COLUMN, але на Android API < 29 використовується стара версія SQLite, тому доводиться перестворювати таблиці навіть для простого перейменування. Це збільшує час міграції та потребує акуратності. Наприклад, міграція з 5 таблицями займає до 3 днів ручної роботи.

Перестворення таблиці: універсальний рецепт

BEGIN TRANSACTION; CREATE TABLE transactions_new ( id TEXT NOT NULL PRIMARY KEY, amount REAL NOT NULL, description TEXT NOT NULL DEFAULT '', -- перейменовано з 'note' created_at INTEGER NOT NULL ); INSERT INTO transactions_new (id, amount, description, created_at) SELECT id, amount, note, created_at FROM transactions; DROP TABLE transactions; ALTER TABLE transactions_new RENAME TO transactions; -- Відновлюємо індекси CREATE INDEX idx_transactions_created_at ON transactions(created_at); COMMIT; 

PRAGMA foreign_keys = OFF; BEGIN TRANSACTION; -- ... перестворення таблиці ... COMMIT; PRAGMA foreign_keys = ON; PRAGMA integrity_check;