couchbase_lite_dart 0.2.0

Dart native
Flutter Android iOS

Dart implementation of Couchbase Lite is an embedded, NoSQL JSON Document Style database.

Introduction #


A full-featured embedded NoSQL database that runs locally on mobile devices

This is a Dart port of the Couchbase Lite database, built on top of the Couchbase Lite C library (CBL_C) using dart.ffi.

Warning: This project is still in early development stage and breaking API changes might still happen! Help with testing, documentation and development is welcome. Here's how you can contribute

Feature checklist #

  • Database A Database is both a filesystem object and a container for documents.
    • [x] Open, Close, Copy, Compact, Delete
    • [x] Batch operations, similar to a transaction
    • [x] Change notifications, document change notifications
    • [x] Buffered notifications
  • Document A Document is essentially a JSON object with an ID string that's unique in its database.
    • [x] CRUD - Create, Read, Udpdate, Delete
    • [x] Save conflict handler
    • [x] Document expiration, with automatic purge
    • [x] Fleece API for direct access to the binary data
  • Queries
    • [x] Query language based on the N1QL language from Couchbase Server, which you can think of as "SQL for JSON" or "SQL++".
    • [x] Query parameters
    • [x] Explain
    • [x] Change listener - turns a query into "live query"
    • [x] Indexes: value index or Full-text Search (FTS)
  • Replication A replicator is a background task that synchronizes changes between a local database and another database on a remote server
    • [x] Authentication: Basic and Session based
    • [x] Pull/push filters
    • [x] Status listeners
    • [ ] Replicated document listeners
    • [ ] Conflict-resolution callbacks
  • Blobs
    • [x] Create, read through content based API
    • [ ] Stream based API

Platform support #

  • Windows: Bundled with the package. Beta status.
  • Android: Experimental, in testing phase. Currently the libraries are not bundled with the package. Contact me, if you would like to test it.
  • iOS, macOS: N/A

Examples and how to use #

Important in your main.dart call to initialize Windows specific bindings.



/// Create/open a databse
var db = Database('name', directory: 'path/to directory');

// Documents
var doc = Document("docid", data: {'name': 'John Doe'});

// Read immutable document
doc1 = db.getDocument('docid'); = {'foo': 'bar'}; //<- throws a DatabaseException

// Get a mutable copy
var mutDoc = doc1.mutableCopy; = {'foo': 'bar'}; // <- OK>

// or retrieve
var doc2 = db.getMutableDocument('testdoc3'); = {'foo': 'bar8'};

// Query

// Compile a query
final q = Query(db, 'SELECT * WHERE foo=\$VALUE');

q.setParameters = {'VALUE': 'bar'};

// Optionally Turn it into a "live query"
q.addChangeListener((List results) {
    print('New query results: ');

// Execute the query
var results = q.execute();

// Replicator

// Create a replicator
var replicator = Replicator(
    endpointUrl: 'ws://localhost:4984/remoteDB/',
    username: 'testuser',
    password: 'password', // or
    // 'sessionId': 'dfhfsdyf8dfenfajfoadnf83c4dfhdfad3228yrsefd',

// Set up a status listener
replicator.addChangeListener((status) {
    print('Replicator status: ' + status.activityLevel.toString());

// Start the replicator

See the example folder for a more complete example, including the Fleece API.

Contributing #

There are couple of ways in which you can contribute:

  • Testing - current status is: it runs on my computer
  • Help with building the dynamic libraries for Android/iOS. I have the C library source code and some custom wrapper code to make it work with Dart's ffi. Currently I have only managed to build it for Windows. In particular iOS/macOS is welcome.
  • Fixing bugs
  • Improve documentation
  • Write examples

Resources #

  • Couchbase Lite mobile CBL
  • Couchbase Lite C CBL_C
  • N1QL N1QL
pub points


Dart implementation of Couchbase Lite is an embedded, NoSQL JSON Document Style database.

Repository (GitHub)
View/report issues


API reference




ffi, meta, path, uuid


Packages that depend on couchbase_lite_dart