Using the Server Plugin
In this tutorial you learn how to use the CouchDB server plugin and replicate data from a node-process to the client. It starts a server that is compatible with the CouchDB replication protocol.
NOTICE: The CouchDB server plugin can only be used with the PouchDB RxStorage.
The CouchDB server plugin is useful
- To simulate the couchdb in developer-mode without setting up a real one
- To replicate data between the renderer and the node-process in an electron-app
- To fast spin up a prototype-app without having to define an API
It should never be used openly accessible to the internet, use a couchdb-instance at production.
In NodeJs
Because the server plugin only works in node, it is not part of the default rxdb-build. You have to import it before you can use it.
// run 'npm install express-pouchdb' before you use the server plugin.
// add the server-plugin
import { addRxPlugin } from 'rxdb';
import { RxDBServerCouchDBPlugin } from 'rxdb/plugins/server-couchdb';
addRxPlugin(RxDBServerCouchDBPlugin);
// add the PouchDB memory-adapter
import { addPouchPlugin } from 'rxdb/plugins/pouchdb';
import * as MemoryAdapter from 'pouchdb-adapter-memory';
addPouchPlugin(MemoryAdapter);
You also have to install the module express-pouchdb
which does not come with RxDB.
npm install express-pouchdb --save
Now we can create a database and a collection.
import { createRxDatabase, getRxStoragePouch } from 'rxdb';
// create database
const db = await createRxDatabase({
name: 'mydb',
storage: getRxStoragePouch('memory')
});
// create collection
const mySchema = {
version: 0,
type: 'object',
primaryKey: 'key',
properties: {
key: {
type: 'string'
},
value: {
type: 'string'
}
},
required: ['key']
};
await db.addCollections({
items: {
schema: mySchema
}
});
// insert one document
await db.items.insert({
key: 'foo',
value: 'bar'
});
Now we can spawn the server. Besides the RxDB specific options, you can set pouchdbExpressOptions
which are defined by the express-pouchdb module.
/**
* Start the server.
*/
const {app, server} = await db.serverCouchDB({
path: '/db', // (optional)
port: 3000, // (optional)
cors: true, // (optional), enable CORS-headers
startServer: true, // (optional), start express server
// options of the pouchdb express server
pouchdbExpressOptions: {
inMemoryConfig: true, // do not write a config.json
logPath: '/tmp/rxdb-server-log.txt' // save logs in tmp folder
}
});
To ensure that everything is ok,
- Open http://localhost:3000/db to get the database-info
- Open http://localhost:3000/db/items to get the collection-info
Server as a part of bigger Express app
You can create server without starting it. It allows to use server as a part of bigger Express app.
const {app, server} = await db.serverCouchDB({
path: '/', // omitted when startServer is false and force set to /
port: 3000, // omitted when startServer is false
cors: false, // disable CORS-headers (default) - you probably want to configure CORS in your main app
startServer: false // do not start express server
});
Then you can mount rxdb server express app in your express app
const { app, server } = await db.serverCouchDB({
startServer: false
});
const mainApp = express();
// configure CORS, other middlewares...
mainApp.use('/db', app);
mainApp.use('/', (req, res) => res.send('hello'));
mainApp.listen(3000, () => console.log(`Server listening on port 3000`));
To ensure that everything is ok,
- Open http://localhost:3000/db to get the database-info
- Open http://localhost:3000/db/items to get the collection-info
On the client
On the client you can now also create a database and replicate it with our server.
Start with creating the database and collection.
import { createRxDatabase, getRxStoragePouch } from 'rxdb';
import { addPouchPlugin } from 'rxdb/plugins/pouchdb';
// we need the http-plugin to relicate over http
import * as PouchHttpPlugin from 'pouchdb-adapter-http';
addPouchPlugin(PouchHttpPlugin);
const clientDB = await createRxDatabase({
name: 'clientdb',
storage: getRxStoragePouch('memory')
});
// create a collection
await clientDB.addCollections({
items: {
schema: mySchema
}
});
Now you replicate the client collection with the server.
clientDB.items.syncCouchDB({
remote: 'http://localhost:3000/db/items'
});
After the replication is in sync, the client has the same documents as the server.
const docs = await clientDB.items.find().exec();