Getting Started With DeltaDB

DeltaDB is an open source offline-first NoSQL database written in JavaScript. It is meant to be used in a front-end only design where the only backend needed is DeltaDB. The client writes to a local database and whenever the app is online it will sync with the database cloud.

Live Demos

Todos: an adaptation of todomvc-angular that uses DeltaDB

Hello: a Hello World app for getting started with DeltaDB

The Code

In a moment, you’ll be taken through the steps to create the Hello demo above. We’re going to do everything in the cloud so you won’t have to download a thing.

Before we dive into the code, let’s try something fun. Open two browser windows and in both of them visit DeltaDB Hello. You’ll now be able to simulate two different users simultaneously using the app. In the first window type hola and then visit the second window. Do you see how hola is displayed in both windows? DeltaDB did this automatically by syncing with the cloud. You can even turn off your internet connection, enter another greeting and then turn your internet connection back on and DeltaDB will sync the greeting again. This app works both offline and online. Pretty cool, right?

Let’s go line by line through the code to see how everything works. We’ll be referring to the code at DeltaDB Hello.

Load DeltaDB

We use a script tag to load DeltaDB. For now, the JS code is being served via a CDN, but you can also download this code and use it locally.

<script src="https://cdn.jsdelivr.net/deltadb/0.0.10/deltadb.min.js"></script>

The User Interface

We provide a way for the user to enter her/his greeting.

<h1>
DeltaDB says <input id="greeting-in" type="text"
                    onkeypress="onKeyPress(event)" />
</h1>

When the user presses enter, the onKeyPress function saves the greeting in the database. We’ll get to onKeyPress in a little bit.

We display the latest greeting:

<h3>
DeltaDB says <em id="greeting-out"></em>
</h3>

Create the Database

We name our database greetings-db and sync it with the cloud at https://delta-dev.deltadb.io

var db = new DeltaDB('greetings-db',
                     'https://delta-dev.deltadb.io');

As soon as we create our database, it is ready to be used. If the database doesn’t exist then DeltaDB will automatically create it, assuming you are authorized.

Create a Collection

A collection is a group of documents. We create a collection for all our greetings. If the collection doesn’t exist then it is created, otherwise the existing collection is loaded.

var greetings = db.col('greetings');

More serious apps have many types of documents so we use collections to keep all our docs organized.

Create the Document

We create a document with a static id of greeting-id so that all users reference the same shared doc. If the doc doesn’t exist then it is created, otherwise the existing doc is loaded:

var greeting = greetings.doc({ $id: 'greeting-id' });

Update the UI After the Doc is Loaded

DeltaDB stores the value of the document locally using IndexedDB or WebSQL. Loading data from these databases occurs asynchronously so we need to listen for the “load” event as it will tell us when any existing data has been loaded. The following code displays the latest greeting that was stored locally:

greeting.on('load', function () {
  document.getElementById('greeting-out').innerHTML =
    greeting.get('text');
});

This code allows the app to display the latest greeting even when we are offline.

Update the UI When There are Remote Changes

Whenever the greeting changes in the cloud, we receive an attr:update event. The following code displays the new greeting whenever it changes remotely. An attribute (attr) is a piece of a doc. In our case, our doc only contains a single attribute, which is our greeting.

greeting.on('attr:update', function (attr) {
  document.getElementById('greeting-out').innerHTML = attr.value;
});

Process Key Presses

The last step is to define the onKeyPress function which sets the greeting in the database and then clears the input box when the user presses the enter key. Behind the scenes, DeltaDB saves the new greeting and when we are online it syncs it with the cloud.

function onKeyPress(e) {
  if (e.keyCode === 13) { // pressed enter?
    // save change
    greeting.set({
      text: document.getElementById('greeting-in').value });
    // clear input box
    document.getElementById('greeting-in').value = '';
  }
}

Congratulations!

You have just built an offline-first app! In just a few lines of code you have created an app that syncs data in both directions, supports collaboration and works offline!

Should DeltaDB be used in production?

Not yet. DeltaDB is a new technology and works well, but it is still early in the development cycle and a bit more work needs to be done before developers should start using it in production. We also need to generate a lot more documentation. We could use your help. If you are interested in helping, head over to DeltaDB and submit a pull request.

What’s next?

Setting Up Your Own DeltaDB Server

DeltaDB on GitHub

Check out the DeltaDB API