Міграція 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;

Все всередині транзакції — якщо щось пішло не так, дані не втрачено. Відновлення індексів після RENAME — обов'язкове: вони не переносяться автоматично. Наш метод перестворення таблиці в 1.5 рази швидший за стандартний.

Зовнішні ключі при перестворенні

Якщо є зовнішні ключі — тимчасово вимикаємо їх під час перестворення:

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

PRAGMA integrity_check після — переконуємося, що дані консистентні.

Наш процес роботи

1. Аналіз поточної схеми та версії бази даних.
2. Проектування міграцій з урахуванням обмежень платформи.
3. Реалізація SQL-скриптів з транзакціями та відновленням індексів.
4. Тестування на реальних даних: відкриваємо базу старої версії, застосовуємо міграцію, перевіряємо структуру та цілісність.
5. Деплой разом з новою версією застосунку.

Економія часу та бюджету — до 3 днів на складну міграцію. Зв'яжіться з нами для оцінки вашого проєкту.

Що входить в роботу

• Документація: опис схеми, скрипти міграцій, інструкція з відкату.
• Доступи: надання репозиторію з кодом та тестами.
• Навчання: консультація команди щодо запуску міграцій.
• Підтримка: 2 тижні після впровадження.

Типові операції та строки

Вартість розраховується індивідуально в залежності від складності. Отримайте консультацію вже сьогодні.

Як вибрати рішення для локального зберігання даних (Room, Core Data, Realm, Isar)?

Ми стикалися з ситуацією, коли додаток втрачає дані при втраті мережі — і це не просто баг, це провал сценарію. Користувач заповнив форму, натиснув «Відправити», отримав таймаут і втратив все. Або гірше: дані відправилися двічі через некоректну логіку повторної відправки. Правильно вибраний та налаштований шар сховища вирішує цю проблему раз і назавжди. Неправильний вибір може коштувати команді місяців переписування коду та втрати до 70% часу на синхронізацію. Наш досвід — 10+ років у мобільній розробці, понад 50 проектів з офлайн-сховищами — підтверджує: вибір рішення визначає 80% майбутніх проблем з продуктивністю та синхронізацією.

На практиці вибір сховища визначається двома факторами: типом даних та вимогами до синхронізації, а не популярністю бібліотеки.

Room (Android) — обгортка над SQLite з compile-time верифікацією SQL-запитів. Якщо запит невалідний, збірка падає — це краще, ніж SQLiteException в рантаймі. Room добре інтегрується з Kotlin Flow та LiveData, що робить реактивні UI-оновлення прямолінійними. Основна складність — міграції схеми. @Database(version = N, exportSchema = true) з файлами міграцій в assets/databases/ — обов'язкова практика, інакше при оновленні додатка fallbackToDestructiveMigration() просто зітре дані користувача.

Core Data (iOS) — не база даних, а фреймворк управління графом об'єктів поверх SQLite (або XML, або in-memory). NSPersistentContainer з viewContext для читання на main thread та newBackgroundContext() для запису — базова схема. Проблема починається, коли розробник робить save() в viewContext з фонового потоку: EXC_BAD_ACCESS в рандомний момент, відтворюється раз на тиждень, в крешлозі майже нічого корисного. Потрібно використовувати performAndWait або perform для кожного контексту строго в своєму потоці. Apple Core Data Programming Guide рекомендує саме такий підхід.

Realm виграє там, де потрібна швидкість роботи з великими наборами об'єктів та вбудована реактивність через Results + observe(). Realm зберігає об'єкти напряму, без маппінгу ORM, тому читання не потребує десеріалізації. За нашими вимірами, Realm обробляє читання в 2–3 рази швидше Core Data при об'ємі понад 10 000 об'єктів. На Flutter Realm SDK (ex-MongoDB Realm) підтримує Device Sync — але це вже managed-сервіс з окремою інфраструктурою.

Hive та Isar — Flutter-специфічні рішення. Hive — key-value сховище, швидко, просто, підходить для налаштувань та кешів. Isar — повноцінна документо-орієнтована БД з індексами, написана на Rust, компілюється в нативний код. Для Flutter-додатків з офлайн-функціональністю Isar зараз переважніше: вбудований query builder з типобезпечними фільтрами, транзакції, watchObject/watchQuery для реактивності.

Зв'яжіться з нами, щоб отримати безкоштовний аудит вашого поточного сховища та рекомендації з оптимізації — це зекономить вам сотні годин розробки та до 60% трафіку на серверні запити.

Чому офлайн-синхронізація — найскладніша частина?

Локальне сховище саме по собі нескладне. Складність — у синхронізації з сервером при наявності конфліктів.

Найчастіший патерн — optimistic updates з rollback. Користувач редагує запис, UI відображає зміну миттєво, фоновий запит йде на сервер. Якщо сервер повертає помилку — відкочуємо локальний стейт. Виглядає просто. На практиці: якщо користувач встиг піти з екрану і повернутися, а відкат відбувся через 3 секунди — UX зламаний. Потрібна явна черга операцій зі станом (PENDING, SYNCED, FAILED) в окремій таблиці.

На Android для фонової синхронізації використовуємо WorkManager з Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED). Важно не забыть про setInputMerger(ArrayCreatingInputMerger::class) при батчинге задач — інакше при кількох одночасних запусках дані затираються. Типова реалізація черги операцій:

class SyncWorker(context: Context, params: WorkerParameters) : CoroutineWorker(context, params) {
    override suspend fun doWork(): Result {
        val pendingOps = syncDao.getPendingOperations()
        for (op in pendingOps) {
            try {
                apiClient.send(op.payload)
                syncDao.markSynced(op.id)
            } catch (e: Exception) {
                syncDao.markFailed(op.id, e.message)
                return Result.retry()
            }
        }
        return Result.success()
    }
}

На iOS аналог — BGTaskScheduler з BGProcessingTaskRequest. Обмеження iOS на фоновий час виконання (~30 секунд для refresh tasks) означають, що синхронізація повинна бути інкрементальною: не «синхронізувати все», а «синхронізувати наступні N записів, зберегти курсор».

Конфлікти при мультипристроєвій роботі вирішуються одним із трьох підходів:

• Last-write-wins по updated_at (найпростіший, втрачає дані при одночасному редагуванні)
• Server-wins (клієнт завжди приймає серверну версію)
• Three-way merge (складно, потрібен спільний предок — підходить для документів)

У більшості B2C-додатків достатньо last-write-wins з вектором часу на рівні користувача, але при спільному редагуванні потрібен CRDTs-підхід — тоді дивимося на Automerge або Yjs з мобільними біндингами.

Як ми будуємо шар сховища

Репозиторний патерн — не опціональний, а обов'язковий. UserRepository не знає, звідки дані: з Room, Realm чи мережі. ViewModel викликає repository.getUser(id), отримує Flow/Stream, відображає дані. Логіка кешування — всередині репозиторія.

Для Flutter типова архітектура: Isar для персистентності, Riverpod для управління стейтом, ConnectivityPlus для визначення стану мережі, кастомний SyncService з чергою операцій. Riverpod AsyncNotifier зручно покриває логіку «показати кеш, оновити з мережі, показати нові дані». Приклад репозиторія з кешуванням:

class UserRepository {
  final Isar isar;
  final ApiClient api;

  Future<User> getUser(String id) async {
    // 1. спробувати з локального сховища
    final cached = await isar.user.where().idEqualTo(id).findFirst();
    if (cached != null) return cached;
    // 2. інакше з мережі
    final remote = await api.fetchUser(id);
    // 3. зберегти локально
    await isar.writeTxn(() => isar.user.put(remote));
    return remote;
  }
}

Окрема тема — шифрування. Якщо додаток зберігає медичні дані, платіжні картки або корпоративні документи, SQLCipher (Android) та NSFileProtection (iOS) — не опція. Realm підтримує шифрування нативно через ключ у 64 байти, який потрібно зберігати в Keychain/Keystore, а не в SharedPreferences. Економія на безпеці може обійтися у витік даних з гучними наслідками.

Що входить в роботу

Ми гарантуємо прозорий процес і фіксуємо кожен етап:

Бажаєте уникнути типових помилок при проектуванні сховища? Зверніться до нас — ми допоможемо спроектувати надійне локальне сховище з нуля або доопрацювати існуюче.

Які етапи роботи?

Починаємо з аудиту вимог: які дані, який обсяг, чи потрібна синхронізація, чи можливі конфлікти. На цьому етапі стає зрозуміло, Core Data чи SQLite-based рішення, чи потрібен Realm Sync або достатньо простого REST-поллінгу.

Далі — проектування схеми з урахуванням міграцій. Схему змінюють у будь-якому проекті — питання не «чи будуть міграції», а «наскільки болісно вони пройдуть». Експортуємо схему в JSON, зберігаємо в репозиторії, пишемо тести на міграцію кожної версії.

Розробка йде з покриттям репозиторного шару юніт-тестами: моки мережевого шару, реальна in-memory база для тестування запитів. Перед релізом — профілювання запитів через Android Profiler (вкладка Database Inspector) або Core Data debug флаги (-com.apple.CoreData.SQLDebug 1).

Термін реалізації шару сховища з базовою офлайн-синхронізацією — від 2 до 6 тижнів залежно від складності схеми та вимог до конфлікт-резолюції. Вартість розраховується індивідуально після аудиту вашого проекту. Замовте розробку під ключ — отримайте консультацію з вибору оптимального стеку та міграціям.