Create a multiplatform app using Ktor and SQLDelight

Configure SQLDelight

The SQLDelight library allows you to generate a type-safe Kotlin database API from SQL queries. During compilation, the generator validates the SQL queries and turns them into Kotlin code that can be used in the shared module.

The SQLDelight dependency is already included in the project. To configure the library, open the shared/build.gradle.kts file and add the sqldelight {} block in the end. This block contains a list of databases and their parameters:

The packageName parameter specifies the package name for the generated Kotlin sources.

Sync the Gradle project files when prompted.

Generate the database API

First, create the .sq file with all the necessary SQL queries. By default, the SQLDelight plugin looks for .sq files in the sqldelight folder of the source set:

1. In the shared/src/commonMain directory, create a new sqldelight directory.

2. Inside the sqldelight directory, create a new directory with the name com/jetbrains/spacetutorial/cache to create nested directories for the package.

3. Inside the cache directory, create the AppDatabase.sq file (with the same name as the database you specified in the build.gradle.kts file). All the SQL queries for your application will be stored in this file.

4. The database will contain a table with data about launches. Add the following code for creating the table to the AppDatabase.sq file:

   import kotlin.Boolean; CREATE TABLE Launch ( flightNumber INTEGER NOT NULL, missionName TEXT NOT NULL, details TEXT, launchSuccess INTEGER AS Boolean DEFAULT NULL, launchDateUTC TEXT NOT NULL, patchUrlSmall TEXT, patchUrlLarge TEXT, articleUrl TEXT );

5. Add the insertLaunch function for inserting data into the table:

   insertLaunch: INSERT INTO Launch(flightNumber, missionName, details, launchSuccess, launchDateUTC, patchUrlSmall, patchUrlLarge, articleUrl) VALUES(?, ?, ?, ?, ?, ?, ?, ?);

6. Add the removeAllLaunches function for clearing data in the table:

   removeAllLaunches: DELETE FROM Launch;

7. Declare the selectAllLaunchesInfo function for retrieving data:

   selectAllLaunchesInfo: SELECT Launch.* FROM Launch;

8. Generate the corresponding AppDatabase interface (which you will initialize with database drivers later on). To do that, run the following command in the terminal:

   ./gradlew generateCommonMainAppDatabaseInterface

   The generated Kotlin code is stored in the shared/build/generated/sqldelight directory.

Create factories for platform-specific database drivers

To initialize the AppDatabase interface, you will pass an SqlDriver instance to it. SQLDelight provides multiple platform-specific implementations of the SQLite driver, so you need to create these instances separately for each platform.

While you can achieve this with expected and actual interfaces, in this project, you will use Koin to try dependency injection in Kotlin Multiplatform.

1. Create an interface for database drivers. To do this, in the shared/src/commonMain/kotlin directory, create a directory with the name com/jetbrains/spacetutorial/cache (this will add the cache directory to the package).

2. Create the DatabaseDriverFactory interface inside the cache directory:

   package com.jetbrains.spacetutorial.cache import app.cash.sqldelight.db.SqlDriver interface DatabaseDriverFactory { fun createDriver(): SqlDriver }

3. Create the class implementing this interface for Android: in the shared/src/androidMain/kotlin directory, create the com.jetbrains.spacetutorial.cache package with the DatabaseDriverFactory.kt file inside.

4. On Android, the SQLite driver is implemented by the AndroidSqliteDriver class. In the DatabaseDriverFactory.kt file, pass the database information and the context link to the AndroidSqliteDriver class constructor:

   package com.jetbrains.spacetutorial.cache import android.content.Context import app.cash.sqldelight.db.SqlDriver import app.cash.sqldelight.driver.android.AndroidSqliteDriver class AndroidDatabaseDriverFactory(private val context: Context) : DatabaseDriverFactory { override fun createDriver(): SqlDriver { return AndroidSqliteDriver(AppDatabase.Schema, context, "launch.db") } }

