rxdb Documentation

Follow up Copy Chapter

• Learn how to use RxDB as database in electron with the Quickstart Tutorial.
• Check out the RxDB Electron example
• There is a followup list of other client side database alternatives that you can try to use with Electron.

Docs Src Docs Electron (`docs-src/docs/electron.md`) Copy Section

title: Seamless Electron Storage with RxDB slug: electron.html image: /headers/electron.jpg Copy Chapter

import {Faq, FaqItem} from '@site/src/components/faq';

Electron Plugin

RxStorage Electron IpcRenderer & IpcMain Copy Chapter

To use RxDB in electron, it is recommended to run the RxStorage in the main process and the RxDatabase in the renderer processes. With the rxdb electron plugin you can create a remote RxStorage and consume it from the renderer process.

To do this in a convenient way, the RxDB electron plugin provides the helper functions exposeIpcMainRxStorage and getRxStorageIpcRenderer.
Similar to the Worker RxStorage, these wrap any other RxStorage once in the main process and once in each renderer process. In the renderer you can then use the storage to create a RxDatabase which communicates with the storage of the main process to store and query data.

:::note
nodeIntegration must be enabled in Electron.
:::

//  main.js
const { exposeIpcMainRxStorage } = require('rxdb/plugins/electron');
const { getRxStorageMemory } = require('rxdb/plugins/storage-memory');
app.on('ready', async function () {
    exposeIpcMainRxStorage({
        key: 'main-storage',
        storage: getRxStorageMemory(),
        ipcMain: electron.ipcMain
    });
});

//  renderer.js
const { getRxStorageIpcRenderer } = require('rxdb/plugins/electron');
const { getRxStorageMemory } = require('rxdb/plugins/storage-memory');

const db = await createRxDatabase({
    name,
    storage: getRxStorageIpcRenderer({
        key: 'main-storage',
        ipcRenderer: electron.ipcRenderer
    })
});
/* ... */

FAQ Copy Chapter

Related Copy Chapter

• Comparison of Electron Databases

Docs Src Docs Encryption (`docs-src/docs/encryption.md`) Copy Section

title: Encryption slug: encryption.html image: /headers/encryption.jpg Copy Chapter

import {Steps} from '@site/src/components/steps';
import {PremiumBlock} from '@site/src/components/premium-block';
import { PerformanceChart } from '@site/src/components/performance-chart';
import { PERFORMANCE_DATA_ENCRYPTION, PERFORMANCE_METRICS } from '@site/src/components/performance-data';

import {HeadlineWithIcon} from '@site/src/components/headline-with-icon';
import {IconEncryption} from '@site/src/components/icons/encryption';
import {Faq, FaqItem} from '@site/src/components/faq';
import {DocsAnimation} from '@site/src/components/docs-animation';
import {EncryptionLogo} from '@site/src/components/animations/encryption-logo';

Encrypted Local Storage with RxDB

The RxDB encryption plugin empowers developers to fortify their applications' data security. It seamlessly integrates with RxDB, allowing for the secure storage and retrieval of documents by encrypting them with a password. With encryption and decryption processes handled internally, it ensures that sensitive data remains confidential, making it a valuable tool for building robust, privacy-conscious applications. The encryption works on all RxDB supported devices types like the browser, ReactNative or Node.js.

Encrypting client-side stored data in RxDB offers numerous advantages:

• Enhanced Security: In the unfortunate event of a user's device being stolen, the encrypted data remains safeguarded on the hard drive, inaccessible without the correct password.
• Access Control: You can retain control over stored data by revoking access at any time simply by withholding the password.
• Tamper proof Other applications on the device cannot read out the stored data when the password is only kept in the process-specific memory

Querying encrypted data Copy Chapter

RxDB handles the encryption and decryption of data internally. This means that when you work with a RxDocument, you can access the properties of the document just like you would with normal, unencrypted data. RxDB automatically decrypts the data for you when you retrieve it, making it transparent to your application code.
This means the encryption works with all RxStorage like SQLite, IndexedDB, OPFS and so on.

Keep in mind that everything which reads the documents through the collection sees the decrypted values. A JSON dump therefore contains your encrypted fields in plain text, so treat such a dump as sensitive data.

However, there's a limitation when it comes to querying encrypted fields. Encrypted fields cannot be used as operators in queries. This means you cannot perform queries like "find all documents where the encrypted field equals a certain value." RxDB does not expose the encrypted data in a way that allows direct querying based on the encrypted content. To filter or search for documents based on the contents of encrypted fields, you would need to first decrypt the data and then perform the query, which might not be efficient or practical in some cases.
You could however use the memory mapped RxStorage to replicate the encrypted documents into a non-encrypted in-memory storage and then query them like normal.

Password handling Copy Chapter

RxDB does not define how you should store or retrieve the encryption password. It only requires you to provide the password on database creation which grants you flexibility in how you manage encryption passwords.
You could ask the user on app-start to insert the password, or you can retrieve the password from your backend on app start (or revoke access by no longer providing the password).
The password is also required when you delete an encrypted database with removeRxDatabase(), see removing an encrypted database.

Asymmetric encryption Copy Chapter

The encryption plugin itself uses symmetric encryption with a password to guarantee best performance when reading and storing data.
It is not able to do Asymmetric encryption by itself. If you need Asymmetric encryption with a private/publicKey, it is recommended to encrypted the password itself with the asymmetric keys and store the encrypted password beside the other data. On app-start you can decrypt the password with the private key and use the decrypted password in the RxDB encryption plugin

Using the RxDB Encryption Plugins Copy Chapter

RxDB currently has two plugins for encryption:

• The free encryption-crypto-js plugin that is based on the AES algorithm of the crypto-js library
• encryption-web-crypto plugin that is based on the native Web Crypto API which makes it faster and more secure to use. Document inserts are about 10x faster compared to crypto-js and it has a smaller build size because it uses the browsers API instead of bundling an npm module.

An RxDB encryption plugin is a wrapper around any other RxStorage.

import {
    wrappedKeyEncryptionCryptoJsStorage
} from 'rxdb/plugins/encryption-crypto-js';
import { getRxStorageLocalstorage } from 'rxdb/plugins/storage-localstorage';

// wrap the normal storage with the encryption plugin
const encryptedStorage = wrappedKeyEncryptionCryptoJsStorage({
    storage: getRxStorageLocalstorage()
});

import { createRxDatabase } from 'rxdb/plugins/core';
// create an encrypted database
const myDatabase = await createRxDatabase({
    name: 'mydatabase',
    storage: encryptedStorage,
    password: 'sudoLetMeIn'
});

const todoSchema = {
    version: 0,
    primaryKey: 'id',
    type: 'object',
    properties: {
        id: {
            type: 'string',
            maxLength: 100
        },
        name: {
            type: 'string'
        },
        note: {
            type: 'string'
        }
    },
    required: ['id', 'name'],
    encrypted: ['note']
};

await myDatabase.addCollections({
    todos: {
        schema: todoSchema
    }
});

await myDatabase.todos.insert({
    id: 'todo2',
    name: 'Buy groceries',
    note: 'Milk, eggs, bread' // <- stored encrypted
});
const doc = await myDatabase.todos.findOne('todo2').exec();
console.log(doc.note);
// > 'Milk, eggs, bread'

Using the WebCrypto API Copy Chapter

import {
    wrappedKeyEncryptionWebCryptoStorage,
    createPassword
} from 'rxdb-premium/plugins/encryption-web-crypto';
import { getRxStorageIndexedDB } from 'rxdb-premium/plugins/storage-indexeddb';

// wrap the normal storage with the encryption plugin
const encryptedIndexedDbStorage = wrappedKeyEncryptionWebCryptoStorage({
    storage: getRxStorageIndexedDB()
});

const myPasswordObject = {
    // Algorithm can be oneOf: 'AES-CTR' | 'AES-CBC' | 'AES-GCM'
    algorithm: 'AES-CTR',
    password: 'myRandomPasswordWithMin8Length'
};

// create an encrypted database
const myDatabase = await createRxDatabase({
    name: 'mydatabase',
    storage: encryptedIndexedDbStorage,
    password: myPasswordObject
});

/* ... */

Changing the password Copy Chapter

The password is set database specific and it is not possible to change the password of a database. Opening an existing database with a different password will throw an error. To change the password you can either:

• Use the storage migration plugin to migrate the database state into a new database.
• Store a randomly created meta-password in a different RxDatabase as a value of a local document. Encrypt the meta password with the actual user password and read it out before creating the actual database.

Encrypted attachments Copy Chapter

To store the attachments data encrypted, you have to set encrypted: true in the attachments property of the schema.

const todoSchema = {
    version: 0,
    primaryKey: 'id',
    type: 'object',
    properties: {
        /* ... */
    },
    attachments: {
        // if true, the attachment-data will be
        // encrypted with the db-password
        encrypted: true
    }
};

Encryption and workers Copy Chapter

If you are using Worker RxStorage or SharedWorker RxStorage with encryption, it's recommended to run encryption inside of the worker. Encryption can be very cpu intensive and would take away CPU-power from the main thread which is the main reason to use workers.

You do not need to worry about setting the password inside of the worker. The password will be set when calling createRxDatabase from the main thread, and will be passed internally to the storage in the worker automatically.

Using encryption inside the worker with OPFS Copy Section

When you wrap a storage like OPFS with encryption inside of a worker, you have to set the usesRxDatabaseInWorker option on the OPFS storage. Without this option, the OPFS storage returns raw JSON strings instead of parsed objects as a performance optimization. The encryption wrapper cannot process these strings and will throw an error.

// inside of the worker.js file
import { getRxStorageOPFS } from 'rxdb-premium/plugins/storage-opfs';
import {
    wrappedKeyEncryptionWebCryptoStorage
} from 'rxdb-premium/plugins/encryption-web-crypto';

const storage = wrappedKeyEncryptionWebCryptoStorage({
    storage: getRxStorageOPFS({
        // Required when wrapping OPFS with encryption inside a worker
        usesRxDatabaseInWorker: true
    })
});

Encryption Performance Copy Chapter

As shown in the chart, the WebCrypto based encryption plugins are generally 5 times faster than the crypto-js plugin.

FAQ Copy Chapter

// NOT ALLOWED - 'assignee.email' is a child of 'assignee'
const todoSchema = {
    encrypted: ['assignee', 'assignee.email']
};

// CORRECT - only encrypt the parent
const todoSchema = {
    encrypted: ['assignee']
};

Docs Src Docs Errors (`docs-src/docs/errors.md`) Copy Section

title: Error Messages slug: errors.html image: /headers/errors.jpg Copy Chapter

RxDB Error Messages

When RxDB has an error, an RxError object is thrown instead of a normal JavaScript Error. This RxError contains additional properties such as a code field and parameters. By default the full human readable error messages are not included into the RxDB build. This is because error messages have a high entropy and cannot be compressed well. Therefore only an error message with the correct error-code and parameters is thrown but without the full text.
When you enable the DevMode Plugin the full error messages are added to the RxError. This should only be done in development, not in production builds to keep a small build size.

All RxDB error messages Copy Chapter

import { ErrorMessages } from '@site/src/components/error-messages';

Docs Src Docs Fulltext Search (`docs-src/docs/fulltext-search.md`) Copy Section

title: Fulltext Search slug: fulltext-search.html image: /headers/fulltext-search.jpg Copy Chapter

import {PremiumBlock} from '@site/src/components/premium-block';
import {Steps} from '@site/src/components/steps';
import {DocsAnimation} from '@site/src/components/docs-animation';
import {FulltextSearchLens} from '@site/src/components/animations/fulltext-search-lens';

Fulltext Search

To run fulltext search queries on the local data, RxDB has a fulltext search plugin based on flexsearch and RxPipeline. On each write to a given source RxCollection, an indexer is running to map the written document data into a fulltext search index.
The index can then be queried efficiently with complex fulltext search operations.

Benefits of using a local fulltext search Copy Chapter

1. Efficient Search and Indexing

The plugin utilizes the FlexSearch library, known for its speed and memory efficiency. This ensures that search operations are performed quickly, even with large datasets. The search engine can handle multi-field queries, partial matching, and complex search operations, providing users with highly relevant results.

2. Local Data Indexing

With the plugin, all search operations are performed on the local data stored within the RxDB collections. This means that users can execute fulltext search queries without the need for an external server or database, which is especially beneficial for offline-first applications. The local indexing ensures that search queries are executed quickly, reducing the latency typically associated with remote database queries. Also when used in multiple browser tabs, it is ensured that through Leader Election, only exactly one tabs is doing the work of indexing without having an overhead in the other browser tabs.

3. Real-time Indexing

The plugin integrates seamlessly with RxDB's reactive nature. Every time a document is written to an RxCollection, an indexer updates the fulltext search index in real-time. This ensures that search results are always up-to-date, reflecting the most current state of the data without requiring manual reindexing.

4. Persistent indexing

The fulltext search index is efficiently persisted within the RxCollection, ensuring that the index remains intact across app restarts. When documents are added or updated in the collection, the index is incrementally updated in real-time, meaning only the changes are processed rather than reindexing the entire dataset. This incremental approach not only optimizes performance but also ensures that subsequent app launches are quick, as there's no need to reindex all the data from scratch, making the search feature both reliable and fast from the moment the app starts. When using an encrypted storage the index itself and incremental updates to it are stored fully encrypted and are only decrypted in-memory.

5. Complex Query Support

The FlexSearch-based plugin allows for sophisticated search queries, including multi-term and contextual searches. Users can perform complex searches that go beyond simple keyword matching, enabling more advanced use cases like searching for documents with specific phrases, relevance-based sorting, or even phonetic matching.

6. Offline-First Support and Privacy

As RxDB is designed with offline-first applications in mind, the fulltext search plugin supports this paradigm by ensuring that all search operations can be performed offline. This is crucial for applications that need to function in environments with intermittent or no internet connectivity, offering users a consistent and reliable search experience with zero latency.

Using the RxDB Fulltext Search Copy Chapter

import { RxDBFlexSearchPlugin } from 'rxdb-premium/plugins/flexsearch';
import { addRxPlugin } from 'rxdb/plugins/core';
addRxPlugin(RxDBFlexSearchPlugin);

import { addFulltextSearch } from 'rxdb-premium/plugins/flexsearch';
const flexSearch = await addFulltextSearch({
    // unique identifier. Used to store metadata
    // and continue indexing on restarts/reloads.
    identifier: 'my-search',
    // The source collection on whose documents the search is based on
    collection: myRxCollection,
    /**
     * Transforms the document data to a given searchable string.
     * This can be done by returning a single string property of the document
     * or even by concatenating and transforming multiple fields like:
     * doc => doc.firstName + ' ' + doc.lastName
     */
    docToString: doc => doc.firstName,
    /**
     * (Optional)
     * Amount of documents to index at once.
     * See https://rxdb.info/rx-pipeline.html
     */
    batchSize: number;
    /**
     * (Optional)
     * lazy: Initialize the in memory fulltext index at the first search query.
     * instant: Directly initialize so that the
     * index is already there on the first query.
     * Default: 'instant'
     */
    initialization: 'instant',
    /**
     * (Optional)
     * @link https://github.com/nextapps-de/flexsearch#index-options
     */
    indexOptions: {},
});

// find all documents whose searchstring contains "foobar"
const foundDocuments = await flexSearch.find('foobar');

/**
 * You can also use search options as second parameter
 * @link https://github.com/nextapps-de/flexsearch#search-options
 */
const foundDocuments = await flexSearch.find('foobar', { limit: 10 });

Docs Src Docs Install (`docs-src/docs/install.md`) Copy Section

title: Installation slug: install.html image: /headers/install.jpg Copy Chapter

import {InstallTabs} from '@site/src/components/install-tabs';
import {Tabs} from '@site/src/components/tabs';

Install RxDB

npm Copy Chapter

To install the latest release of rxdb and its dependencies and save it to your package.json, run:

peer-dependency Copy Chapter

You also need to install the peer-dependency rxjs if you have not installed it before.

Use the ES2015 build of RxJS Copy Chapter

RxJS 7 ships an ES5 build and an ES2015 build. The ES2015 build is only resolved when your bundler sets the es2015 export condition. Vite, webpack, Rollup and esbuild do not set it by default, so they bundle the ES5 build together with the tslib helpers. In an RxDB app built with Vite, adding the condition reduces the bundle by about 6.6 KB minified (1.6 KB gzipped). The Angular CLI already sets the condition, so Angular projects need no change.

// vite.config.ts
import { defineConfig, defaultClientConditions } from 'vite';

export default defineConfig({
    resolve: {
        conditions: ['es2015', ...defaultClientConditions]
    }
});

// webpack.config.js
module.exports = {
    resolve: {
        conditionNames: ['es2015', '...']
    }
};

// rollup.config.mjs
import { nodeResolve } from '@rollup/plugin-node-resolve';

export default {
    plugins: [
        nodeResolve({ browser: true, exportConditions: ['es2015'] })
    ]
};

await esbuild.build({
    conditions: ['es2015', 'module']
});

polyfills Copy Chapter

RxDB is coded with ES8 and transpiled to ES5. This means you have to install polyfills to support older browsers. For example you can use core-js with:

npm i core-js --save

If you need polyfills, you have to import them in your code.

import 'core-js/stable';

Polyfill the `global` variable Copy Chapter

When you use RxDB with Angular or other Webpack based frameworks, you might get the error Uncaught ReferenceError: global is not defined.
This is because some dependencies of RxDB assume a Node.js-specific global variable that is not added to browser runtimes by some bundlers.
You have to add them manually, like we do here.

(window as any).global = window;
(window as any).process = {
    env: { DEBUG: undefined },
};

Project Setup and Configuration Copy Chapter

In the examples folder you can find CI tested projects for different frameworks and use cases, while in the /config folder base configuration files for Webpack, Rollup, Mocha, Karma, TypeScript are exposed.

Consult package.json for the versions of the packages supported.

Installing the latest RxDB build Copy Chapter

If you need the latest development state of RxDB, add it as git dependency into your package.json.

"dependencies": {
      "rxdb": "git+https://[email protected]/pubkey/rxdb.git#commitHash"
  }

Replace commitHash with the hash of the latest build-commit.

Import Copy Chapter

To import rxdb, add this to your JavaScript file to import the default bundle that contains the RxDB core:

import {
  createRxDatabase,       // ./rx-database.md
  /* ... */
} from 'rxdb';

Import Reference Copy Chapter

RxDB has three kinds of import paths:

• rxdb (or rxdb/plugins/core): the core functions and all TypeScript types.
• rxdb/plugins/<name>: the open-source plugins.
• rxdb-premium/plugins/<name>: the premium plugins 👑.

Core Functions Copy Section

import {
    createRxDatabase,
    addRxPlugin,
    removeRxDatabase,
    isRxDatabase,
    isRxCollection,
    isRxDocument,
    isRxQuery,
    toTypedRxJsonSchema
} from 'rxdb';

TypeScript Types Copy Section

All types are exported from rxdb. Use import type so that they do not end up in your bundle.

import type {
    RxDatabase,
    RxCollection,
    RxDocument,
    RxQuery,
    RxJsonSchema,
    RxStorage,
    RxConflictHandler,
    ExtractDocumentTypeFromTypedRxJsonSchema,
    ReplicationPullHandler,
    ReplicationPushHandler
} from 'rxdb';

How to combine these types is shown in the TypeScript tutorial.

Storages Copy Section

For unit tests, use the Memory RxStorage. It needs no setup and all data is gone when the process ends. When your tests need a fresh database per test, give each database a random name with randomToken() from rxdb. More testing patterns are on the testing page.

Common Plugins Copy Section

import { RxDBDevModePlugin } from 'rxdb/plugins/dev-mode';
import { wrappedValidateAjvStorage } from 'rxdb/plugins/validate-ajv';
import { RxDBMigrationSchemaPlugin } from 'rxdb/plugins/migration-schema';
import { RxDBLocalDocumentsPlugin } from 'rxdb/plugins/local-documents';
import { RxDBLeaderElectionPlugin } from 'rxdb/plugins/leader-election';
import { RxDBAttachmentsPlugin } from 'rxdb/plugins/attachments';
import { RxDBQueryBuilderPlugin } from 'rxdb/plugins/query-builder';
import { RxDBUpdatePlugin } from 'rxdb/plugins/update';
import { RxDBCleanupPlugin } from 'rxdb/plugins/cleanup';
import { wrappedKeyCompressionStorage } from 'rxdb/plugins/key-compression';
import {
    wrappedKeyEncryptionCryptoJsStorage
} from 'rxdb/plugins/encryption-crypto-js';
import { replicateRxCollection, RxReplicationState } from 'rxdb/plugins/replication';

Docs Src Docs Json Import Export (`docs-src/docs/json-import-export.md`) Copy Section

title: JSON Import and Export slug: json-import-export.html image: /headers/json-import-export.jpg Copy Chapter

import {Faq, FaqItem} from '@site/src/components/faq';

📤 JSON Import and Export

With the json-dump plugin you can export the data of a RxDatabase or a single RxCollection into a plain JSON object and import that object back later.

The dump is a normal JavaScript object, so you can store it in a file, send it to a server, or keep it in localStorage. It contains the documents in their decrypted form and, when you ask for it, the attachments data as base64 strings.

This is useful to:

• Seed a database with a fixed set of documents in tests or demos.
• Move data between two databases, for example when a user switches devices and you have no replication backend.
• Let users download their own data and load it back into the app.

The plugin runs in every runtime that RxDB supports. For server side backups that stream to disk instead of building one big object in memory, use the backup plugin.

Installation Copy Chapter

import { addRxPlugin } from 'rxdb';
import { RxDBJsonDumpPlugin } from 'rxdb/plugins/json-dump';
addRxPlugin(RxDBJsonDumpPlugin);

Export a collection Copy Chapter

exportJSON() creates a dump of every document in the collection.

const json = await myCollection.exportJSON();
console.dir(json);
/* > {
 *     name: 'heroes',
 *     schemaHash: '22b549e064b35a21494eadc441491eeb644bee28aadb0feb9303cb37c0d51b86',
 *     docs: [
 *         {
 *             id: 'alice',
 *             name: 'Alice',
 *             color: 'blue',
 *             _deleted: false,
 *             _meta: { lwt: 1787225698353.01 }
 *         }
 *     ]
 * }
 */

The schemaHash is written into the dump so that importJSON() can refuse a dump that was created from a different schema. The revision _rev is not part of the dump, because the importing database creates its own revisions.

Import into a collection Copy Chapter

importJSON() writes the documents of a dump into the collection.

await myCollection.importJSON(json);

The collection has to exist and its schema has to be the same one the dump was created from. When the hashes do not match, RxDB throws the error JD2.

Notice that importing fires a change event for each inserted document, so open queries and their subscriptions update on their own.

Export a database Copy Chapter

On the database level, exportJSON() runs the export for every collection and puts the results into one object.

const json = await myDatabase.exportJSON();
console.dir(json);
/* > {
 *     name: 'heroesdb',
 *     instanceToken: 'ruxpmzxulz',
 *     collections: [
 *         {
 *             name: 'heroes',
 *             schemaHash: '22b549e064b35a...',
 *             docs: []
 *         }
 *     ]
 * }
 */

To export only some of the collections, pass their names as the first argument.

const json = await myDatabase.exportJSON(['heroes', 'villains']);

Collections whose name starts with an underscore are internal and are always left out of the database export.

Import into a database Copy Chapter

await myDatabase.importJSON(json);

The collections must be created before the import, because the dump does not carry the collection settings like the schema, the migration strategies or the conflict handler. When the dump contains a collection that does not exist in the database, RxDB throws the error JD1 and nothing is written.

Attachments Copy Chapter

By default the attachments of the documents are not part of the dump, because their binary data can be way bigger than the documents itself. Set the attachments option to true to include them. The data is then stored as a base64 string so that the dump stays JSON friendly.

const json = await myCollection.exportJSON({ attachments: true });
console.dir(json.docs[0]._attachments);
/* > {
 *     'cat.txt': {
 *         type: 'text/plain',
 *         length: 4,
 *         data: 'bWVvdw=='
 *     }
 * }
 */

On the database level you can pass the options either as the first argument or after the list of collection names.

// export everything, including the attachments
const json = await myDatabase.exportJSON({ attachments: true });

// export only some collections, including the attachments
const partialJson = await myDatabase.exportJSON(['heroes'], { attachments: true });

importJSON() turns the base64 strings back into Blobs and writes them together with the documents, so no extra option is needed on the import side. The attachment digest is calculated again with the hash function of the importing database, which means a dump can be imported into a database that uses a different hashFunction.

Base64 needs about 33% more space than the raw bytes. When your documents carry big images or videos, the dump grows accordingly and you might want to keep attachments: false and move the files with something else.

Limitations Copy Chapter

Keep these in mind before you use a dump as your backup strategy:

