Install

Description — Installing Couchbase Lite for Dart

Related Content — General Concepts | Supported Platforms

info

Couchbase Lite for Dart supports most platforms, including Android, iOS, macOS, Windows, and Linux. To learn more about supported platforms and supported versions, see Supported platforms.

note

Couchbase Lite for Dart requires Dart SDK ^3.10.0.

Add dependency

Add the cbl package as a dependency:

dart pub add cbl:4.0.0-dev.4

This single package works for both standalone Dart apps and Flutter apps.

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.

info

The Community edition is free and open source. The Enterprise edition is free for development and testing, but requires a license for production use. To learn more about the differences between the Community and Enterprise editions, see Couchbase Lite editions.

Initialize Couchbase Lite

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, enable it explicitly after initialization and before opening a database that uses it:

final status = Extension.enableVectorSearch();
if (status != VectorSearchStatus.enabled) {
  // Handle the case where vector search could not be enabled.
}

See Working with Vector Search for details.

Platform requirements

Make sure that you have set the required minimum target versions in the build systems of the platforms you want to support.

Verify Installation

To verify that Couchbase Lite is installed correctly, add the following code to your app and call it after initializing Couchbase Lite:

import 'package:cbl/cbl.dart';

Future<void> run() 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();
}