RNSync is a React Native module that allows you to work with your Cloudant or CouchDB database locally (on the mobile device) and replicate to the remote database when needed.
RNSync is a wrapper for Cloudant Sync, which simplifies large-scale mobile development by enabling you to create a single database for every user; you simply replicate and sync the copy of this database in Cloudant with a local copy on their phone or tablet. This can reduce round-trip database requests with the server. If there’s no network connection, the app runs off the database on the device; when the network connection is restored, Cloudant re-syncs the device and server.
You can get an instance of Cloudant by creating an account on IBM Bluemix.
RNSync only supports ReactNative > 0.40
RNSync works with Redux Persist. Please read the RNSyncStorage doc for more info. You may also prefer the simplified API.
Install with npm
npm install --save rnsync
Add CDTDatastore to your Podfile
pod 'CDTDatastore'
Link and Pod install
react-native link rnsync
cd ios;pod install
react-native link rnsync
The below example exposes your credentials on every device, and the database must already exist, but it is fine for testing the package.
To avoid exposing credentials create a web service to authenticate users and set up databases for client devices. This web service needs to:
- Handle sign in/sign up for users.
- Create a new remote database for a new user.
- Grant access to the new database for the new device (e.g., via API keys on Cloudant or the _users database in CouchDB).
- Return the database URL and credentials to the device.
You can use the rnsync_key_generator package with your Express server to easily handle database and credentials creation. Also refer to cloudantApiKeyGenerator for an example of adding this functionality to your Express server if you do not wish to use rnsync_key_generator.
import rnsync from 'rnsync'
// init with your cloudant or couchDB database
var dbUrl = "https://user:pass@xxxxx"
var dbName = "name_xxxx"
rnsync.init(dbUrl, dbName, function(error)
{
console.log(error)
});
This compacts the SQL database and disk storage by removing the bodies and attachments of obsolete revisions.
rnsync.compact(dbName)
.catch(error => console.warn("Compaction error", error));
rnsync.deleteStore(dbName, function(error)
{
console.log(error);
});
rnsync.readAll(dbName, (error, docs) => {
if (error) {
console.warn(error);
} else {
console.log(docs);
}
})
Both the object and the id are optional. If you leave out the object it will create a new doc that is empty. If you leave out the id that will be autogenerated for you.
var object = {x:10}
var id = "whatever"
rnsync.create(dbName, object, id, function(error, doc)
{
console.log(doc.id)
});
rnsync.create(dbName, {name: 'jon'}, function(error, doc)
{
console.log(doc.id)
});
// note: create will return an error if the id already exist
rnsync.create(dbName, 'user', function(error, doc)
{
console.log(doc.id)
});
Returns the doc with the specified id. It will create the doc if it does not already exist.
rnsync.findOrCreate(dbName, 'user', function(error, doc)
{
console.log(doc.id)
});
Returns the doc with the specified id.
var id = "whatever"
rnsync.retrieve(dbName, id, function(error, doc)
{
console.log(JSON.stringify(doc.body))
});
Returns attachments for a doc with the specified ID, in the form:
{
attachmentId: "base64encodedattachment"
}
rnsync.retrieveAttachments(dbName, id, function(error, attachments)
{
console.log(attachments);
});
When doing an update to a doc, you must include the revision.
doc.body.somechange = "hi mom"
rnsync.update(dbName, doc.id, doc.rev, doc.body, function(error, doc)
{
console.log(JSON.stringify(doc.body))
});
rnsync.delete(dbName, doc.id, function(error)
{
console.log(error)
});
All of the CRUD functions only affect the local database. To push your changes to the remote server you must replicate. For more details see the replication docs
Push your local changes to the remote database
rnsync.replicatePush(dbName, (error, msg, docs, batches) => console.log(error) );
Pull changes from the remote database to your local
rnsync.replicatePull(dbName, (error, msg, docs, batches) => console.log(error) );
Do both a push and a pull
rnsync.replicateSync(dbName, error => console.log(error) );
Note: Not currently implemented.
Query for documents. For more details on the query semantics please see the Cloudant query documentation
var query = {name: 'John', age: { '$gt': 25 }}
rnsync.find(dbName, query, function(error, docs)
{
console.log('found ' + docs.length)
});
var indexes = {
"TEXT":{"textNames":["Common_name","Botanical_name"]},
"JSON":{"jsonNames":["Common_name","Botanical_name"]}
};
rnsync.createIndexes(dbName, indexes, function(error)
{
console.log(error);
});
The following events are emitted by this module:
rnsyncDatabaseOpened
rnsyncDatabaseClosed
rnsyncDatabaseCreated
rnsyncDatabaseDeleted
rnsyncDocumentCreated
rnsyncDocumentUpdated
rnsyncDocumentDeleted
These events may be handled as follows:
import { DeviceEventEmitter } from 'react-native';
this.docCreated = DeviceEventEmitter.addListener('rnsyncDocumentCreated', (e) => {
console.log("doc created", e);
});
import { createStore } from 'redux'
import reducer from './redux/reducers/index'
import {persistStore, autoRehydrate} from 'redux-persist'
import rnsync, {RNSyncStorage} from 'rnsync'
let dbUrl = "https://xxx:xxx-bluemix.cloudant.com";
let dbName = "rnsync"
rnsync.init(dbUrl, dbName, error => console.log(error) )
const store = createStore(reducer, undefined, autoRehydrate())
persistStore(store, {storage: new RNSyncStorage(dbName)});
If you want to do replication before loading the store then:
rnsync.replicateSync(dbName).then(() => persistStore(store, {storage: new RNSyncStorage(dbName)}));
It is up to you to decide when and where to do replication. Later I will add the ability automatically do a replication push when data changes (from a whitelist you pass to rnsyncStorage.)
Patrick Cremin, [email protected]
RNSync is available under the MIT license. See the LICENSE file for more info.