• Encrypted fields are exported in plain text. The export reads the documents through the collection, so the encryption is already undone at that point. Treat the dump as sensitive data and never write it to a place where the plain values must not appear.
• Deleted documents are not part of the dump. The export runs a normal query, and queries skip deleted documents. Because of that, a dump cannot be used to replicate deletions to another database.
• Revisions are not part of the dump. On import, every document is written as a fresh insert with a new revision and a new _meta.lwt. A dump is a snapshot of the current state, not a history.
• The whole dump is built in memory. For a few thousand documents this is fine. For a large dataset, use the backup plugin or one of the replication plugins instead.
• The schema hash must match. A dump cannot be imported into a collection with a changed schema. To move data across a schema change, import it into a collection with the old schema version and let the schema migration run.

FAQ Copy Chapter

Follow Up Copy Chapter

• Learn how to back up a database to the filesystem on the server side.
• Learn how to replicate your data with a backend instead of moving dumps around.
• Read the attachments docs to learn how binary data is stored.
• Start with the RxDB Quickstart.

Docs Src Docs Key Compression (`docs-src/docs/key-compression.md`) Copy Section

title: Key Compression slug: key-compression.html image: /headers/key-compression.jpg Copy Chapter

import {Steps} from '@site/src/components/steps';
import {DocsAnimation} from '@site/src/components/docs-animation';
import {KeyCompressionLogo} from '@site/src/components/animations/key-compression-logo';

Key Compression

With the key compression plugin, documents will be stored in a compressed format which saves up to 40% disk space.
For compression the npm module jsonschema-key-compression is used.
It compresses json-data based on its json-schema while still having valid json. It works by compressing long attribute-names into smaller ones and backwards.

The compression and decompression happens internally, so when you work with a RxDocument, you can access any property like normal.

Enable key compression Copy Chapter

The key compression plugin is a wrapper around any other RxStorage.

import { wrappedKeyCompressionStorage } from 'rxdb/plugins/key-compression';
import { getRxStorageLocalstorage } from 'rxdb/plugins/storage-localstorage';

const storageWithKeyCompression = wrappedKeyCompressionStorage({
    storage: getRxStorageLocalstorage()
});

import { createRxDatabase } from 'rxdb/plugins/core';
const myDatabase = await createRxDatabase({
    name: 'mydatabase',
    storage: storageWithKeyCompression
});

const todoSchema = {
  keyCompression: true, // set this to true, to enable the keyCompression
  version: 0,
  primaryKey: 'id',
  type: 'object',
  properties: {
      id: {
          type: 'string',
          maxLength: 100 // <- the primary key must have set maxLength
      },
      name: {
          type: 'string'
      },
      done: {
          type: 'boolean',
          default: false
      }
      /* ... */
  },
  required: ['id', 'name', 'done']
};
await myDatabase.addCollections({
    todos: {
        schema: todoSchema
    }
});

await myDatabase.todos.insert({ id: 'todo1', name: 'Learn RxDB' });
const doc = await myDatabase.todos.findOne('todo1').exec();
// the document data is decompressed when you access it
console.log(doc.name);
// > 'Learn RxDB'

Docs Src Docs Leader Election (`docs-src/docs/leader-election.md`) Copy Section

title: Leader Election slug: leader-election.html image: /headers/leader-election.jpg Copy Chapter

import {CenteredImage} from '@site/src/components/centered-image';
import {DocsAnimation} from '@site/src/components/docs-animation';
import {LeaderElectionTabs} from '@site/src/components/animations/leader-election-tabs';

Leader-Election

RxDB comes with a leader-election which elects a leading instance between different instances in the same javascript runtime.
Before you read this, please check out on how many of your open browser-tabs you have opened the same website more than once. Count them, I will wait..

So if you would now inspect the traffic that these open tabs produce, you can see that many of them send exact the same data over wire for every tab. No matter if the data is sent with an open websocket or by polling.

Use-case-example Copy Chapter

Imagine we have a website which displays the current temperature of the visitors location in various charts, numbers or heatmaps. To always display the live-data, the website opens a websocket to our API-Server which sends the current temperature every 10 seconds. Using the way most sites are currently build, we can now open it in 5 browser-tabs and it will open 5 websockets which send data 6*5=30 times per minute. This will not only waste the power of your clients device, but also wastes your api-servers resources by opening redundant connections.

Solution Copy Chapter

The solution to this redundancy is the usage of a leader-election-algorithm which makes sure that always exactly one tab is managing the remote-data-access. The managing tab is the elected leader and stays leader until it is closed. No matter how many tabs are opened or closed, there must be always exactly one leader.
You could now start implementing a messaging-system between your browser-tabs, hand out which one is leader, solve conflicts and reassign a new leader when the old one 'dies'.
Or just use RxDB which does all these things for you.

Add the leader election plugin Copy Chapter

To enable the leader election, you have to add the leader-election plugin.

import { addRxPlugin } from 'rxdb';
import { RxDBLeaderElectionPlugin } from 'rxdb/plugins/leader-election';
addRxPlugin(RxDBLeaderElectionPlugin);

Code-example Copy Chapter

To make it easy, here is an example where the temperature is pulled every ten seconds and saved to a collection. The pulling starts at the moment where the opened tab becomes the leader.

import { getRxStorageLocalstorage } from 'rxdb/plugins/storage-localstorage';

const db = await createRxDatabase({
  name: 'weatherDB',
  storage: getRxStorageLocalstorage(),
  password: 'myPassword',
  multiInstance: true
});

await db.addCollections({
  temperature: {
    schema: mySchema
  }
});

db.waitForLeadership()
  .then(() => {
    console.log('Long lives the king!'); // <- runs when db becomes leader
    setInterval(async () => {
      const temp = await fetch('https://example.com/api/temp/');
      db.temperature.insert({
          degrees: temp,
          time: new Date().getTime()
      });
    }, 1000 * 10);
  });

Handle Duplicate Leaders Copy Chapter

On rare occasions, it can happen that more than one leader is elected. This can happen when the CPU is on 100% or for any other reason the JavaScript process is fully blocked for a long time.
For most cases this is not really a problem because on duplicate leaders, both browser tabs replicate with the same backend anyways.
To handle the duplicate leader event, you can access the leader elector and set a handler:

import {
    getLeaderElectorByBroadcastChannel
} from 'rxdb/plugins/leader-election';

const leaderElector = getLeaderElectorByBroadcastChannel(broadcastChannel);
leaderElector.onduplicate = async () => {
    // Duplicate leader detected -> reload the page.
    location.reload();
}

Live-Example Copy Chapter

In this example the leader is marked with the crown ♛

Try it out Copy Chapter

Run the angular-example where the leading tab is marked with a crown on the top-right-corner.

Notice Copy Chapter

The leader election is implemented via the broadcast-channel module.
The leader is elected between different processes on the same javascript-runtime. Like multiple tabs in the same browser or multiple Node.js processes on the same machine. It will not run between different replicated instances.

Docs Src Docs Logger (`docs-src/docs/logger.md`) Copy Section

title: RxDB Logger Plugin - Track & Optimize slug: logger.html image: /headers/logger.jpg Copy Chapter

import {PremiumBlock} from '@site/src/components/premium-block';
import {Steps} from '@site/src/components/steps';

RxDB Logger Plugin

With the logger plugin you can log all operations to the storage layer of your RxDatabase.

This is useful to debug performance problems and for monitoring with Application Performance Monitoring (APM) tools like Bugsnag, Datadog, Elastic, Sentry and others.

Using the logger plugin Copy Chapter

The logger is a wrapper that can be wrapped around any RxStorage. Once your storage is wrapped, you can create your database with the wrapped storage and the logging will automatically happen.

import {
    wrappedLoggerStorage
} from 'rxdb-premium/plugins/logger';
import {
    getRxStorageIndexedDB
} from 'rxdb-premium/plugins/storage-indexeddb';

// wrap a storage with the logger
const loggingStorage = wrappedLoggerStorage({
    storage: getRxStorageIndexedDB({})
});

// create your database with the wrapped storage
const db = await createRxDatabase({
    name: 'mydatabase',
    storage: loggingStorage
});

// create collections etc...

Specify what to be logged Copy Chapter

By default, the plugin will log all operations and it will also run a console.time()/console.timeEnd() around each operation. You can specify what to log so that your logs are less noisy. For this you provide a settings object when calling wrappedLoggerStorage().

const loggingStorage = wrappedLoggerStorage({
    storage: getRxStorageIndexedDB({}),
    settings: {
        // can used to prefix all log strings, default=''
        prefix: 'my-prefix',


        /**
         * Be default, all settings are true.
         */

        // if true, it will log timings with console.time() and console.timeEnd()
        times: true,

        // if false, it will not log meta storage instances like used in replication
        metaStorageInstances: true,

        // operations
        bulkWrite: true,
        findDocumentsById: true,
        query: true,
        count: true,
        info: true,
        getAttachmentData: true,
        getChangedDocumentsSince: true,
        cleanup: true,
        close: true,
        remove: true
    }
});

Using custom logging functions Copy Chapter

With the logger plugin you can also run custom log functions for all operations.

const loggingStorage = wrappedLoggerStorage({
    storage: getRxStorageIndexedDB({}),
    onOperationStart: (operationsName, logId, args) => void,
    onOperationEnd: (operationsName, logId, args) => void,
    onOperationError: (operationsName, logId, args, error) => void
});

Docs Src Docs Middleware (`docs-src/docs/middleware.md`) Copy Section

title: Streamlined RxDB Middleware slug: middleware.html image: /headers/middleware.jpg Copy Chapter

import {DocsAnimation} from '@site/src/components/docs-animation';
import {MiddlewareHook} from '@site/src/components/animations/middleware-hook';

Middleware

RxDB middleware-hooks (also called pre and post hooks) are functions which are passed control during execution of asynchronous functions.
The hooks are specified on RxCollection-level and help to create a clear what-happens-when-structure of your code.

Hooks can be defined to run parallel or in series one after another.
Hooks can be synchronous or asynchronous when they return a Promise.
To stop the operation at a specific hook, throw an error.

List Copy Chapter

RxDB supports the following hooks:

• preInsert
• postInsert
• preSave
• postSave
• preRemove
• postRemove
• postCreate

Why is there no validate-hook? Copy Section

Different to mongoose, the validation on document-data is running on the field-level for every change to a document.
This means if you set the value lastName of a RxDocument, then the validation will only run on the changed field, not the whole document.
Therefore it is not useful to have validate-hooks when a document is written to the database.

Use Cases Copy Chapter

Middleware is useful for atomizing model logic and avoiding nested blocks of async code.
Here are some other ideas:

• complex validation
• removing dependent documents
• asynchronous defaults
• asynchronous tasks that a certain action triggers
• triggering custom events
• notifications

Usage Copy Chapter

All hooks have the plain data as first parameter, and all but preInsert also have the RxDocument-instance as second parameter. If you want to modify the data in the hook, change attributes of the first parameter.

All hook functions are also this-bound to the RxCollection-instance.

Insert Copy Section

An insert-hook receives the data-object of the new document.

lifecycle

• RxCollection.insert is called
• preInsert series-hooks
• preInsert parallel-hooks
• schema validation runs
• new document is written to database
• postInsert series-hooks
• postInsert parallel-hooks
• event is emitted to RxDatabase and RxCollection

preInsert

// series
myCollection.preInsert(function(plainData){
    // set age to 50 before saving
    plainData.age = 50;
}, false);

// parallel
myCollection.preInsert(function(plainData){

}, true);

// async
myCollection.preInsert(function(plainData){
  return new Promise(res => setTimeout(res, 100));
}, false);

// stop the insert-operation
myCollection.preInsert(function(plainData){
  throw new Error('stop');
}, false);

postInsert

// series
myCollection.postInsert(function(plainData, rxDocument){

}, false);

// parallel
myCollection.postInsert(function(plainData, rxDocument){

}, true);

// async
myCollection.postInsert(function(plainData, rxDocument){
  return new Promise(res => setTimeout(res, 100));
}, false);

Save Copy Section

A save-hook receives the document which is saved.

lifecycle

• RxDocument.save is called
• preSave series-hooks
• preSave parallel-hooks
• updated document is written to database
• postSave series-hooks
• postSave parallel-hooks
• event is emitted to RxDatabase and RxCollection

preSave

// series
myCollection.preSave(function(plainData, rxDocument){
    // modify anyField before saving
    plainData.anyField = 'anyValue';
}, false);

// parallel
myCollection.preSave(function(plainData, rxDocument){

}, true);

// async
myCollection.preSave(function(plainData, rxDocument){
  return new Promise(res => setTimeout(res, 100));
}, false);

// stop the save-operation
myCollection.preSave(function(plainData, rxDocument){
  throw new Error('stop');
}, false);

postSave

// series
myCollection.postSave(function(plainData, rxDocument){

}, false);

// parallel
myCollection.postSave(function(plainData, rxDocument){

}, true);

