home shape

Arangochair – a tool for listening to changes in ArangoDB

The ArangoDB team gave me an opportunity to write a tutorial about arangochair. Arangochair is the first attempt to listen for changes in the database and execute actions like pushing a document to the client or execute an AQL query. Currently it is limited to single nodes.

This tutorial is loosely based on the example at baslr/arangochair-serversendevents-demo

arangochair is a Node.js module hosted on npm which make it fairly easy to install. Just run
npm install arangochair and its installed.

New to multi-model and graphs? Check out our free ArangoDB Graph Course.

Now we can write our first lines of code

We set up arangochair to listen for changes on the collection tweets and construct a server send event (SSE) message and sent it to all connected sockets. The SSE consists of two lines per message. The first line is the event and the second line is a stringified linke of JSON.

const changes = new arangochair(''); // ArangoDB node to monitor

changes.on('tweets', (docIn, type) => {
    const doc = JSON.parse(docIn);

    const message = 'event: ' + type + '\ndata: ' + JSON.stringify(doc) + '\n\n';
    for(const sse of sses) {

no4.on('error', (err, httpStatus, headers, body) => {
    console.log('on error', err);
    // arangochair stops on errors
    // check last http request

On the client side we use the EventSource interface to listen for events that we send on the server.

First we construct a new EventSource and add two EventListeners to listen for insert/update and delete. Separate events for insert and update are currently not possible but will be part of a future update.

const events = new EventSource('/sse');

events.addEventListener('delete', (e) => {
      const doc = JSON.parse(e.data);
      // do something
}, false);
events.addEventListener('insert/update', (e) => {
      const doc = JSON.parse(e.data);
      // do something
}, false);

Handle socket connections on the server with express:

In this example we use express as our framework to handle api calls. We write a middleware that handles the socket of a client to receive SSEs. If the client connection ends we remove the socket from the array of stored sockets.

app.use( (req, res, next) => {
    if ('/sse' === req.url) {
        res.setHeader('Content-Type', 'text/event-stream');
        res.on('close', () => {
            const idx = sses.indexOf(res);
            if (-1 === idx) return;
            sses.splice(idx, 1);

        res.write('data: initial\n\n');
    } else {

Why not WebSockets?

Since we want only push data to the client we do not need a duplex connection. Also SSE uses a traditional HTTP connection without a special protocol and reconnects itself on connection loss.

Frank Celler

Frank Celler

Frank is both entrepreneur and backend developer, developing mostly memory databases for two decades. He is the CTO and co-founder of ArangoDB. Try to challenge Frank asking him questions on C, C++ and MRuby. Besides Frank organizes Cologne’s NoSQL group & is an active member of NoSQL community.


  1. Torlone Gianfranco on March 9, 2017 at 12:12 am

    is possible subscribe a query? in future ?

  2. Olivier BONNAURE on March 28, 2017 at 4:34 am

    Does SSE works with IE?

  3. Sanju Thomas on December 30, 2020 at 5:10 am

    Do we have similar functionality available with Java client API?

    • Willi Goesgens on January 15, 2021 at 9:38 am

      we know of users that have implemented it; Maybe you ask for it in the community slack and they are willing to share it?

Leave a Comment

Get the latest tutorials, blog posts and news: