Kotbase

Kotlin Multiplatform library for Couchbase Lite

Introduction

Kotbase pairs Kotlin Multiplatform with Couchbase Lite, an embedded NoSQL JSON document database. Couchbase Lite can be used as a standalone client database, or paired with Couchbase Server and Sync Gateway or Capella App Services for cloud to edge data synchronization. Features include:

• SQL++, key/value, full-text search, and vector search queries
• Observable queries, documents, databases, and replicators
• Binary document attachments (blobs)
• Peer-to-peer and cloud-to-edge data sync

Kotbase provides full Enterprise and Community Edition API support for Android and JVM (via Java SDK), native iOS and macOS (via Objective-C SDK), and experimental support for native Linux and Windows (via C SDK).

Installation

Add either the Community or Enterprise Edition dependency in the commonMain source set dependencies of your shared module's build.gradle.kts:

kotlin {
    sourceSets {
        commonMain.dependencies {
            // Community Edition
            implementation("dev.kotbase:couchbase-lite:3.2.4-1.2.0")
            // or Enterprise Edition
            implementation("dev.kotbase:couchbase-lite-ee:3.2.4-1.2.0")
        }
    }
}

Note The Couchbase Lite Community Edition is free and open source. The Enterprise Edition is free for development and testing, but requires a license from Couchbase for production use. See Community vs Enterprise Edition.

Kotbase is published to Maven Central. The Couchbase Lite Enterprise Edition dependency additionally requires the Couchbase Maven repository.

repositories {
    mavenCentral()
    maven("https://mobile.maven.couchbase.com/maven2/dev/")
}

Native Platforms

Native platform targets should additionally link to the Couchbase Lite dependency native binary. See Supported Platforms for more details.

Linux

Targeting JVM running on Linux or native Linux, both require a specific version of the libicu dependency. (You will see an error such as libLiteCore.so: libicuuc.so.71: cannot open shared object file: No such file or directory indicating the expected version.) If the required version isn't available from your distribution's package manager, you can download it from GitHub.

Documentation

Kotbase documentation can be found at kotbase.dev, including getting started examples, usage guide, and API reference.

Differences from Java SDK

Kotbase's API aligns with the Couchbase Lite Java and Android KTX SDKs. Migrating existing Kotlin code can be as straightforward as changing the import package from com.couchbase.lite to kotbase, with some exceptions:

• Java callback functional interfaces are implemented as Kotlin function types.
• File, URL, and URI APIs are represented as strings.
• Date APIs use Kotlin's Instant.
• InputStream APIs use kotlinx-io's Source.
• Executor APIs use Kotlin's CoroutineContext.
• Certificate APIs are available as raw ByteArrays or in platform-specific code.
• There's no need to explicitly call CouchbaseLite.init(). Initialization functions can still be called with custom parameters in JVM and Android platform code.
• Efforts have been made to detect and throw Kotlin exceptions for common error conditions, but NSError may still leak through on Apple platforms. Please report any occurrences that may deserve addressing.
• Some deprecated APIs are omitted.
• While not available in the Java SDK, as Java doesn't support operator overloading, Fragment subscript APIs are available in Kotbase, similar to Swift, Objective-C, and .NET.
• Configuration factory APIs from the Android KTX SDK have been deprecated in favor of using constructors directly, which support Kotlin named arguments themselves.

Extension Libraries

Kotbase includes some convenient extensions on top of Couchbase Lite's official API as additional library artifacts.

Kotbase KTX

The KTX extensions include the excellent Kotlin extensions by MOLO17, as well as other convenience functions for composing queries, mapping query results, creating documents, and observing change Flows.

Installation

// Community Edition
implementation("dev.kotbase:couchbase-lite-ktx:3.2.4-1.2.0")
// or Enterprise Edition
implementation("dev.kotbase:couchbase-lite-ee-ktx:3.2.4-1.2.0")

Kotbase Kermit

Kotbase Kermit is a Couchbase Lite custom logger which logs to Kermit. Kermit can direct its logs to any number of log outputs, including the console.

Installation

// Community Edition
implementation("dev.kotbase:couchbase-lite-kermit:3.2.4-1.2.0")
// or Enterprise Edition
implementation("dev.kotbase:couchbase-lite-ee-kermit:3.2.4-1.2.0")

Kotbase Paging

The paging extensions are built on Google's AndroidX Paging. Kotbase Paging provides a PagingSource which performs limit/offset paging queries based on a user-supplied database query.

Installation

// Community Edition
implementation("dev.kotbase:couchbase-lite-paging:3.2.4-1.2.0")
// or Enterprise Edition
implementation("dev.kotbase:couchbase-lite-ee-paging:3.2.4-1.2.0")

Roadmap

• Documentation website (kotbase.dev)
• NSInputStream interoperability (Okio #1123) (kotlinx-io #174)
• Linux ARM64 support
• Public release
• Sample apps
  • Getting Started
  • Getting Started Compose Multiplatform
  • Kotbase Notes
  • SwiftUI for Kotbase Notes
• Couchbase Lite 3.1 API - Scopes and Collections
• Versioned docs
• Couchbase Lite 3.2 API - Vector Search
• Couchbase Lite 3.3 API - Multipeer Replicator
• Couchbase Lite 4.0 API - Version Vectors
• URLEndpointListener on Linux & MinGW platforms
• Improve Swift API alignment with Couchbase Lite using Swift export, @ObjCName, and/or @ShouldRefineInSwift
• Async coroutines API

Development

• When building the project on Linux, be sure to install the libicu dependency.
• When checking out the git repo on Windows, enable developer mode and symbolic links in git with git config --global core.symlinks true.