// async
myCollection.postSave(function(plainData, rxDocument){
  return new Promise(res => setTimeout(res, 100));
}, false);

Remove Copy Section

A remove-hook receives the document which is removed.

lifecycle

• RxDocument.remove is called
• preRemove series-hooks
• preRemove parallel-hooks
• deleted document is written to database
• postRemove series-hooks
• postRemove parallel-hooks
• event is emitted to RxDatabase and RxCollection

preRemove

// series
myCollection.preRemove(function(plainData, rxDocument){

}, false);

// parallel
myCollection.preRemove(function(plainData, rxDocument){

}, true);

// async
myCollection.preRemove(function(plainData, rxDocument){
  return new Promise(res => setTimeout(res, 100));
}, false);

// stop the remove-operation
myCollection.preRemove(function(plainData, rxDocument){
  throw new Error('stop');
}, false);

postRemove

// series
myCollection.postRemove(function(plainData, rxDocument){

}, false);

// parallel
myCollection.postRemove(function(plainData, rxDocument){

}, true);

// async
myCollection.postRemove(function(plainData, rxDocument){
  return new Promise(res => setTimeout(res, 100));
}, false);

postCreate Copy Section

This hook is called whenever a RxDocument is constructed.
You can use postCreate to modify every RxDocument-instance of the collection.
This adds a flexible way to add specific behavior to every document. You can also use it to add custom getter/setter to documents. PostCreate-hooks cannot be asynchronous.

myCollection.postCreate(function(plainData, rxDocument){
    Object.defineProperty(rxDocument, 'myField', {
        get: () => 'foobar',
    });
});

const doc = await myCollection.findOne().exec();

console.log(doc.myField);
// 'foobar'

:::note
This hook does not run on already created or cached documents. Make sure to add postCreate-hooks before interacting with the collection.
:::

Docs Src Docs Migration Schema (`docs-src/docs/migration-schema.md`) Copy Section

title: Seamless Schema Data Migration with RxDB slug: migration-schema.html image: /headers/migration-schema.jpg Copy Chapter

import {DocsAnimation} from '@site/src/components/docs-animation';
import {SchemaMigrationLogo} from '@site/src/components/animations/schema-migration-logo';

Migrate Database Data on schema changes

The RxDB Data Migration Plugin helps developers easily update stored data in their apps when they make changes to the data structure by changing the schema of a RxCollection. This is useful when developers release a new version of the app with a different schema.

Imagine you have your awesome todo-app distributed to many users. After a while, you decide that in your new version, you want to change the schema of the todos collection. Instead of saving the dueAt date as a unix-timestamp like 1486940585000 you want to have an ISO 8601 string like 2017-02-12T23:03:05.000Z so that it is readable and can be used in an index with a maxLength. To accomplish this, you change the schema and increase the version-number and you also change your code where you save new todos. But one problem remains: what happens with the todos which are already stored in the database on the user's device in the old schema?

With RxDB you can provide migrationStrategies for your collections that automatically (or on call) transform your existing data from older to newer schemas. This assures that the client's data always matches your newest code-version.

Add the migration plugin Copy Chapter

To enable the data migration, you have to add the migration-schema plugin.

import { addRxPlugin } from 'rxdb';
import { RxDBMigrationSchemaPlugin } from 'rxdb/plugins/migration-schema';
addRxPlugin(RxDBMigrationSchemaPlugin);

Providing strategies Copy Chapter

Upon creation of a collection, you have to provide migrationStrategies when your schema's version-number is greater than 0. To do this, you have to add an object to the migrationStrategies property where a function for every schema-version is assigned. A migrationStrategy is a function which gets the old document-data as a parameter and returns the new, transformed document-data. If the strategy returns null, the document will be removed instead of migrated.

myDatabase.addCollections({
  todos: {
    schema: todoSchemaV1,
    migrationStrategies: {
      // 1 means, this transforms data from version 0 to version 1
      1: function(oldDoc){
        oldDoc.dueAt = new Date(oldDoc.dueAt).toISOString(); // unix to string
        return oldDoc;
      }
    }
  }
});

Asynchronous strategies can also be used:

myDatabase.addCollections({
  todos: {
    schema: todoSchemaV1,
    migrationStrategies: {
      1: function(oldDoc){
        oldDoc.dueAt = new Date(oldDoc.dueAt).toISOString(); // unix to string
        return oldDoc;
      },
      /**
       * 2 means, this transforms data from version 1 to version 2
       * this returns a promise which resolves with the new document-data
       */
      2: function(oldDoc){
        // in the new schema (version: 2) we defined
        // 'priority' as required field (integer)
        // so we must get the priority of the todo from the server
        return fetch('https://example.com/api/todoPriority/' + oldDoc.id)
          .then(response => response.json())
          .then(priority => {
            oldDoc.priority = priority;
            return oldDoc;
          });
      }
    }
  }
});

you can also filter which documents should be migrated:

myDatabase.addCollections({
  todos: {
    schema: todoSchemaV1,
    migrationStrategies: {
      // 1 means, this transforms data from version 0 to version 1
      1: function(oldDoc){
        oldDoc.dueAt = new Date(oldDoc.dueAt).toISOString(); // unix to string
        return oldDoc;
      },
      /**
       * this removes all todos due before 2017-02-12
       * they will not appear in the new collection
       */
      2: function(oldDoc){
        if(oldDoc.dueAt < '2017-02-12T00:00:00.000Z') return null;
        else return oldDoc;
      }
    }
  }
});

autoMigrate Copy Chapter

By default, the migration automatically happens when the collection is created. Calling RxDatabase.addCollections() returns only when the migration has finished.
If you have lots of data or the migrationStrategies take a long time, it might be better to start the migration 'by hand' and show the migration-state to the user as a loading-bar.

:::warning No writes during a running migration
While a schema migration is running on a collection, writes to that collection are not allowed.
Calls that would write will throw a COL25 error until the migration finishes.
Wait for collection.migratePromise() to resolve (or observe collection.getMigrationState().$ until status is DONE)
before performing writes.
:::

await myDatabase.addCollections({
  todos: {
    schema: todoSchemaV1,
    autoMigrate: false, // <- migration will not run at creation
    migrationStrategies: {
      1: async function(oldDoc){
        ...
        anything that takes very long
        ...
        return oldDoc;
      }
    }
  }
});
const todosCollection = myDatabase.todos;

// check if migration is needed
const needed = await todosCollection.migrationNeeded();
if(needed === false) {
  return;
}

// start the migration
// 10 is the batch-size, how many docs will run
// at parallel
todosCollection.startMigration(10);

const migrationState = todosCollection.getMigrationState();

// 'start' the observable
migrationState.$.subscribe({
    next: state => console.dir(state),
    error: error => console.error(error),
    complete: () => console.log('done')
});

// the emitted states look like this:
{
    status: 'RUNNING' // oneOf 'RUNNING' | 'DONE' | 'ERROR'
    count: {
      total: 50,   // amount of documents which must be migrated
      handled: 0,  // amount of handled docs
      percent: 0   // percentage [0-100]
    }
}

If you don't want to show the state to the user, you can also use .migratePromise():

const migrationPromise = todosCollection.migratePromise(10);
await migrationPromise;

migrationStates() Copy Chapter

RxDatabase.migrationStates() returns an Observable that emits all migration states of any collection of the database.
Use this when you add collections dynamically and want to show a loading-state of the migrations to the user.

const allStatesObservable = myDatabase.migrationStates();
allStatesObservable.subscribe(allStates => {
  allStates.forEach(migrationState => {
    console.log(
      'migration state of ' +
      migrationState.collection.name
    );
  });
});

Default values are not auto-applied Copy Chapter

Schema default values are not automatically filled in during migration. When you insert a document through the normal RxDB API (like insert() or bulkInsert()), fields with a default in the schema are auto-filled. Migration does not do this. Your migration strategy has full explicit control over the document data and must set every field that the new schema needs.

const todoSchemaV1 = {
    version: 1,
    primaryKey: 'id',
    type: 'object',
    properties: {
        id: { type: 'string', maxLength: 100 },
        name: { type: 'string' },
        // new field in v1 with a default value
        tags: {
            type: 'array',
            default: [],
            items: { type: 'string' }
        }
    },
    required: ['id', 'name', 'tags']
};

const migrationStrategies = {
    1: function(oldDoc){
        /**
         * You must explicitly set 'tags' here.
         * The schema default [] will NOT be
         * applied automatically during migration.
         */
        oldDoc.tags = [];
        return oldDoc;
    }
};

Migrating attachments Copy Chapter

When you store RxAttachments together with your document, they can also be changed, added or removed while running the migration.
You can do this by mutating the oldDoc._attachments property.

import { createBlob } from 'rxdb';
const migrationStrategies = {
      1: async function(oldDoc){
        // do nothing with _attachments to keep all
        // attachments in the new collection version.
        return oldDoc;
      },
      2: async function(oldDoc){
        // set _attachments to an empty object to
        // delete all existing ones during migration.
        oldDoc._attachments = {};
        return oldDoc;
      },
      3: async function(oldDoc){
        // update the data field of a single attachment to change its data. 
        oldDoc._attachments.myFile.data = await createBlob(
          'my new text',
          oldDoc._attachments.myFile.content_type
        );
        return oldDoc;
      }
}

Migration on multi-tab in browsers Copy Chapter

If you use RxDB in a multiInstance environment, like a browser, it will ensure that exactly one tab is running a migration of a collection.
Also the migrationState.$ events are emitted between browser tabs.

Migration and Replication Copy Chapter

If you use any of the RxReplication plugins, the migration will also run on the internal replication-state storage. It will migrate all assumedMasterState documents
so that after the migration is done, you do not have to re-run the replication from scratch.
RxDB assumes that you run the exact same migration on the servers and the clients. Notice that the replication pull-checkpoint will not be migrated. Your backend must be compatible with pull-checkpoints of older versions.

Migration should be run on all database instances Copy Chapter

If you have multiple database instances (for example, if you are running replication inside of a Worker or SharedWorker and have created a database instance inside of the worker), schema migration should be started on all database instances. All instances must know about all migration strategies and any updated schema versions.

Docs Src Docs Migration Storage (`docs-src/docs/migration-storage.md`) Copy Section

title: Migration Storage slug: migration-storage.html image: /headers/migration-storage.jpg Copy Chapter

import {Faq, FaqItem} from '@site/src/components/faq';

Storage Migration

The storage migration plugin can be used to migrate all data from one existing RxStorage into another. This is useful when:

• You want to migrate from one RxStorage to another one.
• You want to migrate to a new major RxDB version while keeping the previous saved data. This function only works from the previous major version upwards. Do not use it to migrate like rxdb v9 to v14.

The storage migration drops deleted documents and filters them out during the migration.

:::warning Do never change the schema while doing a storage migration

When you migrate between storages, you might want to change the schema in the same process. You should never do that because it will lead to problems afterwards and might make your database unusable.

When you also want to change your schema, first run the storage migration and afterwards run a normal schema migration.
:::

Usage Copy Chapter

Lets say you want to migrate from LocalStorage RxStorage to the IndexedDB RxStorage.

import { migrateStorage } from 'rxdb/plugins/migration-storage';
import { getRxStorageIndexedDB } from 'rxdb-premium/plugins/storage-indexeddb';
import { getRxStorageLocalstorage } from 'rxdb-old/plugins/storage-localstorage';

// create the new RxDatabase
const db = await createRxDatabase({
    name: dbLocation,
    storage: getRxStorageIndexedDB(),
    multiInstance: false
});

await migrateStorage({
    database: db as any,
    /**
     * Name of the old database,
     * using the storage migration requires that the
     * new database has a different name.
     */
    oldDatabaseName: 'myOldDatabaseName',
    oldStorage: getRxStorageLocalstorage(), // RxStorage of the old database
    batchSize: 500, // batch size
    // true: migrate all collections in parallel
    // false (default): migrate in serial
    parallel: false,
    afterMigrateBatch: (input: AfterMigrateBatchHandlerInput) => {
        console.log('storage migration: batch processed');
    }
});

:::note
Only collections that exist in the new database at the time you call migrateStorage() will have their data migrated.

• If your old database had collections ['users', 'posts', 'comments'] but your new database only defines ['users', 'posts'], then only users and posts data will be migrated.
• Any collections missing from the new database will simply be skipped - no data for them will be read or written.

This allows you to selectively migrate only certain collections if desired, by choosing which collections to define before invoking migrateStorage().
:::

Migrate from a previous RxDB major version Copy Chapter

To migrate from a previous RxDB major version, you have to install the 'old' RxDB in the package.json

{
    "dependencies": {
        "rxdb-old": "npm:[email protected]",
    }
}

