Sub‐Generator: blueoak‐pouchdb - BlueOakJS/generator-blueoak GitHub Wiki

#1. Overview The module provides an easy way to work with local data, and synchronize it with a remote CouchDB-like database. As with any other BlueOak generator, the goal is to speedup project setup and development process. Module already has methods and functions that are most often used with PouchDB, so you don’t need to re-invent them. At the same time you have full access to PouchDB package to build your own functionality.

Here is the top-level list of functionality provided by module:

  • Configuration of local and remote databases
  • Continues (live) data replication
  • Ability to start/stop replication process
  • User-friendly form to configure replication settings:
    • Synchronize over Wi-Fi only
    • Pull-only replication
    • Push-only replication
  • Information about current replication status
  • Information about recent data replication

PouchDB is famous for its ability to synchronize data. In order to do this a pair of local and remote databases should be set. This is the cornerstone of the package functionality. You configure local and remote database instances, and module does the rest. As soon as the pair of databases is set module will start to synchronize your data automatically.

PouchDB

https://pouchdb.com/

PouchDB is the heart of the module and has a rich set of functions to work with your data, and synchronize it with remote CouchDB-like databases.

#2. Setup

Add module to an existing Blueoak-based project

2.1. Run blueoak-pouchdb generator

Use yeoman generator to add database support to your project.

yo blueoak:blueoak-pouchdb

The yeoman wizard will ask you few questions and create required application configuration. The only required answer at this moment is the name of local database. Make sure the database name is unique and can’t be shared with other application by mistake.

2.2. Inject services into your application

Blueoak-PouchDB module provides two services: PouchdbService and NetworkStatusService. Inject them into your controller or service.

PouchdbService is the main service and is required.

NetworkStatusService is an auxiliary service that provides information about current connection status.

MyDBService.$inject = ['PouchdbService'];
function MyDBService(PouchdbService){
    var localDb = PouchdbService.localDb;
    …
}

2.3. Add UI view to your application (optional)

The module provides a ready-to-use UI component to control data synchronization settings. The form allows user to change data synchronization settings, see current replication status, and information about recent data replication events.

#3. Configuration Blueoak-PouchDB module relies on the application configuration file (app.config.json). Yeoman generator creates necessary data structure in the configuration file for you. You can update attributes value manually anytime.

Configuration file may contain settings for multiple environments. By default, only “local” environment is updated by yeoman generator.

Blueoak-PouchDB configuration consists of the following sections:

  • localDb
  • remoteDb
  • replicationOptions
  • defaultDataSyncSettings

####localDb #####dbname

Name of local database. Value will be cast to lower case.

#####pouchDbOptions

Default parameters that will be passed to PouchDB constructor during database creation. By default Blueoak-PouchDB module uses the following settings:

"pouchDbOptions":{
          "revs_limit": 1,
          "auto_compaction": true
}

For the list of valid options refer official PouchDB site.

remoteDb

PouchDB provides a rich set of options of what can be used as a remote database. Usually it is a real database on some remote server, but it is not the only option. Another local database can be set as a remote option as well, which can be helpful during development process. In-memory database is a one more option. Please refer official PouchDB site for the list of available options.

dbname

Remote database name. Value will be cast to lower case.

url

URL of a remote database. It is recommended to use HTTPS protocol if supported. If URL is not specified, and “remoteDb.dbname” is set then another local database will be used as a remote.

pouchDbOptions

Default parameters that will be passed to PouchDB constructor during database initialization. Authentication parameters can be configured in this section.

"pouchDbOptions":{
   "auth":{
      "username": "username",
      "password": "userpassword"
   }
}

replicationOptions

Default replication options. Refer official PouchDB documentation for the list of valid options.

Example:

"replicationOptions": {
   "heartbeat": 20000
}

####defaultDataSyncSettings

Default data synchronization settings can be configured here. When application starts for the first time, it will use these values.

    "defaultDataSyncSettings": {
      "syncOverWifiOnly": false,
      "pull": true,
      "push": true
    }

#####syncOverWifiOnly Set to “true” if data synchronization should be performed over WiFi network only. Application will start data synchronization automatically if device is connected to a WiFi network, and stop it when WiFi connection is lost.

#####pull Set to “true” if data changes should be pulled from a remote database.

#####push Set to “true” if data changes should be pushed to a remote database.

Here is a full example of the application configuration file with blueoak-pouchdb branch:

{
  "local": {
    "blueoak_pouchdb": {
      "localDb": {
        "dbname": "bluepouch",
        "pouchDbOptions": {
          "revs_limit": 1,
          "auto_compaction": true
        }
      },
      "remoteDb": {
        "url": "https://some.cloudant.com",
        "dbname": "my_db",
        "pouchDbOptions": {
          "auth": {
            "username": "api_key",
            "password": "api_secret_word"
          }
        }
      },
      "replicationOptions": {},
      "defaultDataSyncSettings": {
        "syncOverWifiOnly": false,
        "pull": true,
        "push": true
      }
  }
}

#4. API

PouchdbService

  • generateId(len)
  • getCurrentReplicationOptions()
  • getDataSyncSettings()
  • getLastSyncDocument()
  • getLocalDbInfo()
  • getReplicationHandler()
  • isPullReplicationEnabled()
  • isPushReplicationEnabled()
  • localDb
  • remoteDb
  • restartReplication(customReplicationOptions)
  • stopReplication()
  • updateDataSyncSettings(cfg)

NetworkStatusService

  • getNetworkInfo()