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, the API is still fluid and breaking changes might still happen! Help with testing, documentation and development is welcome. Here's how you can contribute
- Database
A Database is both a filesystem object and a container for documents.
- Open, Close, Copy, Compact, Delete
- Batch operations, similar to a transaction
- Change notifications, document change notifications
- Buffered notifications
- Document
A Document is essentially a JSON object with an ID string that's unique in its database.
- CRUD - Create, Read, Udpdate, Delete
- Save conflict handler
- Document expiration, with automatic purge
- Fleece API for direct access to the binary data
- Queries
- Query language based on the N1QL language from Couchbase Server, which you can think of as "SQL for JSON" or "SQL++".
- Query parameters
- Explain
- Change listener - turns a query into "live query"
- 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
- Authentication: Basic and Session based
- Pull/push filters
- Status listeners
- Replicated document listeners
- Conflict-resolution callbacks (See issue #86)
- Blobs
- Create, read through content based API
- Stream based API
-
Windows: Bundled with the package. Beta status.
-
Android: Some assembly is required. You can either
-
build the shared libraries yourself from the repository: https://github.com/Rudiksz/couchbase-lite-C.git using the
feature/dart
branch or the tag with the matching version -
download the prebuilt libraries from BUILDS
Once you have the shared libraries place them in your project's
\android\app\src\main\jniLibs\
folder -
-
iOS, macOS: N/A
Important in your main.dart call to initialize Dart<->C callbacks.
Cbl.init();
then
/// Create/open a databse
var db = Database('name', directory: 'path/to directory');
// Documents
var doc = Document("docid", data: {'name': 'John Doe'});
db.saveDocument(doc);
// Read immutable document
doc1 = db.getDocument('docid');
doc1.properties = {'foo': 'bar'}; //<- throws a DatabaseException
// Get a mutable copy
var mutDoc = doc1.mutableCopy;
mutDoc.jsonProperties = {'foo': 'bar'}; // <- OK>
db.saveDocument(mutDoc);
// or retrieve
var doc2 = db.getMutableDocument('testdoc3');
doc2.jsonProperties = {'foo': 'bar8'};
db.saveDocument(doc2);
// 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((ResultSet results) {
print('New query results: ');
while(results.next()){
final row = results.rowDict;
print(row.json);
}
});
// Execute the query
var results = q.execute();
// Replicator
// Create a replicator
var replicator = Replicator(
db,
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
replicator.start();
See the example folder for a more complete example, including the Fleece API.
Current milestones for versioning are:
- 0.5.0 - consolidate and document the core API for idiomatic Dart. Breaking changes after that should be deprecated first, if possible.
- 1.0.0
- Align the API to the official SDK's as much as possible and where it makes sense.
- Implement solid memory management to eliminate memory leaks - a mix of automatic and manual disposal of objects
- make the library "production ready"
- Documentation beyond what dart docs has: best practices, tips, caveats, N1SQL features, extensive examples
- post 1.0.0
- JSONQuery language support for queries, with a QueryBuilder API like the official SDK has
There are couple of ways in which you can contribute:
- Testing
- Adding/testing iOS/macOs. I have the C library source code and some custom wrapper code to make it work with Dart's ffi.
- Fixing bugs
- Improve documentation
- Write examples