Then you can run the migration by providing the old storage:

/* ... */
import { migrateStorage } from 'rxdb/plugins/migration-storage';
// import from the old RxDB version
import {
    getRxStorageLocalstorage
} from 'rxdb-old/plugins/storage-localstorage';

await migrateStorage({
    database: db as any,
    /**
     * Name of the old database,
     * using the storage migration requires that the
     * new database has a different name.
     */
    oldDatabaseName: 'myOldDatabaseName',
    oldStorage: getRxStorageLocalstorage(), // RxStorage of the old database
    batchSize: 500, // batch size
    parallel: false,
    afterMigrateBatch: (input: AfterMigrateBatchHandlerInput) => {
        console.log('storage migration: batch processed');
    }
});
/* ... */

Disable Version Check on [RxDB Premium 👑](/premium/) Copy Chapter

RxDB Premium has a check in place that ensures that you do not accidentally use the wrong RxDB core and 👑 Premium version together which could break your database state.
This can be a problem during migrations where you have multiple versions of RxDB in use and it will throw the error Version mismatch detected.
You can disable that check by importing and running the disableVersionCheck() function from RxDB Premium.

// RxDB Premium v15 or newer:
import {
    disableVersionCheck
} from 'rxdb-premium-old/plugins/shared';
disableVersionCheck();


// RxDB Premium v14:

// for esm
import {
    disableVersionCheck
} from 'rxdb-premium-old/dist/es/shared/version-check.js';
disableVersionCheck();

// for cjs
import {
    disableVersionCheck
} from 'rxdb-premium-old/dist/lib/shared/version-check.js';
disableVersionCheck();

FAQ Copy Chapter

Docs Src Docs Nodejs Database (`docs-src/docs/nodejs-database.md`) Copy Section

title: RxDB - The Real-Time Database for Node.js slug: nodejs-database.html image: /headers/nodejs-database.jpg Copy Chapter

import { PerformanceChart } from '@site/src/components/performance-chart';
import { PERFORMANCE_DATA_NODE, PERFORMANCE_METRICS } from '@site/src/components/performance-data';
import {Faq, FaqItem} from '@site/src/components/faq';
import {CenteredImage} from '@site/src/components/centered-image';

Node.js Database

RxDB is a fast, reactive realtime NoSQL database made for JavaScript applications like Websites, hybrid Apps, Electron-Apps, Progressive Web Apps and Node.js. While RxDB was initially created to be used with UI applications, it has been matured and optimized to make it useful for pure server-side use cases. It can be used as embedded, local database inside of the Node.js JavaScript process, or it can be used similar to a database server that Node.js can connect to. The RxStorage layer makes it possible to switch out the underlying storage engine which makes RxDB a very flexible database that can be optimized for many scenarios.

Persistent Database Copy Chapter

To get a "normal" database connection where the data is persisted to a file system, the RxDB real time database provides multiple storage implementations that work in Node.js.

The FoundationDB storage connects to a FoundationDB cluster which itself is just a distributed key-value engine. RxDB adds the NoSQL query-engine, indexes and other features on top of it.
It scales horizontally because you can always add more servers to the FoundationDB cluster to increase the capacity.
Setting up a RxDB database is pretty simple. You import the FoundationDB RxStorage and tell RxDB to use that when calling createRxDatabase:

import { createRxDatabase } from 'rxdb';
import { getRxStorageFoundationDB } from 'rxdb/plugins/storage-foundationdb';

const db = await createRxDatabase({
    name: 'exampledb',
    storage: getRxStorageFoundationDB({
        apiVersion: 620,
        clusterFile: '/path/to/fdb.cluster'
    })
});

// add a collection
await db.addCollections({
    users: {
        schema: mySchema
    }
});

// run a query
const result = await db.users.find({
    selector: {
        name: 'foobar'
    }
}).exec();

Another alternative storage is the SQLite RxStorage that stores the data inside of a SQLite file-based database. The SQLite storage is faster than FoundationDB and does not require to set up a cluster or anything because SQLite directly stores and reads the data inside of the filesystem. The downside of that is that it only scales vertically.

import { createRxDatabase } from 'rxdb';
import {
    getRxStorageSQLite,
    getSQLiteBasicsNode
} from 'rxdb-premium/plugins/storage-sqlite';
import sqlite3 from 'sqlite3';
const myRxDatabase = await createRxDatabase({
    name: 'path/to/database/file/foobar.db',
    storage: getRxStorageSQLite({
        sqliteBasics: getSQLiteBasicsNode(sqlite3)
    })
});

Because the SQLite RxStorage is not free and you might not want to set up a FoundationDB cluster, there is also the SQLite trial storage which ships with RxDB Core. It uses the node:sqlite module that is built into Node.js. The trial storage is limited to 500 documents and does not use indexes, so it works for prototypes but is not made for production.

import { createRxDatabase } from 'rxdb';
import {
    getRxStorageSQLiteTrial,
    getSQLiteBasicsNodeNative
} from 'rxdb/plugins/storage-sqlite';
import { DatabaseSync } from 'node:sqlite';
const myRxDatabase = await createRxDatabase({
    name: 'path/to/database/file/foobar.db',
    storage: getRxStorageSQLiteTrial({
        sqliteBasics: getSQLiteBasicsNodeNative(DatabaseSync)
    })
});

Here is a performance comparison chart of the different storages (lower is better):

RxDB as Node.js In-Memory Database Copy Chapter

One of the easiest way to use RxDB in Node.js is to use the Memory RxStorage. As the name implies, it stores the data directly in-memory of the Node.js JavaScript process. This makes it really fast to read and write data but of course the data is not persisted and will be lost when the nodejs process exits. Often the in-memory option is used when RxDB is used in unit tests because it automatically cleans up everything afterwards.

import { createRxDatabase } from 'rxdb';
import { getRxStorageMemory } from 'rxdb/plugins/storage-memory';

const db = await createRxDatabase({
    name: 'exampledb',
    storage: getRxStorageMemory()
});

Also notice that the default memory limit of Node.js is 4gb (might change of newer versions) so for bigger datasets you might want to increase the limit with the max-old-space-size flag:

# increase the Node.js memory limit to 8GB
node --max-old-space-size=8192 index.js

Hybrid In-memory-persistence-synced storage Copy Chapter

If you want to have the performance of an in-memory database but require persistency of the data, you can use the memory-mapped storage. On database creation it will load all data into the memory and on writes it will first write the data into memory and later also write it to the persistent storage in the background. In the following example the FoundationDB storage is used, but any other RxStorage can be used as persistence layer.

import { createRxDatabase } from 'rxdb';
import { getRxStorageFoundationDB } from 'rxdb/plugins/storage-foundationdb';
import { getMemoryMappedRxStorage } from 'rxdb-premium/plugins/storage-memory-mapped';

const db = await createRxDatabase({
    name: 'exampledb',
    storage: getMemoryMappedRxStorage({
        storage: getRxStorageFoundationDB({
            apiVersion: 620,
            clusterFile: '/path/to/fdb.cluster'
        })
    })
});

While this approach gives you a database with great performance and persistent, it has two major downsides:

• The database size is limited to the memory size
• Writes can be lost when the Node.js process exists between a write to the memory state and the background persisting.

Share database between microservices with RxDB Copy Chapter

Using a local, embedded database in Node.js works great until you have to share the data with another Node.js process or another server at all.
To share the database state with other instances, RxDB provides two different methods. One is replication and the other is the remote RxStorage.
The replication copies over the whole database set to other instances live-replicates all ongoing writes. This has the benefit of scaling better because each of your microservice will run queries on its own copy of the dataset.
Sometimes however you might not want to store the full dataset on each microservice. Then it is better to use the remote RxStorage and connect it to the "main" database. The remote storage will run all operations the main database and return the result to the calling database.

FAQ Copy Chapter

Follow up on RxDB+Node.js Copy Chapter

• Check out the RxDB Nodejs example.
• If you haven't done yet, you should start learning about RxDB with the Quickstart Tutorial.
• I created a list of embedded JavaSCript databases that you will help you to pick a database if you do not want to use RxDB.
• Check out the MongoDB RxStorage that uses MongoDB for the database connection from your Node.js application and runs the RxDB real time database on top of it.

Docs Src Docs Nosql Performance Tips (`docs-src/docs/nosql-performance-tips.md`) Copy Section

title: RxDB NoSQL Performance Tips slug: nosql-performance-tips.html image: /headers/nosql-performance-tips.jpg Copy Chapter

Performance tips for RxDB and other [NoSQL](./articles/in-memory-nosql-database.md) databases

In this guide, you'll find techniques to improve the performance of RxDB operations and queries. Notice that all your performance optimizations should be done with a correct tracking of the metrics, otherwise you might change stuff into the wrong direction.

Use bulk operations Copy Chapter

When you run write operations on multiple documents, make sure you use bulk operations instead of single document operations.

// wrong ❌
for(const docData of dataAr){
    await myCollection.insert(docData);
}

// right ✔️
await myCollection.bulkInsert(dataAr);

Help the query planner by adding operators that better restrict the index range Copy Chapter

Often on complex queries, RxDB (and other databases) do not pick the optimal index range when querying a result set.
You can add additional restrictive operators to ensure the query runs over a smaller index space and has a better performance.

Lets see some examples for different query types.

/**
 * Adding a restrictive operator for an $or query
 * so that it better limits the index space for the time-field.
 */
const orQuery = {
    selector: {
        $or: [
            {
                time: { $gt: 1234 },
            },
            {
                time: { $eq: 1234 },
                user: { $gt: 'foobar' }
            },
        ],
        time: { $gte: 1234 } // <- add restrictive operator
    }
}

/**
 * Adding a restrictive operator for an $regex query
 * so that it better limits the index space for the user-field.
 * We know that all matching fields start with 'foo' so we can
 * tell the query to use that as lower constraint for the index.
 */
const regexQuery = {
    selector: {
        user: {
            $regex: '^foo(.*)0-9$', // a complex regex with a ^ in the beginning
            $gte: 'foo' // <- add restrictive operator
        }
    }
}

/**
 * Adding a restrictive operator for a query on an enum field.
 * so that it better limits the index space for the time-field.
 */

const enumQuery = {
    selector: {
        /**
         * Here lets assume our status field has
         * the enum type
         * ['idle', 'in-progress', 'done']
         * so our restrictive operator can exclude
         * all documents with 'done' as status.
         */
        status: {
            $in: [
                'idle',
                'in-progress',
            ],
            $gt: 'done' // <- add restrictive operator on status
        }
    }
}

For $in queries on an indexed field, the RxDB query planner limits the scanned index space to the range between the smallest and the largest of the given values. Adding a restrictive operator next to an $in is only useful when you know a tighter bound than the min/max of the values.

Set a specific index Copy Chapter

Sometime the query planner of the database itself has no chance in picking the best index of the possible given indexes.
For queries where performance is very important, you might want to explicitly specify which index must be used.

const myQuery = myCollection.find({
    selector: {
        /* ... */
    },
    // explicitly specify index
    index: [
        'fieldA',
        'fieldB'
    ]

});

Try different ordering of index fields Copy Chapter

The order of the fields in a compound index is very important for performance. When optimizing index usage, you should try out different orders on the index fields and measure which runs faster. For that it is very important to run tests on real-world data where the distribution of the data is the same as in production.
For example when there is a query on a user collection with an age and a gender field, it depends if the index ['gender', 'age'] performance better as ['age', 'gender'] based on the distribution of data:

const query = myCollection
    .findOne({
      selector: {
        age: {
          $gt: 18
        },
        gender: {
          $eq: 'm'
        }
      },
      /**
       * Because the developer knows that 50% of the documents are 'male',
       * but only 20% are below age 18,
       * it makes sense to enforce using the
       * ['gender', 'age'] index to improve
       * performance. This could not be known
       * by the query planer which might have
       * chosen ['age', 'gender'] instead.
       */
      index: ['gender', 'age']
    });

Notice that RxDB has the Query Optimizer Plugin that can be used to automatically find the best indexes.

Make a Query "hot" to reduce load Copy Chapter

Having a query where the up-to-date result set is needed more than once, you might want to make the query "hot" by permanently subscribing to it. This ensures that the query result is kept up to date by RxDB ant the EventReduce algorithm at any time so that at the moment you need the current results, it has them already.

For example when you use RxDB at Node.js for a webserver, you should use an outer "hot" query instead of running the same query again on every request to a route.

// wrong ❌
app.get('/list', (req, res) => {
    const result = await myCollection.find({/* ... */}).exec();
    res.send(JSON.stringify(result));
});

// right ✔️
const query = myCollection.find({/* ... */});
query.subscribe(); // <- make it hot

app.get('/list', (req, res) => {
    const result = await query.exec();
    res.send(JSON.stringify(result));
});

Store parts of your document data as attachment Copy Chapter

For in-app databases like RxDB, it does not make sense to partially parse the JSON of a document. Instead, always the whole document json is parsed and handled. This has a better performance because JSON.parse() in JavaScript directly calls a C++ binding which can parse really fast compared to a partial parsing in JavaScript itself. Also by always having the full document, RxDB can de-duplicate memory caches of document across multiple queries.

The downside is that very very big documents with a complex structure can increase query time significantly. Documents fields with complex that are mostly not in use, can be move into an attachment. This would lead RxDB to not fetch the attachment data each time the document is loaded from disc. Instead only when explicitly asked for.

const myDocument = await myCollection.insert({/* ... */});
const attachment = await myDocument.putAttachment(
    {
        id: 'otherStuff.json',
        data: createBlob(JSON.stringify({/* ... */}), 'application/json'),
        type: 'application/json'
    }
);

Process queries in a worker process Copy Chapter

Moving database storage into a WebWorker can significantly improve performance in web applications that use RxDB or similar NoSQL databases. When database operations are executed in the main JavaScript thread, they can block or slow down the User Interface, especially during heavy or complex data operations. By offloading these operations to a WebWorker, you effectively separate the data processing workload from the UI thread. This means the main thread remains free to handle user interactions and render updates without delay, leading to a smoother and more responsive user experience. Additionally, WebWorkers allow for parallel data processing, which can expedite tasks like querying and indexing. This approach not only enhances UI responsiveness but also optimizes overall application performance by leveraging the multi-threading capabilities of modern browsers.
With RxDB you can use the Worker and SharedWorker plugin to move the query processing away from the main thread.

Use less plugins and hooks Copy Chapter

Utilizing fewer hooks and plugins in RxDB or similar NoSQL database systems can lead to markedly better performance. Each additional hook or plugin introduces extra layers of processing and potential overhead, which can cumulatively slow down database operations. These extensions often execute additional code or enforce extra checks with each operation, such as insertions, updates, or deletions. While they can provide valuable functionalities or custom behaviors, their overuse can inadvertently increase the complexity and execution time of basic database operations. By minimizing their use and only employing essential hooks and plugins, the system can operate more efficiently. This streamlined approach reduces the computational burden on each transaction, leading to faster response times and a more efficient overall data handling process, especially critical in high-load or real-time applications where performance is paramount.

Docs Src Docs Offline First (`docs-src/docs/offline-first.md`) Copy Section

title: Local First / Offline First slug: offline-first.html image: /headers/offline-first.jpg Copy Chapter

import {Faq, FaqItem} from '@site/src/components/faq';
import {CenteredImage} from '@site/src/components/centered-image';

Local First / Offline First

Local-First (aka offline first) is a software paradigm where the software stores data locally on the client's device and must work as well offline as it does online.
To implement this, you have to store data at the client side, so that your application can still access it when the internet connection is lost.
This can be either done with complex caching strategies, or by using a local-first, offline database (like RxDB) that stores the data inside of a local database like IndexedDB and replicates it from and to the backend in the background. This makes the local database, not the server, the gateway for all persistent changes in application state. In DDIL environments, where the connection is denied, disrupted, intermittent, or limited most of the time, this is not an optimization but the only architecture that works.

Offline first is not about having no internet connection

:::note
I wrote a follow-up version of offline/first local first about Why Local-First Is the Future and what are Its Limitations
:::

While in the past, internet connection was unstable, things are changing especially for mobile devices.
Mobile networks have become better and having no internet becomes less common even in remote locations.
So if we did not care about offline first applications in the past, why should we even care now?
In the following I will point out why offline first applications are better, not because they support offline usage, but because of other reasons.

const heroes = await myDatabase.addCollections({
  heroes: {
    schema: mySchema,
    statics: {
      scream: function(){
          return 'AAAH!!';
      }
    }
  }
});

console.log(heroes.scream());
// 'AAAH!!'

const heroes = await myDatabase.addCollections({
  heroes: {
    schema: mySchema,
    statics: {
      whoAmI: function(){
          return this.name;
      }
    }
  }
});
console.log(heroes.whoAmI());
// 'heroes'

const heroes = await myDatabase.addCollections({
  heroes: {
    schema: mySchema,
    methods: {
      scream: function(){
        return 'AAAH!!';
      }
    }
  }
});
const doc = await heroes.findOne().exec();
console.log(doc.scream());
// 'AAAH!!'

const heroes = await myDatabase.addCollections({
  heroes: {
    schema: mySchema,
    methods: {
      whoAmI: function(){
          return 'I am ' + this.name + '!!';
      }
    }
  }
});
await heroes.insert({
  name: 'Skeletor'
});
const doc = await heroes.findOne().exec();
console.log(doc.whoAmI());
// 'I am Skeletor!!'

const heroes = await myDatabase.addCollections({
  heroes: {
    schema: mySchema,
    attachments: {
      scream: function(){
          return 'AAAH!!';
      }
    }
  }
});
const doc = await heroes.findOne().exec();
const attachment = await doc.putAttachment({
    id: 'cat.txt',
    data: 'meow I am a kitty',
    type: 'text/plain'
});
console.log(attachment.scream());
// 'AAAH!!'

RxCollection: db.voxels
                                 |
        +------------------------+------------------------+
        |                        |                        |
  replicationState        replicationState        replicationState
  id: chunk-123           id: chunk-124           id: chunk-125
  pull: ?chunkId=123      pull: ?chunkId=124      pull: ?chunkId=125

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

const collection = myDatabase.addCollections({
    foo: {
        schema: mySchema,
        options: { // anything can be passed into the options
            foo: ()=>'bar'
        }
    }
})

// Afterwards you can use these options in your plugin.

collection.options.foo(); // 'bar'

export const todoSchemaWithParent = {
    title: 'todo related to a parent todo',
    version: 0,
    primaryKey: 'id',
    type: 'object',
    properties: {
        id: {
            type: 'string',
            maxLength: 100
        },
        name: {
            type: 'string'
        },
        parent: {
            ref: 'todos',     // refers to collection todos
            // ref-values must always be string
            // or ['string', 'null']
            // (primary of foreign RxDocument)
            type: 'string'
        }
    },
    required: ['id', 'name']
};

export const todoSchemaWithSubtasks = {
  version: 0,
  primaryKey: 'id',
  type: 'object',
  properties: {
    id: {
      type: 'string',
      maxLength: 100
    },
    name: {
      type: 'string'
    },
    subtasks: {
      type: 'array',
      ref: 'todos',
      items: {
        type: 'string'
      }
    }
  },
  required: ['id', 'name']
};

await myDatabase.todos.bulkInsert([
  {
    id: 'todo1',
    name: 'Learn RxDB',
    done: false,
    dueAt: '2026-01-01T10:00:00.000Z',
    priority: 8,
    tags: ['learning', 'rxdb'],
    subtasks: ['todo3']
  },
  {
    id: 'todo3',
    name: 'Set up replication',
    dueAt: '2026-01-03T14:15:00.000Z',
    priority: 10,
    tags: ['rxdb', 'backend']
  }
]);
const doc = await myDatabase.todos.findOne('todo1').exec();
const subtasks = await doc.populate('subtasks');
console.dir(subtasks); //> [RxDocument[todo3]]

const doc = await myDatabase.todos.findOne('todo1').exec();
const subtasks = await doc.subtasks_; // notice the underscore `_`
console.dir(subtasks); //> [RxDocument[todo3]]

await myDatabase.addCollections({
  todos: {
    schema: {
      version: 0,
      primaryKey: 'id',
      type: 'object',
      properties: {
        id: {
          type: 'string',
          maxLength: 100
        },
        name: {
          type: 'string'
        },
        relations: {
          type: 'object',
          properties: {
            parent: {
              type: 'string',
              ref: 'todos'
            }
          }
        }
      },
      required: ['id', 'name']
    }
  }
});

/**
 * We assume myDocument is a document from the collection
 */
const parent = await myDocument.relations.parent_;
console.dir(parent); //> RxDocument

await myDatabase.addCollections({
  todos: {
    schema: {
      version: 0,
      primaryKey: 'id',
      type: 'object',
      properties: {
        id: {
          type: 'string',
          maxLength: 100
        },
        name: {
          type: 'string'
        },
        subtasks: {
          type: 'array',
          ref: 'todos',
          items: {
              type: 'string'
          }
        }
      },
      required: ['id', 'name']
    }
  } 
});

//[insert the subtasks todo2, todo3 and todo4 here]

await myDatabase.todos.insert({
  id: 'todo1',
  name: 'Learn RxDB',
  subtasks: [
    'todo2',
    'todo3',
    'todo4'
  ]
});

const doc = await myDatabase.todos.findOne('todo1').exec();
const subtasks = await doc.subtasks_;
console.dir(subtasks); //> Array.<RxDocument>

import { addRxPlugin } from 'rxdb';
import { RxDBQueryBuilderPlugin } from 'rxdb/plugins/query-builder';
addRxPlugin(RxDBQueryBuilderPlugin);

// selector: { priority: { $gt: 5 } }
const query = myDatabase.todos.find().where('priority').gt(5);
const results = await query.exec();
// > [RxDocument[todo1], RxDocument[todo3]]

// selector: { priority: { $gte: 3, $lte: 8 }, done: { $eq: false } }
const results = await myDatabase.todos.find()
    .where('priority').gte(3).lte(8)
    .where('done').eq(false)
    .exec();
// > [RxDocument[todo1]]

// selector: { 'assignee.name': { $eq: 'Alice' } }
const results = await myDatabase.todos.find()
    .where('assignee.name').eq('Alice')
    .exec();
// > [RxDocument[todo1]]

// selector: { done: false, priority: { $gt: 5 } }
const results = await myDatabase.todos.find()
    .where({
        done: false,
        priority: { $gt: 5 }
    })
    .exec();
// > [RxDocument[todo1], RxDocument[todo3]]

// selector: { assignee: { $exists: false } }
const results = await myDatabase.todos.find()
    .where('assignee').exists(false)
    .exec();
// > [RxDocument[todo3], RxDocument[todo4]]

// sql equivalent of LIKE '%RxDB%'
const results = await myDatabase.todos.find()
    .where('name').regex('.*RxDB.*')
    .exec();
// > [RxDocument[todo1]]

// case insensitive: matches 'learn rxdb', 'LEARN RXDB', 'Learn RxDB' and so on
const caseInsensitiveResults = await myDatabase.todos.find()
    .where('name').regex({ $regex: '^learn rxdb$', $options: 'i' })
    .exec();
// > [RxDocument[todo1]]

// selector: { tags: { $size: 2 } }
const results = await myDatabase.todos.find()
    .where('tags').size(2)
    .exec();
// > [RxDocument[todo1], RxDocument[todo3]]

// todos with at least one tag that starts with 'back'
// selector: { tags: { $elemMatch: { $regex: '^back' } } }
const results = await myDatabase.todos.find()
    .where('tags').elemMatch({ $regex: '^back' })
    .exec();
// > [RxDocument[todo3]]

// todos that have both the 'rxdb' and the 'learning' tag
// selector: { $and: [ { tags: 'rxdb' }, { tags: 'learning' } ] }
const results = await myDatabase.todos.find()
    .and([
        { tags: 'rxdb' },
        { tags: 'learning' }
    ])
    .exec();
// > [RxDocument[todo1]]

// todos that are done or have a priority of 9 or higher
// selector: { $or: [ { done: true }, { priority: { $gte: 9 } } ] }
const results = await myDatabase.todos.find()
    .or([
        { done: true },
        { priority: { $gte: 9 } }
    ])
    .exec();
// > [RxDocument[todo2], RxDocument[todo3]]

// open todos that are neither tagged 'home' nor have a priority below 2
/**
 * selector: {
 *   done: { $eq: false },
 *   $nor: [ { tags: 'home' }, { priority: { $lt: 2 } } ]
 * }
 */
const results = await myDatabase.todos.find()
    .where('done').eq(false)
    .nor([
        { tags: 'home' },
        { priority: { $lt: 2 } }
    ])
    .exec();
// > [RxDocument[todo1], RxDocument[todo3]]

const results = await myDatabase.todos.find()
    .sort('-priority name')
    .exec();
// > [RxDocument[todo3], RxDocument[todo1], RxDocument[todo2], RxDocument[todo4]]

const sameResults = await myDatabase.todos.find()
    .sort({ priority: 'desc', name: 'asc' })
    .exec();

// the second page with 2 todos per page
const results = await myDatabase.todos.find()
    .sort('-priority')
    .skip(2)
    .limit(2)
    .exec();
