mobile-android

name	mobile-android
summary	Couchbase Lite for Android — installation (Kotlin/Java, Gradle), database and collection setup, CRUD operations, local SQL++ queries with QueryBuilder and SQL++ string API, live queries, full-text search, blob storage, database encryption, replication to Sync Gateway or Capella App Services
description	Couchbase Lite for Android — installation (Kotlin/Java, Gradle), database and collection setup, CRUD operations, local SQL++ queries with QueryBuilder and SQL++ string API, live queries, full-text search, blob storage, database encryption, replication to Sync Gateway or Capella App Services
compatibility	Couchbase Lite 4.x for Android. Kotlin and Java. Minimum Android API level 24 (Android 7.0).
metadata	{"last_verified":"2026-05","handoff":[{"condition":"user asks about sync or replication setup","skill":"mobile-sync-android"},{"condition":"user asks about conflict resolution","skill":"mobile-conflict-resolution-android"},{"condition":"user is building for iOS/Swift","skill":"mobile-ios"},{"condition":"user asks about on-device vector or semantic search","skill":"mobile-vector-search-android"},{"condition":"user asks about device-to-device or P2P sync","skill":"mobile-p2p-sync-android"},{"condition":"user asks about logging or debugging","skill":"mobile-logging-android"},{"condition":"user asks about testing or unit tests","skill":"mobile-testing-android"}]}

Couchbase Lite — Android

Platform-agnostic concepts (document model, CRUD semantics, live queries, blobs, replication, editions): shared/mobile/cbl-core.md

Couchbase Lite is an embedded JSON document database for Android. It works fully offline and syncs to Couchbase Server via Sync Gateway or Capella App Services.

Installation

Kotlin (build.gradle — app level)

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

dependencies {
    // Community Edition
    implementation 'com.couchbase.lite:couchbase-lite-android-ktx:4.0.3'
    // Enterprise Edition (encryption, vector search)
    // implementation 'com.couchbase.lite:couchbase-lite-android-ee-ktx:4.0.3'
}

Java (build.gradle — app level)

dependencies {
    implementation 'com.couchbase.lite:couchbase-lite-android:4.0.3'
    // Enterprise: 'com.couchbase.lite:couchbase-lite-android-ee:4.0.3'
}

Initialization

Call once in Application.onCreate():

// Kotlin
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        CouchbaseLite.init(this)
    }
}

// Java
public class MyApp extends Application {
    @Override public void onCreate() {
        super.onCreate();
        CouchbaseLite.init(this);
    }
}

Open a database

// Kotlin — opens or creates "myapp.cblite2" in the default directory
val database = Database("myapp")

// Custom directory
val config = DatabaseConfigurationFactory.newConfig(
    directory = context.filesDir.absolutePath
)
val database = Database("myapp", config)

// Java
Database database = new Database("myapp");

Collections

// Default collection (equivalent to _default._default)
val collection = database.defaultCollection

// Named collection in default scope
val collection = database.createCollection("users")

// Named collection in named scope
val collection = database.createCollection("orders", "commerce")

// Get existing (returns null if not found)
val collection = database.getCollection("users") ?: error("not found")

CRUD

// Create
val doc = MutableDocument()
    .setString("type", "user")
    .setString("name", "Alice")
    .setInt("age", 30)
    .setBoolean("active", true)
collection.save(doc)
val docId = doc.id  // auto-generated UUID

// Create with explicit ID
val doc = MutableDocument("user::alice")
    .setString("name", "Alice")
collection.save(doc)

// Read
val doc = collection.getDocument("user::alice")
    ?: throw IllegalStateException("not found")
val name = doc.getString("name")
val age  = doc.getInt("age")

// Update — always work from a retrieved document to preserve CAS
val mutable = collection.getDocument("user::alice")!!.toMutable()
mutable.setInt("age", 31)
collection.save(mutable)

// Delete
val doc = collection.getDocument("user::alice")!!
collection.delete(doc)

SQL++ Queries

QueryBuilder API

val query = QueryBuilder
    .select(
        SelectResult.property("name"),
        SelectResult.property("age"),
        SelectResult.expression(Meta.id)
    )
    .from(DataSource.collection(collection))
    .where(
        Expression.property("type").equalTo(Expression.string("user"))
            .and(Expression.property("age").greaterThan(Expression.intValue(18)))
    )
    .orderBy(Ordering.property("name").ascending())
    .limit(Expression.intValue(20))

query.execute().use { rs ->
    for (result in rs) {
        val name = result.getString("name")
        val id   = result.getString("id")
        println("$id: $name")
    }
}

SQL++ string API

val query = database.createQuery(
    "SELECT META().id, name, age FROM _ WHERE type = 'user' AND age > 18 ORDER BY name LIMIT 20"
)
// _ refers to the default collection; use collection name for named collections:
// "SELECT * FROM users WHERE type = 'user'"

query.execute().use { rs ->
    rs.allResults().forEach { result ->
        println(result.toMap())
    }
}

Live Queries

Live queries re-run automatically when underlying data changes:

val query = QueryBuilder
    .select(SelectResult.all())
    .from(DataSource.collection(collection))
    .where(Expression.property("type").equalTo(Expression.string("user")))

val token = query.addChangeListener { change ->
    change.error?.let { throw it }
    val results = change.results?.allResults() ?: return@addChangeListener
    // Update UI with results
    updateUserList(results)
}

// Stop listening
token.remove()

Indexes

// Value index — speeds up WHERE and ORDER BY
collection.createIndex(
    "idx_type_name",
    IndexBuilder.valueIndex(
        ValueIndexItem.property("type"),
        ValueIndexItem.property("name")
    )
)

// Full-text index
collection.createIndex(
    "idx_fts_bio",
    IndexBuilder.fullTextIndex(FullTextIndexItem.property("bio"))
        .ignoreAccents(false)
)

Full-Text Search

val query = QueryBuilder
    .select(SelectResult.expression(Meta.id), SelectResult.property("name"))
    .from(DataSource.collection(collection))
    .where(FullTextFunction.match(Expression.fullTextIndex("idx_fts_bio"), "engineer"))
    .limit(Expression.intValue(10))

Blobs

// Store a blob (e.g. profile photo)
val bytes = File("photo.jpg").readBytes()
val blob  = Blob("image/jpeg", bytes)

val doc = MutableDocument("user::alice")
    .setString("name", "Alice")
    .setBlob("photo", blob)
collection.save(doc)

// Read blob
val savedDoc = collection.getDocument("user::alice")!!
val photo    = savedDoc.getBlob("photo")
val content  = photo?.content  // ByteArray

Database encryption (Enterprise only)

val key    = DatabaseEncryptionKey("my-secret-passphrase")
val config = DatabaseConfigurationFactory.newConfig(encryptionKey = key)
val db     = Database("secure", config)

Replication

Replication setup, channel filtering, offline-first patterns, and Sync Function configuration are covered in mobile-sync-android. Load that skill for any replication question.

The Replicator class syncs one or more collections to Sync Gateway or Capella App Services. Credentials must be read from Android Keystore at runtime — see shared/mobile/cbl-core.md for the credential storage pattern and mobile-sync-android for full setup examples.

Coroutine / Flow integration (Kotlin)

import com.couchbase.lite.replicatorChangesFlow

// Collect replicator changes as a Flow
replicator.replicatorChangesFlow()
    .onEach { change -> println(change.status.activityLevel) }
    .launchIn(lifecycleScope)

// Query changes as Flow
query.queryChangeFlow()
    .map { change -> change.results?.allResults() ?: emptyList() }
    .onEach { results -> updateUI(results) }
    .launchIn(lifecycleScope)