RxDB on FoundationDB

On this page

FoundationDB is a distributed key-value store designed to handle large volumes of structured data across clusters of computers while maintaining high levels of performance, scalability, and fault tolerance. While FoundationDB itself only can store and query key-value pairs, it lacks more advanced features like complex queries, encryption and replication.

With the FoundationDB based RxStorage of RxDB you can combine the benefits of FoundationDB while having a fully featured, high performance NoSQL database.

Features of RxDB+FoundationDB​

Using RxDB on top of FoundationDB, gives you many benefits compare to using the plain FoundationDB API:

• Indexes : In RxDB with a FoundationDB storage layer, indexes are used to optimize query performance, allowing for fast and efficient data retrieval even in large datasets. You can define single and compound indexes with the RxDB schema.
• Schema Based Data Model : Utilizing a jsonschema based data model, the system offers a highly structured and versatile approach to organizing and validating data, ensuring consistency and clarity in database interactions.
• Complex Queries : The system supports complex NoSQL queries, allowing for advanced data manipulation and retrieval, tailored to specific needs and intricate data relationships. For example you can do $regex or $or queries which is hardly possible with the plain key-value access of FoundationDB.
• Observable Queries & Documents : RxDB's observable queries and documents feature ensures real-time updates and synchronization, providing dynamic and responsive data interactions in applications.
• Compression : RxDB employs data compression techniques to reduce storage requirements and enhance transmission efficiency, making it more cost-effective and faster, especially for large volumes of data. You can compress the NoSQL document data, but also the binary attachments data.
• Attachments : RxDB supports the storage and management of attachments which allowing for the seamless inclusion of binary data like images or documents alongside structured data within the database.

Installation​

• Install the FoundationDB client cli which is used to communicate with the FoundationDB cluster.
• Install the FoundationDB node bindings npm module via npm install foundationdb. This will install v2.x.x, which is only compatible with FoundationDB server and client v7.3.x (which is the only version currently maintained by the FoundationDB team). If you need to use an older version (e.g. 7.1.x or 6.3.x), you should run npm install [email protected] (though this might only work with v6.3.x).
• Due to an outstanding bug in node foundationdb, you will need to specify an apiVersion of 720 even though you are using 730. When this PR is merged, you will be able to use 730.

Usage​

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

const db = await createRxDatabase({
    name: 'exampledb',
    storage: getRxStorageFoundationDB({
        /**
         * Version of the API of the FoundationDB cluster..
         * FoundationDB is backwards compatible across a wide range of versions,
         * so you have to specify the api version.
         * If in doubt, set it to 720.
         */
        apiVersion: 720,
        /**
         * Path to the FoundationDB cluster file.
         * (optional)
         * If in doubt, leave this empty to use the default location.
         */
        clusterFile: '/path/to/fdb.cluster',
        /**
         * Amount of documents to be fetched in batch requests.
         * You can change this to improve performance depending on
         * your database access patterns.
         * (optional)
         * [default=50]
         */
        batchSize: 50
    })
});

Multi Instance​

Because FoundationDB does not offer a changestream, it is not possible to use the same cluster from more than one Node.js process at the same time. For example you cannot spin up multiple servers with RxDB databases that all use the same cluster. There might be workarounds to create something like a FoundationDB changestream and you can make a Pull Request if you need that feature.

Running the FoundationDB Server with Docker​

Instead of installing the FoundationDB server locally, you can run it in a Docker container. This is the recommended approach for local development and CI environments.

# Pull the Docker image
docker pull foundationdb/foundationdb:7.3.59

# Start the container with host networking
docker run -d \
    --name rxdb-foundationdb \
    --network host \
    -e FDB_NETWORKING_MODE=host \
    foundationdb/foundationdb:7.3.59

# Copy the cluster file from the container
sudo mkdir -p /etc/foundationdb
docker cp rxdb-foundationdb:/var/fdb/fdb.cluster /etc/foundationdb/fdb.cluster

# Configure the database
fdbcli --exec "configure new single memory" --timeout 30

You can also use the provided npm scripts:

npm run foundationdb:start # Starts the Docker container and configures the database
npm run foundationdb:stop # Stops and removes the Docker container