// > [RxDocument[todo2], RxDocument[todo4]]

// the todo with the highest priority above 5
const doc = await myDatabase.todos.findOne()
    .where('priority').gt(5)
    .sort('-priority')
    .exec();
// > RxDocument[todo3]

const openTodosQuery = myDatabase.todos.find({
    selector: {
        done: false
    }
});

// selector: { done: false, priority: { $gte: 8 } }
const urgentOpenTodos = await openTodosQuery
    .where('priority').gte(8)
    .exec();
// > [RxDocument[todo1], RxDocument[todo3]]

// openTodosQuery is unchanged

/**
 * {
 *   selector: {
 *     done: { $eq: false },
 *     priority: { $gte: 5 },
 *     tags: { $in: ['rxdb'] },
 *     $or: [ { 'assignee.name': 'Alice' }, { note: { $exists: false } } ]
 *   },
 *   sort: [ { priority: 'desc' } ],
 *   limit: 10
 * }
 */
const query = myDatabase.todos.find()
    .where('done').eq(false)
    .where('priority').gte(5)
    .where('tags').in(['rxdb'])
    .or([
        { 'assignee.name': 'Alice' },
        { note: { $exists: false } }
    ])
    .sort('-priority')
    .limit(10);

// emits the current results and again whenever they change
query.$.subscribe(todos => console.dir(todos));
// > [RxDocument[todo3], RxDocument[todo1]]

const collection = await myDatabase.addCollections({
    humans: {
        schema: mySchema,
        cacheReplacementPolicy: function(){ /* ... */ }
    }
});

import {
    findBestIndex
} from 'rxdb-premium/plugins/query-optimizer';

import { 
    getRxStorageIndexedDB
} from 'rxdb-premium/plugins/storage-indexeddb';

const bestIndexes = await findBestIndex({
    schema: myRxJsonSchema, // see Schema Validation
    /**
     * In this example we use the IndexedDB RxStorage,
     * but any other storage can be used for testing.
     */
    storage: getRxStorageIndexedDB(),
    /**
     * Multiple queries can be optimized at the same time
     * which decreases the overall runtime.
     */
    queries: {
        /**
         * Queries can be mapped by a query id,
         * here we use myFirstQuery as query id.
         */
        myFirstQuery: {
            selector: {
                age: {
                    $gt: 10
                }
            },
        },
        mySecondQuery: {
            selector: {
                age: {
                    $gt: 10
                },
                lastName: {
                    $eq: 'Nakamoto'
                }
            },
        }
    },
    testData: [/** data for the documents. **/]
});

npm install rxdb rxjs react-native-quick-sqlite

import { createRxDatabase } from 'rxdb';
import {
    getRxStorageSQLite,
    getSQLiteBasicsQuickSQLite
} from 'rxdb-premium/plugins/storage-sqlite';
import { open } from 'react-native-quick-sqlite';

const db = await createRxDatabase({
    name: 'mydatabase',
    storage: getRxStorageSQLite({
        sqliteBasics: getSQLiteBasicsQuickSQLite(open)
    }),
    multiInstance: false,
    ignoreDuplicate: true
});

npx expo install expo-sqlite
npm install rxdb rxjs

import { createRxDatabase } from 'rxdb';
import {
    getRxStorageSQLite,
    getSQLiteBasicsExpoSQLiteAsync
} from 'rxdb-premium/plugins/storage-sqlite';
import * as SQLite from 'expo-sqlite';

const db = await createRxDatabase({
    name: 'mydatabase',
    storage: getRxStorageSQLite({
        sqliteBasics: getSQLiteBasicsExpoSQLiteAsync(SQLite.openDatabaseAsync)
    }),
    multiInstance: false,
    ignoreDuplicate: true
});

import { RxDatabaseProvider } from 'rxdb/plugins/react';

export default function App() {
  // ... create db instance
  return (
    <RxDatabaseProvider database={db}>
       <MyComponent />
    </RxDatabaseProvider>
  );
}

import { useRxCollection, useLiveRxQuery } from 'rxdb/plugins/react';

function TaskList() {
  const collection = useRxCollection('tasks');
  
  // This hook automatically updates 'tasks' whenever the query result changes
  const { result: tasks } = useLiveRxQuery(
    collection.find({
        selector: {
            done: { $eq: false }
        },
        sort: [{ createdAt: 'asc' }]
    })
  );

  return (
    <FlatList
      data={tasks}
      renderItem={({ item }) => <Text>{item.title}</Text>}
      keyExtractor={item => item.id}
    />
  );
}

// Enable the signals plugin once
import { addRxPlugin } from 'rxdb';
import {
    RxDBReactivityPreactSignalsPlugin
} from 'rxdb/plugins/reactivity-preact-signals';
addRxPlugin(RxDBReactivityPreactSignalsPlugin);

// ... in your component
const signals = collection.find().$$; // Returns a Signal<Doc[]>

import { replicateSupabase } from 'rxdb/plugins/replication-supabase';

const replicationState = replicateSupabase({
    replicationIdentifier: 'my-sync',
    collection: db.tasks,
    supabaseClient: supabase,
    pull: {},
    push: {},
});

npm install rxdb react react-dom

import {
    createRxDatabase,
    addRxPlugin
} from 'rxdb';
import {
    getRxStorageLocalstorage
} from 'rxdb/plugins/storage-localstorage';

async function getDatabase() {
    const db = await createRxDatabase({
        name: 'heroesreactdb',
        storage: getRxStorageLocalstorage()
    });
    await db.addCollections({
        heroes: {
            schema: myRxSchema
        }
    });

    /**
     * Do other stuff here
     * like setting up middleware
     * or starting replication.
     */

    return db;
}

import React, { useEffect, useState } from 'react';
import { RxDatabaseProvider } from 'rxdb/plugins/react';
import { getDatabase } from './Database';


const App = () => {
    const [database, setDatabase] = useState();

    useEffect(() => {
        const initDb = async () => {
            const db = await getDatabase();
            setDatabase(db);
        };
        initDb();
    }, []);

    if (database == null) {
        return <span>
            Loading <a href="https://rxdb.info/react.html">RxDB</a> database...
        </span>;
    }

    return (
        <RxDatabaseProvider database={database}>
            {/* your application */}
        </RxDatabaseProvider>
    );
};

export default App;

import { useRxCollection } from 'rxdb/plugins/react';

const collection = useRxCollection('heroes');

import { useRxQuery } from 'rxdb/plugins/react';

const query = {
    collection: 'heroes',
    query: {
        selector: {},
        sort: [{ name: 'asc' }]
    }
};

const HeroCount = () => {
    const { results, loading } = useRxQuery(query);

    if (loading) {
        return <span>Loading...</span>;
    }

    return <span>Total heroes: {results.length}</span>;
};

import { useLiveRxQuery } from 'rxdb/plugins/react';

const query = {
    collection: 'heroes',
    query: {
        selector: {},
        sort: [{ name: 'asc' }]
    }
};

const HeroList = () => {
    const { results, loading } = useLiveRxQuery(query);

    if (loading) {
        return <span>Loading...</span>;
    }

    return (
        <ul>
            {results.map(hero => (
                <li key={hero.name}>{hero.name}</li>
            ))}
        </ul>
    );
};

import { useRxCollection } from 'rxdb/plugins/react';
import { useRxDocument } from 'rxdb/plugins/react';

const HeroDetail = ({ heroId }: { heroId: string }) => {
    const collection = useRxCollection('heroes');
    const { result: hero, loading } = useRxDocument(collection, heroId);

    if (loading || !hero) {
        return <span>Loading...</span>;
    }

    return <span>{hero.name} ({hero.color})</span>;
};

import { useReplicationStatus } from 'rxdb/plugins/react';

const SyncIndicator = ({ replicationState }) => {
    const status = useReplicationStatus(replicationState);
    const { syncing, error, lastSyncedAt, canceled } = status;

    if (canceled) return <span>Sync stopped</span>;
    if (error) return <span>Sync error: {error.message}</span>;
    if (syncing) return <span>Syncing...</span>;
    if (lastSyncedAt) {
        const time = new Date(lastSyncedAt).toLocaleTimeString();
        return <span>Last synced: {time}</span>;
    }

    return <span>Idle</span>;
};

import { createReactivityFactory } from 'rxdb/plugins/reactivity-angular';
import { Injectable, inject } from '@angular/core';

const database = await createRxDatabase({
    name: 'mydb',
    storage: getRxStorageLocalstorage(),
    reactivity: createReactivityFactory(inject(Injector))
});

// add collections/sync etc...

import { Component, inject } from '@angular/core';
import { CommonModule } from '@angular/common';
import { DbService } from '../db.service';

@Component({
  selector: 'app-todos-list',
  standalone: true,
  imports: [CommonModule],
  template: `
      <ul>
        <li
          *ngFor="let t of todosSignal();"
        >{{ t.title }}</li>
      </ul>
  `,
})
export class TodosListComponent {
  private dbService = inject(DbService);

  // RxDB query - Angular Signal
  readonly todosSignal = this.dbService.db.todos.find().$$;
}

npm install @preact/signals-core --save

import {
  PreactSignalsRxReactivityFactory
} from 'rxdb/plugins/reactivity-preact-signals';

const database = await createRxDatabase({
    name: 'mydb',
    storage: getRxStorageLocalstorage(),
    reactivity: PreactSignalsRxReactivityFactory
});

// add collections/sync etc...

import { useEffect, useState } from 'preact/hooks';
import { getDatabase } from './db';

export function TodosList() {
  const [db, setDb] = useState(null);

  useEffect(() => {
    getDatabase().then(setDb);
  }, []);

  if (!db) return null;

  // RxQuery -> Preact Signal
  const todosSignal = db.todos.find().$$;

  return (
    <ul>
      {todosSignal.value.map((doc: any) => (
        <li key={doc.primary}>
            {doc.title}
        </li>
      ))}
    </ul>
  );
}

import { VueRxReactivityFactory } from 'rxdb/plugins/reactivity-vue';

const database = await createRxDatabase({
    name: 'mydb',
    storage: getRxStorageLocalstorage(),
    reactivity: VueRxReactivityFactory
});

// add collections/sync etc...

<script setup lang="ts">
import { getDatabase } from './db';

const db = getDatabase();

// RxQuery to Vue shallowRef signal
const todosSignal = db.todos.find().$$;
</script>

<template>
  <ul>
    <li v-for="t in todosSignal" :key="t.primary">
      <label>{{ t.title }}</label>
    </li>
  </ul>
</template>

// RxDocument

// get signal that represents the document field 'foobar'
const signal = myRxDocument.get$$('foobar');

// same as above
const signal = myRxDocument.foobar$$;

// get signal that represents whole document over time
const signal = myRxDocument.$$;

// get signal that represents the deleted state of the document
const signal = myRxDocument.deleted$$;

// RxQuery

// get signal that represents the query result set over time
const signal = collection.find().$$;

// get signal that represents the query result set over time
const signal = collection.findOne().$$;

// RxLocalDocument

// get signal that represents the whole local document state
const signal = myRxLocalDocument.$$;

// get signal that represents the foobar field
const signal = myRxLocalDocument.get$$('foobar');

<VideoBox videoId="L07xPMyL8sY" title="Appwrite in 100 Seconds" duration="2:35" />

docker-compose -v

docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
    --entrypoint="install" \
    appwrite/appwrite:1.6.1

# stop
docker-compose down

# start
docker-compose up

<VideoBox videoId="HGlBpna17LQ" title="Appwrite Database Tutorial" duration="9:47" startAt={328} />

npm install appwrite rxdb

import {
    replicateAppwrite
} from 'rxdb/plugins/replication-appwrite';
import {
    createRxDatabase,
    addRxPlugin,
    RxCollection
} from 'rxdb/plugins/core';
import {
    getRxStorageLocalstorage
} from 'rxdb/plugins/storage-localstorage';

import { Client } from 'appwrite';

const myDatabase = await createRxDatabase({
    name: 'mydb',
    storage: getRxStorageLocalstorage()
});
const todoSchema = {
    title: 'todo schema',
    version: 0,
    primaryKey: 'id',
    type: 'object',
    properties: {
        id: {
            type: 'string',
            maxLength: 100
        },
        name: {
            type: 'string'
        },
        done: {
            type: 'boolean',
            default: false
        },
        priority: {
            type: 'integer',
            minimum: 0,
            maximum: 10,
            multipleOf: 1
        }
    },
    required: ['id', 'name', 'done', 'priority']
};
await myDatabase.addCollections({
    todos: {
        schema: todoSchema
    }
});
const collection = myDatabase.todos;

const client = new Client();
client.setEndpoint('https://cloud.appwrite.io/v1');
client.setProject('YOUR_APPWRITE_PROJECT_ID');

const client = new Client();
client.setEndpoint('http://localhost/v1');
client.setProject('YOUR_APPWRITE_PROJECT_ID');

const replicationState = replicateAppwrite({
    replicationIdentifier: 'my-appwrite-replication',
    client,
    databaseId: 'YOUR_APPWRITE_DATABASE_ID',
    collectionId: 'YOUR_APPWRITE_COLLECTION_ID',
    deletedField: 'deleted', // Field that represents deletion in Appwrite
    collection,
    pull: {
        batchSize: 10,
    },
    push: {
        batchSize: 10
    },
    /*
     * ...
     * You can set all other options for RxDB replication states
     * like 'live' or 'retryTime'
     * ...
     */
});

/* Detailed source-code truncated for AI context efficiency. */

const myCustomFetch = (url, options) => {

    // flat clone the given options to not mutate the input
    const optionsWithAuth = Object.assign({}, options);
    // ensure the headers property exists
    if(!optionsWithAuth.headers) {
        optionsWithAuth.headers = {};
    }
    // add bearer token to headers
    optionsWithAuth.headers['Authorization'] ='Basic S0VLU0UhIExFQ0...';

    // call the original fetch function with our custom options.
    return fetch(
        url,
        optionsWithAuth
    );
};

const replicationState = replicateCouchDB(
    {
        replicationIdentifier: 'my-couchdb-replication',
        collection: myRxCollection,
        url: 'http://example.com/db/humans',
        /**
         * Add the custom fetch function here.
         */
        fetch: myCustomFetch,
        pull: {},
        push: {}
    }
);

replicationState.fetch = newCustomFetchMethod;

import { 
    replicateCouchDB,
    getFetchWithCouchDBAuthorization
} from 'rxdb/plugins/replication-couchdb';

const replicationState = replicateCouchDB(
    {
        replicationIdentifier: 'my-couchdb-replication',
        collection: myRxCollection,
        url: 'http://example.com/db/humans',
        /**
         * Add the custom fetch function here.
         */
        fetch: getFetchWithCouchDBAuthorization('myUsername', 'myPassword'),
        pull: {},
        push: {}
    }
);

server {
    http2 on;
    location /db {
        rewrite /db/(.*) /$1 break;
        proxy_pass http://172.0.0.1:5984;
        proxy_redirect off;
        proxy_buffering off;
        proxy_set_header Host            $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded;
        proxy_set_header Connection "keep_alive";
    }
}

// create a 'humans' CouchDB database on the server
const remoteDatabaseName = 'humans';
await fetch(
    'http://example.com/db/' + remoteDatabaseName,
    {
        method: 'PUT'
    }
);

import crossFetch from 'cross-fetch';
const replicationState = replicateCouchDB(
    {
        replicationIdentifier: 'my-couchdb-replication',
        collection: myRxCollection,
        url: 'http://example.com/db/humans',
        fetch: crossFetch,
        pull: {},
        push: {}
    }
);

npm install firebase

import * as firebase from 'firebase/app';
import {
    getFirestore,
    collection
} from 'firebase/firestore';

const projectId = 'my-project-id';
const app = firebase.initializeApp({
    projectId,
    databaseURL: 'http://localhost:8080?ns=' + projectId,
    /* ... */
});
const firestoreDatabase = getFirestore(app);
const firestoreCollection = collection(firestoreDatabase, 'my-collection-name');

const replicationState = replicateFirestore({
    replicationIdentifier: `https://firestore.googleapis.com/${projectId}`,
    collection: myRxCollection,
    firestore: {
        projectId,
        database: firestoreDatabase,
        collection: firestoreCollection
    },
    /**
     * (required) Enable push and pull replication with firestore by
     * providing an object with optional filter
     * for each type of replication desired.
     * [default=disabled]
     */
    pull: {},
    push: {},
    /**
     * Either do a live or a one-time replication
     * [default=true]
     */
    live: true,
    /**
     * (optional) likely you should just use the default.
     *
     * In firestore it is not possible to read out
     * the internally used write timestamp of a document.
     * Even if we could read it out, it is not indexed which
     * is required for fetch 'changes-since-x'.
     * So instead we have to rely on a custom user defined field
     * that contains the server time
     * which is set by firestore via serverTimestamp()
     * Notice that the serverTimestampField MUST NOT be
     * part of the collections RxJsonSchema!
     * [default='serverTimestamp']
     */
    serverTimestampField: 'serverTimestamp'
});

import {
    getDocs,
    query,
    where,
    serverTimestamp
} from 'firebase/firestore';
const allDocsResult = await getDocs(query(firestoreCollection));
allDocsResult.forEach(doc => {
    doc.update({
        _deleted: false,
        serverTimestamp: serverTimestamp()
    })
});

const replicationState = replicateFirestore(
    {
        collection: myRxCollection,
        firestore: {
            projectId,
            database: firestoreDatabase,
            collection: firestoreCollection
        },
        pull: {
            filter: [
                where('ownerId', '==', userId)
            ]
        },
        push: {
            filter: (item) => item.syncEnabled === true
        }
    }
);

import { replicateGoogleDrive } from 'rxdb/plugins/replication-google-drive';

const replicationState = await replicateGoogleDrive({
    replicationIdentifier: 'my-app-drive-sync',
    collection: myDatabase.todos, // RxCollection
    googleDrive: {
        oauthClientId: 'YOUR_GOOGLE_CLIENT_ID',
        authToken: 'USER_ACCESS_TOKEN',
        folderPath: 'my-app-data/user-1'
    },
    live: true,
    pull: {
        batchSize: 60,
        modifier: doc => doc // (optional) modify invalid data
    },
    push: {
        batchSize: 60,
        modifier: doc => doc // (optional) modify before sending
    }
});

// Observe replication states
replicationState.error$.subscribe(err => {
    console.error('Replication error:', err);
});

replicationState.awaitInitialReplication().then(() => {
    console.log('Initial replication done');
});

import nodeDatachannelPolyfill from 'node-datachannel/polyfill';
import { createSimplePeerWrtc } from 'rxdb/plugins/replication-webrtc';
// ...
const replicationState = await replicateGoogleDrive({
    // ...
    signalingOptions: {
        wrtc: createSimplePeerWrtc(nodeDatachannelPolyfill)
    }
});

const replicationState = await replicateGoogleDrive({
    replicationIdentifier: 'my-app-drive-sync',
    collection: myDatabase.todos,
    googleDrive: {
        oauthClientId: 'YOUR_GOOGLE_CLIENT_ID',
        authToken: 'USER_ACCESS_TOKEN',
        space: 'appDataFolder'
        // folderPath is optional here
    },
    live: true,
    pull: {},
    push: {}
});

const replicationState = await replicateGoogleDrive({
    // ...
    attachments: false, // disable attachment replication
    pull: {},
    push: {}
});

input HumanInput {
    id: ID!,
    name: String!,
    lastName: String!,
    updatedAt: Float!,
    deleted: Boolean!
}
type Human {
    id: ID!,
    name: String!,
    lastName: String!,
    updatedAt: Float!,
    deleted: Boolean!
}
input Checkpoint {
    id: String!,
    updatedAt: Float!
}
type HumanPullBulk {
    documents: [Human]!
    checkpoint: Checkpoint
}

type Query {
    pullHuman(checkpoint: Checkpoint, limit: Int!): HumanPullBulk!
}

input HumanInputPushRow {
    assumedMasterState: HeroInputPushRowT0AssumedMasterStateT0
    newDocumentState: HeroInputPushRowT0NewDocumentStateT0!
}

type Mutation {
    # Returns a list of all conflicts
    # If no document write caused a conflict, return an empty list.
    pushHuman(rows: [HumanInputPushRow!]): [Human]
}

# headers are used to authenticate the subscriptions
# over websockets.
input Headers {
    AUTH_TOKEN: String!;
}
type Subscription {
    streamHuman(headers: Headers): HumanPullBulk!
}

/* Detailed source-code truncated for AI context efficiency. */

const pullQueryBuilder = (checkpoint, limit) => {
    /**
     * The first pull does not have a checkpoint
     * so we fill it up with defaults
     */
    if (!checkpoint) {
        checkpoint = {
            id: '',
            updatedAt: 0
        };
    }
    const query = `query PullHuman($checkpoint: CheckpointInput, $limit: Int!) {
        pullHuman(checkpoint: $checkpoint, limit: $limit) {
            documents {
                id
                name
                age
                updatedAt
                deleted
            }
            checkpoint {
                id
                updatedAt
            }
        }
    }`;
    return {
        query,
        operationName: 'PullHuman',
        variables: {
            checkpoint,
            limit
        }
    };
};

/* Detailed source-code truncated for AI context efficiency. */

const pushQueryBuilder = rows => {
    const query = `
    mutation PushHuman($writeRows: [HumanInputPushRow!]) {
        pushHuman(writeRows: $writeRows) {
            id
            name
            age
            updatedAt
            deleted
        }
    }
    `;
    const variables = {
        writeRows: rows
    };
    return {
        query,
        operationName: 'PushHuman',
        variables
    };
};

const replicationState = replicateGraphQL(
    {
        collection: myRxCollection,
        // urls to the GraphQL endpoints
        url: {
            http: 'http://example.com/graphql'
        },
        push: {
            queryBuilder: pushQueryBuilder, // the queryBuilder from above
            /**
             * batchSize (optional)
             * Amount of document that will be pushed
             * to the server in a single request.
             */
            batchSize: 5,
            /**
             * modifier (optional)
             * Modifies all pushed documents before
             * they are sent to the GraphQL endpoint.
             * Returning null will skip the document.
             */
            modifier: doc => doc
        },
        headers: {
            Authorization: 'Bearer abcde...'
        },
        pull: {
            /* ... */
        },
        /* ... */
    }
);

const pullStreamQueryBuilder = (headers) => {
    const query = `subscription onStream($headers: Headers) {
        streamHero(headers: $headers) {
            documents {
                id,
                name,
                age,
                updatedAt,
                deleted
            },
            checkpoint {
                id
                updatedAt
            }
        }
    }`;
    return {
        query,
        variables: {
            headers
        }
    };
};

/* Detailed source-code truncated for AI context efficiency. */

const replicationState: RxGraphQLReplicationState<RxDocType> = replicateGraphQL(
    {
        collection: myRxCollection,
        url: {/* ... */},
        headers: {/* ... */},
        push: {/* ... */},
        pull: {
            queryBuilder: pullQueryBuilder,
            modifier: (doc => {
                // We have to remove optional non-existent field values
                // they are set as null by GraphQL but should be undefined
                Object.entries(doc).forEach(([k, v]) => {
                    if (v === null) {
                        delete doc[k];
                    }
                });
                return doc;
            })
        },
        /* ... */
    }
);

import {

} from 'rxdb';
const replicationState: RxGraphQLReplicationState<RxDocType> = replicateGraphQL(
    {
        collection: myRxCollection,
        url: {/* ... */},
        headers: {/* ... */},
        push: {/* ... */},
        pull: {
            responseModifier: async function(
                plainResponse, // the exact response that was returned from the server
                // either 'handler' if plainResponse
                // came from the pull.handler,
                // or 'stream' if it came from
                // the pull.stream
                origin,
                // if origin==='handler', the
                // requestCheckpoint contains the
                // checkpoint that was sent to
                // the backend
                requestCheckpoint
            ) {
                /**
                 * In this example we aggregate the
                 * checkpoint from the documents array
                 * that was returned from the graphql endpoint.
                 */
                const docs = plainResponse;
                return {
                    documents: docs,
                    checkpoint: docs.length === 0 ? requestCheckpoint : {
                        name: lastOfArray(docs).name,
                        updatedAt: lastOfArray(docs).updatedAt
                    }
                };
            }
        },
        /* ... */
    }
);

type PushResponse {
    conflicts: [Human]
    conflictMessages: [ReplicationConflictMessage]
}

type Mutation {
    # Returns a PushResponse type that contains
    # the conflicts along with other information
    pushHuman(rows: [HumanInputPushRow!]): PushResponse!
}

import {} from "rxdb";
const replicationState: RxGraphQLReplicationState<RxDocType> = replicateGraphQL(
    {
        collection: myRxCollection,
        url: {/* ... */},
        headers: {/* ... */},
        push: {
            responseModifier: async function (plainResponse) {
                /**
                 * In this example we aggregate the
                 * conflicting documents from a
                 * response object
                 */
                return plainResponse.conflicts;
            },
        },
        pull: {/* ... */},
        /* ... */
    }
);

replicationState.setHeaders({
    Authorization: `...`
});