5. For iOS, in the shared/src/iosMain/kotlin directory, create a directory with the name com/jetbrains/spacetutorial/cache.

6. Inside this directory, create the DatabaseDriverFactory.kt file and add this code:

   package com.jetbrains.spacetutorial.cache import app.cash.sqldelight.db.SqlDriver import app.cash.sqldelight.driver.native.NativeSqliteDriver class IOSDatabaseDriverFactory : DatabaseDriverFactory { override fun createDriver(): SqlDriver { return NativeSqliteDriver(AppDatabase.Schema, "launch.db") } }

You will implement instances of these drivers later in the platform-specific code of your project.

Implement cache

So far, you have added factories for platform database drivers and an AppDatabase interface to perform database operations. Now, create a Database class, which will wrap the AppDatabase interface and contain the caching logic.

1. In the common source set shared/src/commonMain/kotlin, create a new Database class in the com.jetbrains.spacetutorial.cache directory. It will contain logic common to both platforms.

2. To provide a driver for AppDatabase, pass an abstract DatabaseDriverFactory instance to the Database class constructor:

   package com.jetbrains.spacetutorial.cache internal class Database(databaseDriverFactory: DatabaseDriverFactory) { private val database = AppDatabase(databaseDriverFactory.createDriver()) private val dbQuery = database.appDatabaseQueries }

   This class's visibility is set to internal, which means it is only accessible from within the multiplatform module.

