RxDatabase

A RxDatabase-Object contains your collections and handles the synchronisation of change-events.

Creation

The database is created by the asynchronous .create()-function of the main RxDB-module. It has the following parameters:

const db = await RxDB.create({
  name: 'heroesdb',           // <- name
  adapter: 'idb',          // <- storage-adapter
  password: 'myPassword',     // <- password (optional)
  multiInstance: true,         // <- multiInstance (optional, default: true)
  queryChangeDetection: false // <- queryChangeDetection (optional, default: false)
});
console.dir(db);

name

The database-name is a string which uniquely identifies the database. When two RxDatabases have the same name and use the same storage-adapter, their data can be assumed as equal and they will share change-events between each other. Depending on the adapter this can also be used to define the storage-folder of your data.

adapter

The storage-adapter defines where the data is actually stored at. You can use a string for pouchdb-adapters or an object for level-adapters. To use an adapter it must before have been added with the RxDB.plugin()-function.

Before using a level-adapter, you have to add the pouchdb-adapter-leveldb module. Please always ensure that your adapter-version is the same as pouchdb-core in the rxdb package.json. Otherwise you might have strange problems

Example with level-adapter:

import memdown from 'memdown';
RxDB.plugin(require('pouchdb-adapter-leveldb'));
const db = await RxDB.create({name: 'mydatabase', adapter: memdown});

password

(optional) If you want to use encrypted fields in the collections of a database, you have to set a password for it. The password must be a string with at least 12 characters.

multiInstance

(optional=true) When you create more than one instance of the same database in a single javascript-runtime, you should set multiInstance to true. This will enable the event-sharing between the two instances serverless. This should be set to false when you have single-instances like a single nodejs-process, a react-native-app, a cordova-app or a single-window electron-app.

queryChangeDetection

(optional=false) If set to true, this enables the QueryChangeDetection for the database.

ignoreDuplicate

(optional=false) If you create multiple RxDatabase-instances with the same name and same adapter, it's very likely that you have done something wrong. To prevent this common mistake, RxDB will throw an error when you do this. In some rare cases like unit-tests, you want to do this intentional by setting ignoreDuplicate to true.

const db1 = await RxDB.create({
  name: 'heroesdb',
  adapter: 'websql',
  ignoreDuplicate: true
});
const db2 = await RxDB.create({
  name: 'heroesdb',
  adapter: 'websql',
  ignoreDuplicate: true // this create-call will not throw because you explicitly allow it
});

pouchSettings

You can pass settings directly to the pouchdb database create options through this property. This settings will be added to all pouchdb-instances that are created for this database.

Functions

Observe with $

Calling this will return an rxjs-Observable which streams every change to data of this database.

myDb.$.subscribe(changeEvent => console.dir(changeEvent));

dump()

Use this function to create a json-export from every piece of data in every collection of this database. You can pass true as a parameter to decrypt the encrypted data-fields of your document.

myDatabase.dump()
  .then(json => console.dir(json));

// decrypted dump
myDatabase.dump(true)
  .then(json => console.dir(json));

importDump()

To import the json-dumps into your database, use this function.

// import the dump to the database
emptyDatabase.importDump(json)
  .then(() => console.log('done'));

server()

Spawns a couchdb-compatible server from the database. Read more

waitForLeadership()

Returns a Promise which resolves when the RxDatabase becomes elected leader.

requestIdlePromise()

Returns a promise which resolves when the database is in idle. This works similar to requestIdleCallback but tracks the idle-ness of the database instead of the CPU. Use this for semi-important tasks like cleanups which should not affect the speed of important tasks.


myDatabase.requestIdlePromise().then(() => {
    // this will run at the moment the database has nothing else to do
    myCollection.customCleanupFunction();
});

// with timeout
myDatabase.requestIdlePromise(1000 /* time in ms */).then(() => {
    // this will run at the moment the database has nothing else to do
    // or the timeout has passed
    myCollection.customCleanupFunction();
});

destroy()

Destroys the databases object-instance. This is to free up memory and stop all observings and replications. Returns a Promise that resolves when the database is destroyed.

await myDatabase.destroy();

remove()

Removes the database and wipes all data of it from the storage.

await myDatabase.remove();
// database is now gone

// NOTICE: You can also remove a database without its instance
RxDB.removeDatabase('mydatabasename', 'localstorage');

checkAdapter()

Checks if the given adapter can be used with RxDB in the current environment.

RxDB.plugin(require('pouchdb-adapter-localstorage')); // adapter must be added before

const ok = await RxDB.checkAdapter('localstorage');
console.dir(ok); // true on most browsers, false on nodejs

isRxDatabase

Returns true if the given object is an instance of RxDatabase. Returns false if not.

const is = RxDB.isRxDatabase(myObj);

If you are new to RxDB, you should continue here

results matching ""

    No results matching ""