bartwell 3 мар в 05:00

Delight SQL Viewer: отладка SQLDelight-базы прямо в приложении

Простой

4 мин

Туториал

Привет! Хочу поделиться инструментом, который может существенно упростить жизнь тем, кто использует SQLDelight для работы с базами данных в Kotlin Multiplatform-проектах. Этот инструмент называется Delight SQL Viewer.

Кратко о проблеме

Когда вы разрабатываете мультиплатформенное приложение (Android, iOS или Desktop) и используете SQLDelight, нередко приходится заглядывать «под капот», чтобы проверить, что хранится в таблицах базы, либо быстро отредактировать какую-то строку. Обычно это требует либо выгрузки файла базы, либо использования отладочных инструментов IDE (Android Studio Database Inspector и т.п.), что иногда бывает неудобно или просто недоступно.

Delight SQL Viewer решает эту задачу, позволяя открыть удобный интерфейс для просмотра, редактирования, добавления и удаления строк напрямую внутри приложения. При этом библиотека легко встраивается в общий (common) код Kotlin Multiplatform.

Основные возможности

Мультиплатформенность: библиотека написана на Kotlin Multiplatform и работает на Android, iOS и Desktop.
Прямое управление данными в SQLDelight-базе: не нужно выгружать файлы или подключаться внешними инструментами.
Ярлыки (Shortcuts) на мобильных платформах (iOS и Android): при долгом нажатии на иконку приложения можно сразу открыть Delight SQL Viewer.
Лёгкая интеграция: библиотека доступна в Maven Central, а для её подключения достаточно нескольких строк в Gradle.
Возможность отключения в релизных сборках: не нужно «тащить» отладочный инструмент в продакшен. Можно использовать stub-библиотеку или просто не вызывать нужные функции.

Установка

Подключение в общий (common) модуль

В файле shared/build.gradle.kts (или эквивалентном Gradle-файле) добавьте:

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                api("ru.bartwell.delightsqlviewer:library:1.0.0")
            }
        }
    }
}

Для iOS нужно экспортировать библиотеку в iOS-фреймворк:

framework {
    export("ru.bartwell.delightsqlviewer:library:1.0.0")
}

Отключение в релизных сборках

Если хотите исключить Delight SQL Viewer из продакшена (чтобы не светить отладочные возможности и не увеличивать размер приложения), вы можете:

Подключать stub-библиотеку вместо основной:

val isRelease = /* Ваша логика определения релизной сборки */

if (isRelease) {
    export("ru.bartwell.delightsqlviewer:stub:1.0.0")
} else {
    export("ru.bartwell.delightsqlviewer:library:1.0.0")
}

if (isRelease) {
    api("ru.bartwell.delightsqlviewer:stub:1.0.0")
} else {
    api("ru.bartwell.delightsqlviewer:library:1.0.0")
}

Не вызывать DelightSqlViewer.init(...) и DelightSqlViewer.launch() при сборке релиза. Например, используя BuildConfig или аналогичные механизмы условной компиляции.

Инициализация на разных платформах

Delight SQL Viewer требует от вас лишь SqlDriver, который вы уже используете для SQLDelight. На каждой платформе необходимо передать этот драйвер (и контекст, если нужно) через соответствующий EnvironmentProvider.

Android

val sqlDriver: SqlDriver = // Инициализация SQLDelight
DelightSqlViewer.init(
    object : AndroidEnvironmentProvider {
        override fun getSqlDriver() = sqlDriver
        override fun getContext() = context
    }
)

Здесь context — это ваш Context, например this или applicationContext.
Библиотека автоматически добавляет shortcut (ярлык) на иконке приложения при long press.

Если этот ярлык не нужен, можно отключить его:

DelightSqlViewer.init(
    object : AndroidEnvironmentProvider { ... },
    isShortcutEnabled = false
)

iOS

let sqlDriver = // SQLDelight driver
let provider = IosEnvironmentProvider(sqlDriver: sqlDriver)
DelightSqlViewer.shared.doInit(provider: provider)

По умолчанию также создаётся ярлык для иконки iOS-приложения.
Чтобы он корректно работал, в вашем AppDelegate или UISceneDelegate нужно обработать событие вызова этого ярлыка.

Пример фрагмента кода в AppDelegate:

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        configurationForConnecting connectingSceneSession: UISceneSession,
        options: UIScene.ConnectionOptions
    ) -> UISceneConfiguration {
        return ShortcutActionHandler.shared.getConfiguration(session: connectingSceneSession)
    }
}

Или если в приложении уже есть логика обработки других ярлыков:

...
} else if item.type == DelightSqlViewer.shared.getShortcutId() {
    DelightSqlViewer.shared.launch()
}
...

Desktop

val sqlDriver: SqlDriver = // SQLDelight driver
DelightSqlViewer.init(
    object : DesktopEnvironmentProvider {
        override fun getSqlDriver() = sqlDriver
    }
)

На Desktop нет ярлыка, но вы можете добавить кнопку, пункт в меню или хоткей, который будет вызывать:
```
DelightSqlViewer.launch()
```

Запуск просмотрщика

После инициализации всё просто. Например, в общем коде Compose UI (Android / Desktop):

Button(onClick = { DelightSqlViewer.launch() }) {
    Text("Open SQL Viewer")
}

На iOS (Swift/SwiftUI):

Button("Open SQL Viewer") {
    DelightSqlViewer.shared.launch()
}

На Android и iOS вызов метода launch() является опциональным, так как Viewer можно вызывать через ярлык.

Как только Viewer запущен, вы увидите экран с:

Списком таблиц
Детальным представлением содержимого выбранной таблицы
Возможностью редактировать, добавлять и удалять строки

Как это выглядит

Типичные сценарии использования

Тестирование. QA-инженеры могут быстро проверить разные сценарии, добавив/изменив нужные записи без перезапуска окружения.
Отладка. При сложных багах, когда нужно выставить определённые флаги или поля, Delight SQL Viewer помогает сделать это «на лету».

Итог

Delight SQL Viewer упрощает жизнь тем, кто использует SQLDelight для управления базой данных в Kotlin Multiplatform-проектах. Он обеспечивает быстрый доступ к содержимому таблиц, возможность редактировать записи без лишних действий и легко «убирается» из продакшен-сборки, когда инструмент уже не нужен.

Ссылка на репозиторий: https://github.com/bartwell/delight-sql-viewer

Если у вас возникнут вопросы или улучшения, буду рад вашей обратной связи в репозитории!

Хабы: