{"id":13820799,"url":"https://github.com/fluttercouch/fluttercouch","last_synced_at":"2026-02-19T09:33:50.040Z","repository":{"id":56830586,"uuid":"132781963","full_name":"fluttercouch/fluttercouch","owner":"fluttercouch","description":"With Fluttercouch is possible to use Couchbase Mobile Native SDK in Flutter Projects.","archived":false,"fork":false,"pushed_at":"2020-09-21T22:02:29.000Z","size":28800,"stargazers_count":106,"open_issues_count":18,"forks_count":28,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-08-05T08:09:19.803Z","etag":null,"topics":["android","couchbase-database","couchbase-lite-database","dart","flutter","ios"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fluttercouch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-09T16:06:55.000Z","updated_at":"2023-07-20T16:51:10.000Z","dependencies_parsed_at":"2022-09-02T03:51:35.793Z","dependency_job_id":null,"html_url":"https://github.com/fluttercouch/fluttercouch","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttercouch%2Ffluttercouch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttercouch%2Ffluttercouch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttercouch%2Ffluttercouch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttercouch%2Ffluttercouch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fluttercouch","download_url":"https://codeload.github.com/fluttercouch/fluttercouch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225423717,"owners_count":17472177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","couchbase-database","couchbase-lite-database","dart","flutter","ios"],"created_at":"2024-08-04T08:01:09.258Z","updated_at":"2025-10-22T23:31:43.820Z","avatar_url":"https://github.com/fluttercouch.png","language":"Dart","funding_links":[],"categories":["Dart"],"sub_categories":[],"readme":"[![Pub](https://img.shields.io/pub/v/fluttercouch.svg)](https://pub.dev/packages/fluttercouch)\n[![Gitter](https://badges.gitter.im/fluttercouch/Lobby.svg)](https://gitter.im/fluttercouch/Lobby)\n\n# Fluttercouch\nWith Fluttercouch is possible to use Couchbase Mobile Native SDK in Flutter Projects.\n\nThe plugin takes advantage of Flutter ability to write platform specific code to instantiate and manage a Couchbase Lite database. The Fluttercouch library is a wrapper to native SDK, which is handled from Dart through “mockup” objects. Those objects are responsible for creating local database, making CRUD operation and interact with a Couchbase database through platform channels.\n\nNone of the Dart object holds the actual state (which is hold in the native code). They are an interface to operate the native SDK in an easy and workable manner, helping developers to not deal with native layer directly.\n\n## Installation\n\nIn order to use Fluttercouch, add this code to pubspec.yaml in your project directory.\n```dart\ndependencies:\n  fluttercouch: ^0.5.0\n```\n\nNOTES:\n- The current version uses the Couchbase Lite SDK 2.1 for Android and iOs.\n- Due to Couchbase Lite SDK restrictions, the minSdkVersion for Android is 19 (Android KitKat 4.4) and minimum platform for iOs is 9.0\n\n## Code Reference\n\n### Initialization\nThe package is designed as a mix-in for a model class. After importing the main file in your code and extending a class with Fluttercouch mix-in, you can use the package. Remember that you can use the same code for Android and iOs development because Fluttercouch handles automatically the native code for the two different platforms for you.\n```dart\nimport ‘package:fluttercouch/fluttercouch.dart’;\n\nclass MyModel extends Object with Fluttercouch {\n}\n```\nDefine an async method to initialize a Couchbase Lite database and wrap the initialization code within a try / catch block to watch for PlatformException error. The initDatabaseWithName() method returns a string with the name of the database, but saving its result is optional. Infact Fluttercouch consider the last initialized database as the default database, and further commands refers to that database. Unfortunately, handling multiple databases is not fully supported at the moment.\n```dart\ninitFluttercouch() async {\n  try {\n  await initDatabaseWithName(‘myDatabaseName’);\n  } on PlatformException {\n    // Handle error during database initialization\n  }\n}\n```\nIf the database already exists in a device, nothing is done (except for changing default database reference). Hence you can safely init a database many times in different sections of your code or among various launch of your application.\nThe database is now available in any part of your class mixed with Fluttercouch.\n\n### Replication Configuration\nYou can configure a replicator with the following methods:\n```dart\n// Supplies the address of the database replicated by the Sync Gateway server. \n// In case you want to enable SSL encryption, use wss:// insted of ws://. \n// To connect to a local Sync Gateway instance, use localhost as hostname for iOs simulator, and 10.0.2.2 for Android simulator.\nsetReplicatorEndpoint(\"ws://your-server-address:4984/yourReplicationDatabaseName\");\n\n// Sets the replication type as PULL, PUSH or PUSH_AND_PULL\nsetReplicatorType(\"PUSH_AND_PULL\");\n\n// Sets the replication as continuous\nsetReplicatorContinuous(true);\n\n// Sets a BasicAuthenticator for the replication. The methods accept a parameter of type Map\u003cString, String\u003e \n// with two keys named \"username\" and \"password\".\nsetReplicatorBasicAuthentication(\u003cString, String\u003e{\n  \"username\": \"yourUsername\",\n  \"password\": \"yourPassword\"\n});\n\n// Sets a SessionAuthenticator for the replication. SessionID is retrieved querying the public REST API of your Sync Gateway\nsetReplicatorSessionAuthentication(sessionID);\n\n// Before starting the replication, you must init the replicator object\ninitReplicator();\n\n// Starts the replication\nstartReplicator();\n\n// Stops the replication\nstopReplicator();\n```\n\nYou can listen for replication events passing a function to the listenReplicatorEvents method. The listenReplicatorEvents calls the function with a parameter containing the event type.\n\n__NOTE__: The replicator must have been initialized with `initReplicator()` before trying to register any replication listener.\n```dart\nlistenReplicationEvents((dynamic event) {\n    switch(event) {\n      case (\"BUSY\"):\n        // executed when the replicator status changes to BUSY\n      case (\"IDLE\"):\n        // executed when the replicator status changes to IDLE\n      case (\"OFFLINE\"):\n        // executed when the replicator status changes to OFFLINE\n      case (\"STOPPED\"):\n        // executed when the replicator status changes to STOPPED\n      case (\"CONNECTING\"):\n        // executed when the replicator status changes to CONNECTING\n    }\n  }\n);\n```\n\n### Basic CRUD operations\nAs in Couchbase Lite native implementations, documents are managed through Document and MutableDocument objects.\nTo retrieve a document by ID, you wait for the the result of the getDocumentWithId method.\n```dart\nDocument document = await getDocumentWithId(\"document::ID\");\n```\nTo save a document to the database, you can use any of the following methods. Because MutableDocument is a subclass of Document, you can pass either types to saveDocument().\n```dart\nsaveDocument(document);\nsaveDocumentWithId(\"aDocument::ID\", document);\n```\nDocument and MutableDocument object expose getter methods to get values for a key.\n```dart\n// retrieves the value related to the \"key\" as Boolean\naBoolean = document.getBoolean(\"key\");\n// retrieves the value related to the \"key\" as Double\naDouble = document.getDouble(\"key\");\n// retrieves the value related to the \"key\" as Int\naInt = document.getInt(\"key\");\n// retrieves the value related to the \"key\" as String\naString = document.getString(\"key\");\n// retrieves the value related to the \"key\" as List of type T\naList = document.getList\u003cT\u003e(\"key\");\n// retrieves the value related to the \"key\" as Map of type K, V\naMap = document.getMap\u003cK, V\u003e(\"key\");\n```\nDocument and MutableDocument have also methods that help to handle various aspect of documents.\n```dart\nconst document = new Document(); // initializes a new empty document\ndocument.contains(\"key\");        // returns true if the document contains the specified key\ndocument.count();                // returns the number of first level field in the document\ndocument.getKeys();              // returns a List\u003cString\u003e that contains the first level keys of the document\ndocument.toMap();                // returns the document as a Map\u003cString, dynamic\u003e\ndocument.toMutable();            // returns a mutable copy of the document as MutableDocument\ndocument.getId();                // returns the id of the document. If not supplied, the id is setted after having saved the document in the database\ndocument.isNotEmpty();           // returns true if the document has at least one key/value pairs\ndocument.isNotNull();            // returns true if the document is correctly initialized\ndocument.isEmpty();              // returns true if the document doesn't have any key/value pairs\n```\nBecause SubDocument operations are not currently supported, Fluttercouch supply a convenience method to get a List of Map that handles the conversion from dynamic type automatically. The method returns a List of type Map\u003cK, V\u003e (List\u003cMap\u003cK,V\u003e\u003e)\n```dart\nList\u003cMap\u003cK,V\u003e\u003e aListOfMap = document.getListOfMap\u003cK, V\u003e(\"key\");\n```\nThe MutableDocument class exposes setter methods to set document key/value pairs\n```dart\n// initializes a new empty mutable document\nconst mutableDocument = new MutableDocument();\n// you can optionally specify an id or a map to initialize the key/value pairs\nconst mutableDocument = new MutableDocument(id: \"anID\", map: {\"key\": \"value\"});\n\nmutableDocument.setArray(\"key\", aList\u003cAnyType\u003e);  // set a List as the value of \"key\"\nmutableDocument.setBoolean(\"key\", false);         // set a Boolean as the value of \"key\"\nmutableDocument.setDouble(\"key\", aDouble);        // set a Double as the value of \"key\"\nmutableDocument.setInt(\"key\", aInt\u003e);             // set a Int as the value of \"key\"\nmutableDocument.setString(\"key\", \"aString\");      // set a String as the value of \"key\"\nmutableDocument.remove(\"key\");                    // remove the key/value pairs from the document\n```\n\n## Roadmap\nThe first goal is to implement all software parts needed to run the starter code listed \u003ca href=\"https://developer.couchbase.com/documentation/mobile/2.0/couchbase-lite/java.html\"\u003ehere\u003c/a\u003e in Flutter.\n\nThe aim is to construct a “zero-documentation” plugin that can be used by following the Couchbase Mobile Documentation for other platforms. Therefore, any adaptation to the Flutter style has to be optional although strongly desirable, such as integration with Inherited Widgets or other Flutter plugins that manage data and model layers.\n\nThe Fluttercouch plugin is still under development and any contribution is welcome.\n\n## Current development\n\nBy now, the library can create (in Android and iOs devices) a database locally and replicate a couchbase database connecting to sync gateway. It can retrieve a Document by id and extract any “usual” field (no blob) and save it back to the Database.\nQueries have been developed, but some more testing and documentation is needed.\n\nAny suggestion or feedback is appreciated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluttercouch%2Ffluttercouch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffluttercouch%2Ffluttercouch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluttercouch%2Ffluttercouch/lists"}