Learn Couchbase Lite with Dart and Flutter

In this learning path you will be reviewing an Android and iOS Application written in Dart and Flutter that uses the community Couchbase Lite SDK for Dart and Flutter. You will learn how to get and insert documents using the key-value engine, query the database using the QueryBuilder engine or SQL++, and learn how to sync information between your mobile app and either a Couchbase Server using Sync Gateway or using peer-to-peer technology.

Full documentation can be found on the Couchbase Developer Portal.

Note: The Dart SDK for Couchbase Lite is a community based project on GitHub and is not officially supported by Couchbase. If you have questions or issues with the SDK, please post them on the GitHub project.

Prerequisites

Before you get started you should take the following prerequisites into consideration:

• Familiarity with building Dart and Flutter Apps

• Familiarity with Bloc and statement management patterns in Flutter

• Android SDK installed and setup (> v.32.0.0)

• Android Build Tools (> v.32.0.0)

• XCode 13 or later installed and setup

• Android device or emulator running API level 23 (Android 6.0 Marshmallow) or above

• iOS device or simulator setup for iOS 14 or later

• IDE of choice (IntelliJ, Android Studio, VS Code, etc.)

• Flutter > 3.0 installed, setup, and configured for your IDE of choice

• curl HTTP client

  • You could use any HTTP client of your choice. But we will use curl in our tutorial. Mac OS Package Manager users can use homebrew. Windows Package Manager users can use winget.

Demo Application

Overview

The demo application used in this learning path is based on auditing inventory in various warehouses for a fictitious company. Most companies have some inventory - from laptops to office supplies and must audit their stock from time to time. For example, when a user's laptop breaks, the Information Technology department can send out a replacement from the inventory of spare laptops they have on hand. In this app, the items we are auditing are cases of beer.

Users running the mobile app would log into the application to see the projects they are assigned to work on. Then, the user would look at the project to see which warehouse they need to travel to. Once at the warehouse, they would inspect the number of cases of beer, tracking them in the mobile application. Finally the data can be synced back to the server for use with other analytical data.

Architecture

The demo application uses bloc, a very popular statement management patternfor Dart.

Bloc is used to manage dependency inversion, injection, and state management. Repositories and Services are registered using Bloc's MultiRepositoryProvider. The sample application is broken down into features which can be found in the src/lib/features directory.

The Database Provider, found in the src/lib/features/database/ diretory, is a custom class that manages the database state and lifecycle. Querying and updating documents in the database is handled using the repository pattern. Blocs will query or post updates to the repository and control the state of objects that the Flutter widgets can use to display information.

Application Flow

The application structure starts with the main function. It creates an InventoryAuditApp that is a Stateless Widget and sets up all repositories and services using MultiRepositoryProvider. The RouteBloc defined is used to handle all routing calls. This bloc defines a child, AppView, which is a stateful widget that uses a MultiBlocListern to react to changes in the route state and thus render new screens as requested.

The default state of the app is for the user to not be authenticated, which will call the LoginScreen widget to render. LoginScreen uses a BlocProvider to inject LoginBloc into the render tree which defines LoginForm as a child to render the UI. When a user taps the _LoginButton, the LoginSubmitted event is added to LoginBloc, which runs the _onSubmitted method to update state with if the user logged in properly or not. If the user is authenticated properly the state is updated and the BlocListner for RouteState will push the ProjectListScreenwidget to the render tree.

The user can use the menu drawer to navigate to other sections of the app or use the Floating Action button to add a new Project.

Replication

Couchbase Capella App Services Users

It's highly recommended to follow the full documentation on the Couchbase Developer Portal. An overview of the steps using the Couchbase Capella documentation is provided below:

The steps below will guide you through the following:

• Setup an App Endpoint under your App Services in Couchbase Capella named projects
• Update your import and sync functions
• Create App Roles and App Users
• Copy the URL of the App Endpoint
• Download the App Endpoint Public Certificate file
• Update the app to use the public certficate and URL information to connect to Couchbase Capella App Services to sync documents between the mobile app and App Services.

1. Create an endpoint called projects using the documentation found here.

• NOTE Use the import.js file in the Import Filter section of the documentation.

2. You will need to update the Access Control and Validation for the App Endpoint usng documentation you can find here.

• NOTE Use the sync.js file in the second step under Security > Access and Validation.

3. You will need to add the roles for the users using the documentation found here.

• You will need to create roles team1 through team15 with the same channel name as the role name. These are assigned to the user in the auth_services.dart file and must must match this file or you will get a 403 error when trying to replicate.

4. You will need to create sample users using the documentation found here.

• You will need to create users demo@example.com through demo15@example.com same roles as found in the auth_services.dart file. If the user isn't added to the proper role, you will have issues when trying to replicate documents.

5. From the App Services Endpoint section of Couchbase Capella, click on the Connect tab.
6. You will need to write down the Public Connection URL that is provided on this page so we can update the hostname in the replicator_provider.dart file in a later step.
7. Download the Public Certificate file. The dart SDK doesn't include the App Services certificate, so you will need to provide it in the app and then pin it in the replication configuration. You can click the Download button under Public Certificate which should download a cert.pem file.
8. Add the .pem file (certificate) to the src folder. It should be at the same folder structure level as your pubspec.yaml file.
9. Update the src/pubspec.yaml file to include the certificate file. Note it's YAML so the spacing is important. An example of what the file file should look like after this change is provided below:

  assets:
    - asset/images/couchbase.png
    - asset/database/startingWarehouses.zip
    - cert.pem

10. Open the replicator_provider.dart file found in the src/lib/features/database directory.
11. Uncomment line 82 that will load the pem file that you added in step 5 and put in the YAML file in step 6

var pem = await rootBundle.load('cert.pem');

12. Update line 87 with the hostname part of your URL that you got from step 3. Note you have to remove the endpoint name from the url to get the hostname. It should look similar to this:

  var url = Uri(scheme: 'wss',
        port: 4984,
        host: 'your_account_hostname.apps.cloud.couchbase.com',             
        path: 'projects',
      );

13. Uncomment out line 103 in order to load the PEM file as a pinned certificate. This will allow the device to trust the connection between App Services and the mobile device. Your code should look like this when done:

      _replicatorConfiguration = ReplicatorConfiguration(
          database: db,
          target: endPoint,
          authenticator: basicAuthenticator,
          continuous: true,
          replicatorType: ReplicatorType.pushAndPull,
          heartbeat: const Duration(seconds: 60),
          // **UNCOMMENT** this the line below if you are using App Services or a custom certificate
          pinnedServerCertificate: pem.buffer.asUint8List()
        );

14. Open the src/lib/features/router/bloc/route_bloc.dart file
15. Uncomment out line 110 so it enables the replicator to initalize once the user logs into the app.

  await _replicatorProvider.init();

16. You should be able to now debug the app and replication should start working. Any documents found on Couchbase Server will be replicated to the mobile device and any documents created on the mobile device will be replicated to the server. You can use the Couchbase Server UI to see the documents that are being replicated.

Try it out

• Open src folder using your favorite IDE
• Build and run the project.
• Log in to the app with "demo@example.com" and "P@ssw0rd12" for user Id and password fields respectively.

Community Documentation

The Dart and Flutter community documentation can be found here.