cbl 4.0.0-dev.0

Couchbase Lite is an embedded, NoSQL JSON Document Style database, supporting Blobs, Encryption, SQL++ 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 - SQL++ (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.
• Peer-to-Peer Sync - Sync directly between devices without a server. Enterprise Edition
• Vector Search - Perform similarity searches using vector embeddings. Enterprise Edition

---

❤️ 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.

Proudly sponsored by

---

This is the single package for Couchbase Lite in Dart. It works for both standalone Dart apps and Flutter apps - no additional platform packages are needed. Native libraries are downloaded and compiled automatically via Dart native assets.

For the full documentation, go to cbl-dart.dev.

Important

Upgrading from v3? See the migration guide for upgrading to v4.

Getting started

Install

Add the package as a dependency:

dart pub add cbl

Configure edition (optional)

By default, the Community edition is used. To use the Enterprise edition, configure it in your package pubspec.yaml:

hooks:
  user_defines:
    cbl:
      edition: enterprise

Note

If you are using a Dart pub workspace, hooks.user_defines are read from the workspace root pubspec.yaml, so put this configuration there instead.

Initialize

Initialize Couchbase Lite before using it:

import 'package:cbl/cbl.dart';

Future<void> main() async {
  await CouchbaseLite.init();
  // Start using Couchbase Lite ...
}

If you enabled vector search in pubspec.yaml, call Extension.enableVectorSearch() after initialization and before opening a database that uses vector search.

Example

import 'package:cbl/cbl.dart';

Future<void> main() async {
  await CouchbaseLite.init();

  // Open the database (creating it if it doesn't exist).
  final database = await Database.openAsync('database');

  // Create a collection, or return it if it already exists.
  final collection = await database.createCollection('components');

  // Create a new document.
  final mutableDocument = MutableDocument({'type': 'SDK', 'majorVersion': 2});
  await collection.saveDocument(mutableDocument);

  print(
    'Created document with id ${mutableDocument.id} and '
    'type ${mutableDocument.string('type')}.',
  );

  // Update the document.
  mutableDocument.setString('Dart', key: 'language');
  await collection.saveDocument(mutableDocument);

  print(
    'Updated document with id ${mutableDocument.id}, '
    'adding language ${mutableDocument.string("language")!}.',
  );

  // Read the document.
  final document = (await collection.document(mutableDocument.id))!;

  print(
    'Read document with id ${document.id}, '
    'type ${document.string('type')} and '
    'language ${document.string('language')}.',
  );

  // Create a query to fetch documents of type SDK.
  print('Querying Documents of type=SDK.');
  final query = await database.createQuery('''
    SELECT * FROM components
    WHERE type = 'SDK'
  ''');

  // Run the query.
  final result = await query.execute();
  final results = await result.allResults();
  print('Number of results: ${results.length}');

  // Close the database.
  await database.close();
}

Integrations

• cbl_sentry -- Sentry integration for error reporting and performance tracing.

🤝 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Read CONTRIBUTING to get started developing.

Prior work

Thanks to the authors of earlier Couchbase Lite packages. Those packages where valuable references for making decisions about how to approach this project.

• Luca Christille - fluttercouch
• Bryan Welter - couchbase_lite
• Rudolf Martincsek - couchbase_lite_dart

⚖️ Disclaimer

⚠️ This is not an official Couchbase product.