Skip to content

Latest commit

 

History

History
181 lines (142 loc) · 8.59 KB

README.md

File metadata and controls

181 lines (142 loc) · 8.59 KB
Raw

Maven Central Kotlin GitHub License Couchbase Community Slack Channel

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, and full-text 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 available APIs in 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.1.9-1.1.1")
            // or Enterprise Edition
            implementation("dev.kotbase:couchbase-lite-ee:3.1.9-1.1.1")
        }
    }
}

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 kotlinx-datetime'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.

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, observing change Flows, and creating indexes.

Installation

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

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.1.9-1.1.1")
// or Enterprise Edition
implementation("dev.kotbase:couchbase-lite-ee-kermit:3.1.9-1.1.1")

Kotbase Paging

The paging extensions are built on Cash App's Multiplatform Paging, Google's AndroidX Paging with multiplatform support. 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.1.9-1.1.1")
// or Enterprise Edition
implementation("dev.kotbase:couchbase-lite-ee-paging:3.1.9-1.1.1")

Roadmap

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.