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.

If you want to use Couchbase Lite in a standalone Dart app, such as a CLI or server, jump to Standalone Dart.

Flutter

1. Run the following command to add the cbl and cbl_flutter packages as dependencies:

   flutter pub add cbl cbl_flutter

2. Choose between the Community and Enterprise edition.

   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.

   To use the Community edition, run the following command to add the cbl_flutter_ce package as a dependency:

   flutter pub add cbl_flutter_ce

   To use the Enterprise edition, run the following command to add the cbl_flutter_ee package as a dependency

   flutter pub add cbl_flutter_ee

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

4. Initialize Couchbase Lite before using it:

   import 'package:cbl_flutter/cbl_flutter.dart';
   
   Future<void> main() async {
     await CouchbaseLiteFlutter.init();
     runApp(MyApp());
   }

Unit Tests

You can use Couchbase Lite in Flutter unit tests but you need to use cbl_dart in them. In integration tests, cbl_flutter works just fine.

1. Add cbl_dart as a development dependency.

   flutter pub add --dev cbl_dart

2. In your unit tests initialize Couchbase Lite through CouchbaseLiteDart.init instead of CouchbaseLiteFlutter.init:

   import 'dart:io';
   
   import 'package:cbl/cbl.dart';
   import 'package:cbl_dart/cbl_dart.dart';
   import 'package:flutter_test/flutter_test.dart';
   
   void setupCouchbaseLiteForUnitTests() {
     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.enterprise,
         filesDir: tempFilesDir.path,
       );
     });
   }
   
   void main() {
     setupCouchbaseLiteForUnitTests();
   
     test('use a database', () async {
       final db = await Database.openAsync('test');
       // ...
     });
   }

Standalone Dart

1. Run the following command to add the cbl and cbl_dart packages as dependencies:

   flutter pub add cbl cbl_dart

2. Initialize Couchbase Lite before using it:

   import 'package:cbl_dart/cbl_dart.dart';
   
   Future<void> main() async {
     await CouchbaseLiteDart.init(edition: Edition.enterprise);
     // Start using Couchbase Lite ...
   }

   As part of initializing Couchbase Lite you need to select an edition.

   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.

   note

   CouchbaseLiteDart.init downloads the needed native libraries if they have not already been cached.

Verify Installation

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

import 'package:cbl/cbl.dart';

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