DB8 Basics

DB8 is a storage method of webOS TV. DB8 is designed to meet the needs of robust, high-performance apps. DB8 is a service available on Luna Bus, and interfaces to an embedded JSON database.

To find out information on how to call this service from an app or service, see Database API or Media Database API. You can also see code samples and download the sample app in the GitHub repository.

We assume that you have a basic knowledge of database concepts and SQL in our explanation about the following topics:

Main DB8 features

Main DB8 features include:

• Enabling high-speed access and queries.
• Storing JSON objects.
• App-aware access control.
• Paging support for queries that can retrieve up to 500 objects at a time.
• Support for change notification.
• Data object validation through schema enforcement.

Getting started

To use DB8 storage in your code, follow the steps provided below.

1. Determine what you are going to store in DB.
2. Determine what your indices are going to be. It is critical because the indices determine the query types that you can make.
3. Create a kind using the putKind() method. Now your app can store data objects in the kind created.
4. Start storing your data with the put() method.

DB8 JSON objects

DB8 stores two types of JSON objects:

• Kind object: Think of this as what we casually call 'table' in DB. This object defines the owner, schema, and indexes for JSON data objects. In DB8, these objects are known as kinds. Before a data object can be saved, its defining kind object must be stored and registered with the putKind() call.
• Data object: JSON object of a particular kind that contains data. It is similar to objects that are instances of classes in object-oriented programming.

Example

Let's see some object examples to help your understanding. Before creating a kind object, we will determine what we will store in DB, as guided in the Getting Started. Let's create a DB for contacts. We will store the contact information in DB.

Data object

After a thorough discussion, we have decided to store contact information that would look like this:

{
    "displayName"  : "John Doe",
    "name"         : {"familyName":"Doe", "givenName":"John"},
    "nickname"     : "Skippy",
    "emails"       : [ "jdoe@gmail.com", "john.doe@palm.com", "jdoe99@gmail.com" ]
}

The definition of the above JSON object would look like this:

{
    "displayName" : string,
    "name"        : {
        "familyName" : string,
        "givenName"  : string
    },
    "nickname"    : string,
    "emails"      : string array
}

Kind object

Before we store data objects that we defined above, we need a table to store the data objects. You can create a kind object using the putKind() method. The parameter of this method would look something like this:

{
    "id"      :  "com.yourdomain.contact:1",
    "owner"   :  "com.yourdomain.contacts",
    "extends" :  ["PimObject:1"],
    "indexes" :  [{"name":"dname", "props":[{"name":"displayName"}]}]
}

The properties of the kind object are as follows. These properties can be defined when registering a kind with putKind() method.

Special properties

There are some special properties that DB8 assigns to objects. These are delineated with an underscore (_) based on JSON DB conventions. Because of this, apps cannot create properties that start with an underscore.

Currently, the following special properties are assigned to stored objects.

Here is a sample contacts object assigned with the special properties:

{
    "_id"          : "2+n4",
    "_rev"         : 276,
    "_kind"        : "com.yourdomain.contact:1",
    "displayName"  : "John Doe",
    "name"         : {"familyName":"Doe", "givenName":"John"},
    "nickname"     : "Skippy",
    "emails"       : [ "jdoe@gmail.com", "john.doe@palm.com", "jdoe99@gmail.com" ]
}

Atomicity & optimistic concurrency

For updating an object, atomicity means that either all of it takes place and is committed to the database, or none of it is.

In DB8, all updates (i.e., inserting or deleting multiple objects) done in a single method call are atomic. Batch operations that combine multiple operations atomically are NOT supported.

App-level transactions are not supported. Doing so would allow database locks to be held for a long period of time, potentially blocking other applications, including those the user is waiting on.

You can implement a form of optimistic concurrency to ensure atomicity. This would involve the following steps:

1. Get an object and note its revision value (_rev).
2. Modify the object.
3. Perform a conditional merge operation with a query that specifies the object's id and revision values (_id and _rev).
4. If the revision number has changed, indicating it has been modified, repeat the cycle and try again.