cbl_flutter 1.0.0+3

Flutter Plugin for Couchbase Lite, an embedded, NoSQL JSON Document Style database, supporting Blobs, Encryption, N1QL Queries, Live Queries, Full-Text Search and Data Sync.

Couchbase Lite is an embedded, NoSQL database:

• Multi-Platform - Android, iOS, macOS, Windows, Linux
• Standalone Dart and Flutter - No manual setup required, just add the package.
• Fast and Compact - Uses efficient persisted data structures.

It is fully featured:

• JSON Style Documents - No explicit schema and supports deep nesting.
• Expressive Queries - N1QL (SQL for JSON), QueryBuilder, Full-Text Search
• Observable - Get notified of changes in database, queries and data sync.
• Data Sync - Pull and push data from/to server with full control over synced data.

---

❤️ If you find this package useful, please ⭐ us on pub.dev and GitHub. 🙏

🐛 & ✨ Did you find a bug or have a feature request? Please open a GitHub issue.

👋 Do you you have a question or feedback? Let us know in a GitHub discussion.

---

What are all these packages for?

Couchbase Lite can be used with standalone Dart or with Flutter apps and comes in two editions: Community and Enterprise.

Regardless of the app platform and edition of Couchbase Lite you use, you always need the cbl package. All of the APIs of Couchbase Lite live in this package.

What other packages you need depends on the app platform and the edition of Couchbase Lite you use.

Package	Required when you want to:	Pub	Likes	Points	Popularity
cbl	use Couchbase Lite.
cbl_dart	use the Community or Enterprise Edition in a standalone Dart app or in Flutter unit tests.
cbl_flutter	use Couchbase Lite in a Flutter app.
cbl_flutter_ce	use the Community Edition in a Flutter app.
cbl_flutter_ee	use the Enterprise Edition in a Flutter app.
cbl_sentry	integrate Couchbase Lite with Sentry in a Dart or Flutter app.
cbl_generator	generated Dart code to access data trough a typed data model.

🎯 Platform Support

Platform	Version
iOS	>= 10.0
macOS	>= 10.14
Android	>= 22
Linux *	== Ubuntu 20.04-x86_64
Windows	>= 10

*: 🐛 Currently broken because of a bug in Flutter. Most notably, operations trying to return an error crash the app.

🔌 Getting started

1. Add cbl and cbl_flutter as dependencies:

   dependencies:
     cbl: ...
     cbl_flutter: ...
   

2. Select the edition of Couchbase Lite you want to use, by adding as a dependency either cbl_flutter_ce for the Community Edition or cbl_flutter_ee for the Enterprise Edition:

   # This dependency selects the Couchbase Lite Community Edition.
   cbl_flutter_ce: ...
   

   ⚖️ You need to comply with the Couchbase licensing terms of the edition of Couchbase Lite you select.

3. Make sure you have set the required minimum target version in the build systems of the platforms you support.

4. Initialize Couchbase Lite before using it:

   import 'dart:io';
   
   import 'package:cbl_flutter/cbl_flutter.dart';
   import 'package:cbl_flutter_ce/cbl_flutter_ce.dart';
   
   Future<void> initCouchbaseLite() async {
     await CouchbaseLiteFlutter.init();
   }
   

Default database directory

When opening a database without specifying a directory, path_provider's getApplicationSupportDirectory is used to resolve it. See that function's documentation for the concrete locations on the various platforms.

🧪 Flutter unit tests

Flutter unit tests are executed by a headless version of Flutter, on the development host.

You can use the cbl package in your unit tests, but you need to use cbl_dart to initialize Couchbase Lite, instead of cbl_flutter:

import 'dart:io';

import 'package:cbl/cbl.dart';
import 'package:cbl_dart/cbl_dart.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  setUpAll(() async {
    // If no `filesDir` is specified when initializing CouchbaseLiteDart, the
    // working directory is used as the default database directory.
    // By specifying a `filesDir` here, we can ensure that the tests don't
    // create databases in the project directory.
    final tempFilesDir = await Directory.systemTemp.createTemp();
    await CouchbaseLiteDart.init(edition: Edition.community, filesDir: tempFilesDir.path);
  });

  test('use a database', () async {
    final db = await Database.openAsync('test');
    await db.saveDocument(MutableDocument({'message': 'Hello, World!'}));
    await db.close();
  });
}

Unit tests are the best way to learn, experiment and validate ideas, since they launch much quicker than integration tests. Be aware though, that using Couchbase Lite like this cannot replace integration testing your database code on actual devices or even simulators.

These tests can validate that you're using Couchbase Lite correctly and the code works as expected generally, but subtle differences between platforms, operating system versions and devices can still crop up.

💡 Where to go next

• Check out the example app in the Example tab.
• Look at the usage examples for cbl.

⚖️ Disclaimer

⚠️ This is not an official Couchbase product.