3. Inside the Database class, implement some data handling operations. First, create the getAllLaunches function to return a list of all the rocket launches. The mapLaunchSelecting function is used to map the result of the database query to RocketLaunch objects:

   import com.jetbrains.spacetutorial.entity.Links import com.jetbrains.spacetutorial.entity.Patch import com.jetbrains.spacetutorial.entity.RocketLaunch internal class Database(databaseDriverFactory: DatabaseDriverFactory) { // ... internal fun getAllLaunches(): List<RocketLaunch> { return dbQuery.selectAllLaunchesInfo(::mapLaunchSelecting).executeAsList() } private fun mapLaunchSelecting( flightNumber: Long, missionName: String, details: String?, launchSuccess: Boolean?, launchDateUTC: String, patchUrlSmall: String?, patchUrlLarge: String?, articleUrl: String? ): RocketLaunch { return RocketLaunch( flightNumber = flightNumber.toInt(), missionName = missionName, details = details, launchDateUTC = launchDateUTC, launchSuccess = launchSuccess, links = Links( patch = Patch( small = patchUrlSmall, large = patchUrlLarge ), article = articleUrl ) ) } }

4. Add the clearAndCreateLaunches function to clear the database and insert new data:

   internal class Database(databaseDriverFactory: DatabaseDriverFactory) { // ... internal fun clearAndCreateLaunches(launches: List<RocketLaunch>) { dbQuery.transaction { dbQuery.removeAllLaunches() launches.forEach { launch -> dbQuery.insertLaunch( flightNumber = launch.flightNumber.toLong(), missionName = launch.missionName, details = launch.details, launchSuccess = launch.launchSuccess ?: false, launchDateUTC = launch.launchDateUTC, patchUrlSmall = launch.links.patch?.small, patchUrlLarge = launch.links.patch?.large, articleUrl = launch.links.article ) } } } }

Add internet access permission

To access the internet, an Android application needs the appropriate permission. In the composeApp/src/androidMain/AndroidManifest.xml file, add the <uses-permission> tag:

Add dependency injection

The Koin dependency injection lets you declare modules (sets of components) that you can use in different contexts. In this project, you will create two modules: one for the Android application and another for the iOS app. Then, you will start Koin for each native UI using the corresponding module.

Declare a Koin module that will contain the components for the Android app:

1. In the composeApp/src/androidMain/kotlin directory, create the AppModule.kt file in the com.jetbrains.spacetutorial package.

   In that file, declare the module as two singletons, one for the SpaceXApi class and one for the SpaceXSDK class:

   package com.jetbrains.spacetutorial import com.jetbrains.spacetutorial.cache.AndroidDatabaseDriverFactory import com.jetbrains.spacetutorial.network.SpaceXApi import org.koin.android.ext.koin.androidContext import org.koin.dsl.module val appModule = module { single<SpaceXApi> { SpaceXApi() } single<SpaceXSDK> { SpaceXSDK( databaseDriverFactory = AndroidDatabaseDriverFactory( androidContext() ), api = get() ) } }

   The SpaceXSDK class constructor is injected with the platform-specific AndroidDatabaseDriverFactory class. The get() function resolves dependencies within the module: in place of the api parameter for SpaceXSDK(), Koin will pass the SpaceXApi singleton declared earlier.

2. Create a custom Application class, which will start the Koin module.

   Next to the AppModule.kt file, create the Application.kt file with the following code, specifying the module you declared in the modules() function call:

   package com.jetbrains.spacetutorial import android.app.Application import org.koin.android.ext.koin.androidContext import org.koin.core.context.GlobalContext.startKoin class MainApplication : Application() { override fun onCreate() { super.onCreate() startKoin { androidContext(this@MainApplication) modules(appModule) } } }

3. Specify the MainApplication class you created in the <application> tag of your AndroidManifest.xml file:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"> ... <application ... android:name="com.jetbrains.spacetutorial.MainApplication"> ... </application> </manifest>

Now, you are ready to implement the UI that will use the information provided by the platform-specific database driver.

Prepare the view model with the list of launches

You will implement the Android UI using Jetpack Compose and Material 3. First, you'll create the view model that uses the SDK to get the list of launches. Then, you'll set up the Material theme, and finally, you'll write the composable function that brings it all together.

1. In the composeApp/src/androidMain source set, in the com.jetbrains.spacetutorial package, create the RocketLaunchViewModel.kt file:

   package com.jetbrains.spacetutorial import androidx.compose.runtime.State import androidx.compose.runtime.mutableStateOf import androidx.lifecycle.ViewModel import com.jetbrains.spacetutorial.entity.RocketLaunch class RocketLaunchViewModel(private val sdk: SpaceXSDK) : ViewModel() { private val _state = mutableStateOf(RocketLaunchScreenState()) val state: State<RocketLaunchScreenState> = _state } data class RocketLaunchScreenState( val isLoading: Boolean = false, val launches: List<RocketLaunch> = emptyList() )

   A RocketLaunchScreenState instance will store data received from the SDK and the current state of the request.

2. Add the loadLaunches function that will call the getLaunches function of the SDK in a coroutine scope of this view model:

   import androidx.lifecycle.viewModelScope import kotlinx.coroutines.launch class RocketLaunchViewModel(private val sdk: SpaceXSDK) : ViewModel() { //... fun loadLaunches() { viewModelScope.launch { _state.value = _state.value.copy(isLoading = true, launches = emptyList()) try { val launches = sdk.getLaunches(forceReload = true) _state.value = _state.value.copy(isLoading = false, launches = launches) } catch (e: Exception) { _state.value = _state.value.copy(isLoading = false, launches = emptyList()) } } } }

3. Then add a loadLaunches() call to the init {} block of the class to request data from the API as soon as the RocketLaunchViewModel object is created:

   class RocketLaunchViewModel(private val sdk: SpaceXSDK) : ViewModel() { // ... init { loadLaunches() } }

4. Now, in the AppModule.kt file, specify the view model in the Koin module:

   import org.koin.androidx.viewmodel.dsl.viewModel val appModule = module { // ... viewModel { RocketLaunchViewModel(sdk = get()) } }

Build the Material Theme

You will build your main App() composable around the AppTheme function supplied by a Material Theme:

1. You can generate a theme for your Compose app using the Material Theme Builder. When you're done picking colors, click Export in the top right corner and select the Jetpack Compose (Theme.kt) option.

2. Unpack the archive and copy the theme folder into the composeApp/src/androidMain/kotlin/com/jetbrains/spacetutorial directory.

   

3. In each theme file, Color.kt and Theme.kt, change the package com.example.compose line to refer to your package:

   package com.jetbrains.spacetutorial.theme

4. In the Color.kt file, add two variables for colors you are going to use for successful and unsuccessful launches:

   val app_theme_successful = Color(0xff4BB543) val app_theme_unsuccessful = Color(0xffFC100D)

Implement the presentation logic

Create the main App() composable for your application, and call it from a ComponentActivity class:

1. Create the App.kt file next to the theme directory in the com.jetbrains.spacetutorial package and add the App() composable function:

   package com.jetbrains.spacetutorial import androidx.compose.material3.ExperimentalMaterial3Api import androidx.compose.material3.pulltorefresh.rememberPullToRefreshState import androidx.compose.runtime.Composable import androidx.compose.runtime.getValue import androidx.compose.runtime.remember import org.koin.androidx.compose.koinViewModel @OptIn( ExperimentalMaterial3Api::class ) @Composable fun App() { val viewModel = koinViewModel<RocketLaunchViewModel>() val state by remember { viewModel.state } val pullToRefreshState = rememberPullToRefreshState() if (pullToRefreshState.isRefreshing) { viewModel.loadLaunches() pullToRefreshState.endRefresh() } }

   Here, you are using the Koin ViewModel API to refer to the viewModel you declared in the Android Koin module.

2. Now add the UI code that will implement the loading screen, the column of launch results, and the pull-to-refresh action:

   import com.jetbrains.spacetutorial.theme.AppTheme import com.jetbrains.spacetutorial.entity.RocketLaunch import com.jetbrains.spacetutorial.theme.app_theme_successful import com.jetbrains.spacetutorial.theme.app_theme_unsuccessful import androidx.compose.material3.HorizontalDivider import androidx.compose.material3.MaterialTheme import androidx.compose.material3.Scaffold import androidx.compose.material3.Text import androidx.compose.material3.TopAppBar import androidx.compose.material3.pulltorefresh.PullToRefreshContainer import androidx.compose.ui.Modifier import androidx.compose.ui.Alignment import androidx.compose.foundation.layout.Arrangement import androidx.compose.foundation.layout.Box import androidx.compose.foundation.layout.Column import androidx.compose.foundation.layout.Spacer import androidx.compose.foundation.layout.fillMaxSize import androidx.compose.foundation.layout.height import androidx.compose.foundation.layout.padding import androidx.compose.foundation.lazy.LazyColumn import androidx.compose.foundation.lazy.items import androidx.compose.ui.input.nestedscroll.nestedScroll import androidx.compose.ui.unit.dp @Composable fun App() { // ... AppTheme { Scaffold( topBar = { TopAppBar(title = { Text( "SpaceX Launches", style = MaterialTheme.typography.headlineLarge ) }) } ) { padding -> Box( modifier = Modifier .nestedScroll(pullToRefreshState.nestedScrollConnection) .fillMaxSize() .padding(padding) ) { if (state.isLoading) { Column( verticalArrangement = Arrangement.Center, horizontalAlignment = Alignment.CenterHorizontally, modifier = Modifier.fillMaxSize() ) { Text("Loading...", style = MaterialTheme.typography.bodyLarge) } } else { LazyColumn { items(state.launches) { launch: RocketLaunch -> Column(modifier = Modifier.padding(all = 16.dp)) { Text( text = "${launch.missionName} - ${launch.launchYear}", style = MaterialTheme.typography.headlineSmall ) Spacer(Modifier.height(8.dp)) Text( text = if (launch.launchSuccess == true) "Successful" else "Unsuccessful", color = if (launch.launchSuccess == true) app_theme_successful else app_theme_unsuccessful ) Spacer(Modifier.height(8.dp)) val details = launch.details if (details?.isNotBlank() == true) { Text( text = details ) } } HorizontalDivider() } } } PullToRefreshContainer( state = pullToRefreshState, modifier = Modifier.align(Alignment.TopCenter) ) } } } }

3. Remove the import App line in the MainActivity.kt file in the com.jetbrains.spacetutorial package so that the setContent() function refers to the App() composable you just created in that package.

4. Finally, specify your MainActivity class in the AndroidManifest.xml file:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"> ... <application ... <activity ... android:name="com.jetbrains.spacetutorial.MainActivity"> ... </activity> </application> </manifest>

5. Run your Android app: select composeApp from the run configurations menu, choose an emulator, and click the run button. The app automatically runs the API request and displays the list of launches (the background color depends on the Material Theme you generated):

   

You've just created an Android application that has its business logic implemented in the Kotlin Multiplatform module, and its UI made using native Jetpack Compose.

Add the dynamic linking flag for SQLDelight

By default, the Kotlin Multiplatform wizard generates projects set up for static linking of iOS frameworks.

To use the native SQLDelight driver on iOS, add the dynamic linker flag that allows Xcode tooling to find the system-provided SQLite binary:

1. In Android Studio, right-click the iosApp/iosApp.xcodeproj folder and select the Open In | Xcode option.

2. In Xcode, double-click the project name to open its settings.

3. Switch to the Build Settings tab and search for the Other Linker Flags field.

4. Double-click the field value, click +, and add the -lsqlite3 string.

Prepare a Koin class for iOS dependency injection

To use Koin classes and functions in Swift code, create a special KoinComponent class and declare the Koin module for iOS.

1. In the shared/src/iosMain/kotlin/ source set, create a file with the name com/jetbrains/spacetutorial/KoinHelper.kt (it will appear next to the cache folder).

2. Add the KoinHelper class, which will wrap the SpaceXSDK class with a lazy Koin injection:

   package com.jetbrains.spacetutorial import org.koin.core.component.KoinComponent import com.jetbrains.spacetutorial.entity.RocketLaunch import org.koin.core.component.inject class KoinHelper : KoinComponent { private val sdk: SpaceXSDK by inject<SpaceXSDK>() suspend fun getLaunches(forceReload: Boolean): List<RocketLaunch> { return sdk.getLaunches(forceReload = forceReload) } }

3. Add the initKoin function, which you will use in Swift to initialize and start the iOS Koin module:

   import com.jetbrains.spacetutorial.cache.IOSDatabaseDriverFactory import com.jetbrains.spacetutorial.network.SpaceXApi import org.koin.core.context.startKoin import org.koin.dsl.module fun initKoin() { startKoin { modules(module { single<SpaceXApi> { SpaceXApi() } single<SpaceXSDK> { SpaceXSDK( databaseDriverFactory = IOSDatabaseDriverFactory(), api = get() ) } }) } }

Now, you can start the Koin module in your iOS app to use the native database driver with the common SpaceXSDK class.

Implement the UI

First, you'll create a RocketLaunchRow SwiftUI view for displaying an item from the list. It will be based on the HStack and VStack views. There will be extensions on the RocketLaunchRow structure with useful helpers for displaying the data.

1. Right-click the iosApp/iosApp.xcodeproj directory and choose Open In | Xcode.

2. In your Xcode project, create a new Swift file with the type SwiftUI View and name it RocketLaunchRow.

3. Update the RocketLaunchRow.swift file with the following code:

   import SwiftUI import Shared struct RocketLaunchRow: View { var rocketLaunch: RocketLaunch var body: some View { HStack() { VStack(alignment: .leading, spacing: 10.0) { Text("\(rocketLaunch.missionName) - \(String(rocketLaunch.launchYear))").font(.system(size: 18)).bold() Text(launchText).foregroundColor(launchColor) Text("Launch year: \(String(rocketLaunch.launchYear))") Text("\(rocketLaunch.details ?? "")") } Spacer() } } } extension RocketLaunchRow { private var launchText: String { if let isSuccess = rocketLaunch.launchSuccess { return isSuccess.boolValue ? "Successful" : "Unsuccessful" } else { return "No data" } } private var launchColor: Color { if let isSuccess = rocketLaunch.launchSuccess { return isSuccess.boolValue ? Color.green : Color.red } else { return Color.gray } } }

   The list of launches will be displayed in the ContentView view, which is already included in the project.

4. Create an extension to the ContentView class with a ViewModel class which will prepare and manage the data. Add the following code to the ContentView.swift file:

   extension ContentView { enum LoadableLaunches { case loading case result([RocketLaunch]) case error(String) } @MainActor class ViewModel: ObservableObject { @Published var launches = LoadableLaunches.loading } }

   • The view model (ContentView.ViewModel) connects with the view (ContentView) via the Combine framework:

     • The ContentView.ViewModel class is declared as an ObservableObject.

     • The @Published attribute is used for the launches property, so the view model will emit signals whenever this property changes.

5. Remove the ContentView_Previews structure: you won't need to implement a preview that should be compatible with your view model.

6. Update the body of the ContentView class to display the list of launches and add the reload functionality.

   • This is the UI groundwork: you will implement the loadLaunches function in the next phase of the tutorial.

   • The viewModel property is marked with the @ObservedObject attribute to subscribe to the view model.

   struct ContentView: View { @ObservedObject private(set) var viewModel: ViewModel var body: some View { NavigationView { listView() .navigationBarTitle("SpaceX Launches") .navigationBarItems(trailing: Button("Reload") { self.viewModel.loadLaunches(forceReload: true) }) } } private func listView() -> AnyView { switch viewModel.launches { case .loading: return AnyView(Text("Loading...").multilineTextAlignment(.center)) case .result(let launches): return AnyView(List(launches) { launch in RocketLaunchRow(rocketLaunch: launch) }) case .error(let description): return AnyView(Text(description).multilineTextAlignment(.center)) } } }

7. The RocketLaunch class is used as a parameter for initializing the List view, so it needs to conform to the Identifiable protocol. The class already has a property named id, so all you should do is add an extension to the bottom of ContentView.swift:

   extension RocketLaunch: Identifiable { }

Load the data

To retrieve the data about the rocket launches in the view model, you'll need an instance of the KoinHelper class from the Multiplatform library. It will allow you to call the SDK function with the correct database driver.

1. In the ContentView.swift file, expand the ViewModel class to include a KoinHelper object and the loadLaunches function:

   extension ContentView { // ... @MainActor class ViewModel: ObservableObject { // ... let helper: KoinHelper = KoinHelper() init() { self.loadLaunches(forceReload: false) } func loadLaunches(forceReload: Bool) { // TODO: retrieve data } } }

2. Call the KoinHelper.getLaunches() function (which will proxy the call to the SpaceXSDK class) and save the result in the launches property:

   func loadLaunches(forceReload: Bool) { Task { do { self.launches = .loading let launches = try await helper.getLaunches(forceReload: forceReload) self.launches = .result(launches) } catch { self.launches = .error(error.localizedDescription) } } }

   • When you compile a Kotlin module into an Apple framework, suspending functions can be called using the Swift's async/await mechanism.

   • Since the getLaunches function is marked with the @Throws(Exception::class) annotation in Kotlin, any exceptions that are instances of the Exception class or its subclass will be propagated to Swift as NSError. Therefore, all such exceptions can be caught by the loadLaunches() function.

3. Go to the app's entry point, the iOSApp.swift file, and initialize the Koin module, the view, and the view model:

   import SwiftUI import Shared @main struct iOSApp: App { init() { KoinHelperKt.doInitKoin() } var body: some Scene { WindowGroup { ContentView(viewModel: .init()) } } }

4. In Android Studio, switch to the iosApp configuration, choose an emulator, and run it to see the result: