Настройка SQLite: миграции, индексы, WAL для мобильного приложения

Под ключ: настройка SQLite в мобильном приложении

Мы часто встречаем проекты, где SQLite используется как простая key-value куча. Через полгода такой код превращается в ад из raw-запросов, SQLiteDatabaseLockedException на Android и падений при миграциях. Без правильной настройки база данных становится узким местом: 9 из 10 отзывов о медленной работе приложения связаны с неоптимизированными запросами. На одном из проектов мы сократили время загрузки списка с 8 секунд до 0.3 секунды — всего лишь добавив индекс и включив WAL. Наша команда с 10+ годами опыта в мобильной разработке настраивает SQLite так, чтобы база работала стабильно и масштабировалась без боли.

SQLite встроен в iOS и Android на уровне ОС. Вопрос не в том, подключить ли его — он уже есть. Вопрос в том, как с ним работать так, чтобы через полгода не переписывать всё с нуля из-за запутанных raw-запросов или падений с SQLiteDatabaseLockedException на Android. Правильная архитектура с ORM и WAL-режимом устраняет 80% типовых проблем.

Как выбрать ORM для вашего проекта?

Работать с SQLite напрямую через android.database.sqlite.SQLiteDatabase или sqlite3 на iOS — вариант для минимальных сценариев. В реальных проектах используют ORM:

Room — стандарт для Android, за него голосует Google. GRDB.swift на iOS даёт типобезопасные запросы без лишней магии. SQLDelight интересен для KMM-проектов: один .sq файл с SQL, генерирует Kotlin и Swift код.

Room на Android: правильная архитектура

@Entity(tableName = "products",
    indices = [Index(value = ["category_id"]), Index(value = ["sku"], unique = true)]
)
data class ProductEntity(
    @PrimaryKey val id: String,
    @ColumnInfo(name = "category_id") val categoryId: String,
    val sku: String,
    val title: String,
    @ColumnInfo(name = "price_cents") val priceCents: Int,
    @ColumnInfo(name = "updated_at") val updatedAt: Long,
    @ColumnInfo(name = "is_deleted") val isDeleted: Boolean = false
)

@Dao
interface ProductDao {
    @Query("SELECT * FROM products WHERE category_id = :categoryId AND is_deleted = 0 ORDER BY title ASC")
    fun observeByCategory(categoryId: String): Flow<List<ProductEntity>>

    @Upsert
    suspend fun upsert(products: List<ProductEntity>)

    @Query("UPDATE products SET is_deleted = 1, updated_at = :timestamp WHERE id = :id")
    suspend fun softDelete(id: String, timestamp: Long)
}

@Upsert появился в Room 2.5 — до этого нужно было @Insert(onConflict = OnConflictStrategy.REPLACE). Soft delete через флаг is_deleted — стандартная практика для синхронизируемых баз, чтобы не потерять запись до подтверждения удаления с сервера.

Миграции — самое болезненное место

Room проверяет exportedSchema при изменении схемы. Если fallbackToDestructiveMigration() — база пересоздаётся при каждом изменении схемы. Это нормально для debug, недопустимо для production.

val db = Room.databaseBuilder(context, AppDatabase::class.java, "app.db")
    .addMigrations(MIGRATION_1_2, MIGRATION_2_3)
    .build()

val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE products ADD COLUMN tags TEXT NOT NULL DEFAULT ''")
        db.execSQL("CREATE INDEX IF NOT EXISTS index_products_updated_at ON products(updated_at)")
    }
}

Экспортируйте схему в JSON (room.schemaLocation в build.gradle) и храните в git. При code review сразу видно, что изменилось в схеме. Room может автоматически сгенерировать миграцию через AutoMigration для простых случаев (добавление колонки), но переименование таблиц и колонок требует @RenameTable/@RenameColumn аннотаций. Грамотная стратегия миграций экономит до 30% времени на сопровождение.

GRDB.swift на iOS

// Открытие и настройка
let dbQueue = try DatabaseQueue(path: dbPath)

try dbQueue.write { db in
    try db.create(table: "products", ifNotExists: true) { t in
        t.primaryKey("id", .text)
        t.column("category_id", .text).notNull().indexed()
        t.column("sku", .text).unique()
        t.column("title", .text).notNull()
        t.column("price_cents", .integer).notNull()
        t.column("updated_at", .integer).notNull()
    }
}

// Реактивное наблюдение через ValueObservation
let observation = ValueObservation.tracking { db in
    try Product.filter(Column("categoryId") == categoryId).fetchAll(db)
}
let cancellable = observation.start(in: dbQueue,
    onError: { error in print(error) },
    onChange: { products in self.updateUI(products) }
)

ValueObservation — аналог Room's Flow: автоматически перезапускает запрос при изменении затронутых таблиц.

Как WAL-режим повышает производительность?

По умолчанию SQLite работает в journal mode. Для мобильных приложений WAL (Write-Ahead Logging) лучше: читатели не блокируют писателей. Room включает WAL автоматически. В GRDB: dbQueue.configuration.journalMode = .wal. Тесты показывают, что WAL снижает задержку записи в 3 раза на Android и в 5 раз на iOS. Это особенно заметно при частых вставках — например, при загрузке офлайн-данных. Подробнее о WAL см. SQLite WAL.

Какие индексы создавать для ускорения запросов?

Индексы на поля в WHERE и ORDER BY снижают время сканирования в 10–100 раз. Без них SQLite выполняет полное сканирование таблицы. Для таблицы orders с 100 000 строк запрос по дате без индекса занимает 2 секунды, с индексом — 20 миллисекунд. Создавайте уникальные индексы на SKU, email — они гарантируют целостность и ускоряют поиск. Оптимальный баланс: не более 5 индексов на таблицу, каждый замедляет запись на 10-20%.

Типичные ошибки и как их избежать

Что входит в работу

• Проектирование схемы базы данных с учётом бизнес-логики
• Выбор и настройка ORM (Room, GRDB, SQLDelight) под iOS/Android/KMM
• Написание миграций с хранением схемы в Git
• Включение WAL-режима и оптимизация индексов
• Документация по работе с базой и инструкция по миграциям
• Code review и тестирование на реальных устройствах

Сроки и стоимость

Настройка SQLite с Room или GRDB, миграционная стратегия, индексы: от 1 недели на одну платформу. Стоимость рассчитывается индивидуально — мы оцениваем проект за 1 день. Внедрите стабильную локальную базу данных — свяжитесь с нами для консультации. За 10+ лет мы реализовали более 50 проектов с локальным хранением данных — средняя экономия бюджета на доработках составляет 30% при правильной начальной настройке. Получите консультацию по вашему проекту уже сегодня.

Как выбрать решение для локального хранения данных (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 недель в зависимости от сложности схемы и требований к конфликт-резолюции. Стоимость рассчитывается индивидуально после аудита вашего проекта. Закажите разработку под ключ — получите консультацию по выбору оптимального стека и миграциям.