couchbase_lite

couchbase_lite plugin

A Flutter plugin for Couchbase Lite Community Edition. An embedded lightweight, noSQL database with live synchronization and offline support on Android and iOS.

The goal of this project is to align this library with the Swift SDK API for Couchbase Lite.

Note: This plugin is still under development, and some APIs might not be available yet. Feedback and Pull Requests are most welcome!

This project forked from Fluttercouch

Getting Started

In your flutter project add the dependency:

dependencies:
  couchbase_lite: ^2.7.1
  
  flutter:
      sdk: flutter

For help getting started with Flutter, view the online documentation

Supported Versions

iOS

Platform	Minimum OS version
iOS	10.0 (9.0 - DEPRECATED)

Android

Platform	Runtime architectures	Minimum API Level
Android	armeabi-v7a	22 (19 - DEPRECATED)
Android	arm64-v8a	22 (21 - DEPRECATED)
Android	x86	22 (19 - DEPRECATED)
Android	x86_64	22

API References

Swift SDK API References

Java SDK API References

Note: Syntax follows the Swift SDK but these are the SDKs used for the platform code.

Local Server Setup

Download and setup Couchbase Server / Sync Gateway Community Editions on your local machine the following link

• Sync Gatway Getting Started
• Couchbase Downloads

Setup beer-sample database Local Couchbase Server:

• Add the beer-sample bucket: Settings > Sample Buckets
• Create a sync_gateway user in the Couchbase Server under Security
• Give sync_gateway access to the beer-sample

Start Sync Gateway:

~/Downloads/couchbase-sync-gateway/bin/sync_gateway ~/path/to/sync-gateway-config.json

Note: Included in this example is sync-gateway-config.json (Login => u: foo, p: bar)

Usage example

Below is an example for the database using the BLoC pattern ( View <-> BLoC <-> Repository <-> Database )

// Initialize the database
try {
  database = await Database.initWithName("gettingStarted");
} on PlatformException {
  return "Error initializing database";
}

// Create a new document (i.e. a record) in the database.
var mutableDoc = MutableDocument()
    .setDouble("version", 2.0)
    .setString("type", "SDK");

// Save it to the database.
try{
  await database.saveDocument(mutableDoc);
} on PlatformException {
  return "Error saving document";
}

// Update a document.
mutableDoc = (await database.document(mutableDoc.id))?.toMutable()?.setString("language", "Dart");

if (mutableDoc != null) {
  // Save it to the database.
  try {
    await database.saveDocument(mutableDoc);

    var document = await database.document(mutableDoc.id);

    // Log the document ID (generated by the database)
    // and properties
    print("Document ID :: ${document.id}");
    print("Learning ${document.getString("language")}");
  } on PlatformException {
    return "Error saving document";
  }
}

// Create a query to fetch documents of type SDK.
var query = QueryBuilder
    .select([SelectResult.all().from("mydocs")])
    .from("gettingStarted", as: "mydocs")
    .where(Expression.property("type").from("mydocs").equalTo(Expression.string("SDK")));

// Run the query.
try {
  var result = await query.execute();
  print("Number of rows :: ${result.allResults().length}");
} on PlatformException {
  return "Error running the query";
}

// Note wss://10.0.2.2:4984/my-database is for the android simulator on your local machine's couchbase database
// Create replicators to push and pull changes to and from the cloud.
ReplicatorConfiguration config =
ReplicatorConfiguration(database, "ws://10.0.2.2:4984/beer-sample");
config.replicatorType = ReplicatorType.pushAndPull;
config.continuous = true;

// Add authentication.
config.authenticator = BasicAuthenticator("foo", "bar");

// Create replicator (make sure to add an instance or static variable named replicator)
var replicator = Replicator(config);

// Listen to replicator change events.
_listenerToken = replicator.addChangeListener((ReplicatorChange event) {
  if (event.status.error != null) {
    print("Error: " + event.status.error);
  }

  print(event.status.activity.toString());
});

// Start replication.
await replicator.start();

For this getting started guide, you will need to allow using ws protocol.

As of Android Pie, version 9, API 28, cleartext support is disabled, by default. Although wss: protocol URLs are not affected, in order to use the ws: protocol, applications must target API 27 or lower, or must configure application network security as described here.

<application android:usesCleartextTraffic="true">
</application>

App Transport Security is enabled by default since iOS 9 and enforces applications to use HTTPS exclusively. For this getting started guide, you will disable it but we recommend to enable it in production (and enable HTTPS on Sync Gateway). In the Xcode navigator, right-click on Info.plist and open it as a source file.

Append the following inside of the XML tags to disable ATS.

<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key><true/>
</dict>