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


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

import { createRxDatabase, getRxStoragePouch } from 'rxdb';
const db = await createRxDatabase({
  name: 'heroesdb',           // <- name
  storage: getRxStoragePouch('idb'),          // <- storage-adapter
  password: 'myPassword',     // <- password (optional)
  multiInstance: true,         // <- multiInstance (optional, default: true)
  eventReduce: false // <- eventReduce (optional, default: true)


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.


RxDB uses adapters to define where the data is actually stored at. You can use different adapters depending on which environment your database runs in. This has the advantage that you can use the same RxDB code in different environments and just switch out the adapter.

Example for browsers:

// this adapter stores the data in indexeddb

const db = await createRxDatabase({
  name: 'mydatabase',
  storage: getRxStoragePouch('idb')

Check out the List of adapters for RxDB to learn which adapter you should use.


(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.


(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.



One big benefit of having a realtime database is that big performance optimizations can be done when the database knows a query is observed and the updated results are needed continuously. RxDB uses the EventReduce Algorithm to optimize observer or recurring queries.


(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 createRxDatabase({
  name: 'heroesdb',
  storage: getRxStoragePouch('websql'),
  ignoreDuplicate: true
const db2 = await createRxDatabase({
  name: 'heroesdb',
  storage: getRxStoragePouch('websql'),
  ignoreDuplicate: true // this create-call will not throw because you explicitly allow it


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.


Observe with $

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

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


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.

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

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


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

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


Writes the current (or ongoing) database state to the filesystem. Read more


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


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


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

// 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


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();


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
import { removeRxDatabase } from 'rxdb';
removeRxDatabase('mydatabasename', 'localstorage');


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

// must be imported from the pouchdb plugin
import { 
} from 'rxdb/plugins/pouchdb';

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


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

import { isRxDatabase } from 'rxdb';
const is = isRxDatabase(myObj);

If you are new to RxDB, you should continue here

results matching ""

    No results matching ""