HTML5 - Introduction to local, client-side databases

From Nokia Developer Wiki
Jump to: navigation, search
Article Metadata
Created: Maveric (30 Dec 2010)
Last edited: Vaishali Rawat (19 Dec 2012)


This article is an introduction to what are the local client-side databases in HTML5, how to open an existing database, how to handle possible errors and finally how to start creating a new database.

The so called client-side storage API in HTML allows web applications to store structured data locally. This is achieved by using the Structured Query Language (SQL) callback functions asynchronously.

The convenience of these client-side databases is in the fact that they are are easy to use and won´t expire. A maximum size for the database can be set.. No need to use external servers, manage cookies because of the use of JavaScript. All data in the database is persistent until deleted manually. The Safari and Opera browsers have an SQL lite based database solution, and have been proven to be threadsafe. This means that a multiple instances of data cannot be opened.

What is especially good in this way of working, is that you do not need to establish external mechanisms to accomplish this; no servers needed. At the same time, this would mean an inrceased security and short response times.

HTML5 Local Databases are now supported in the following browsers: Safari 4, iPhone/iPad OS3, Chrome 5, and Opera 10.5 (Desktop). It is good to follow the support status, as the HTML5 support and definition is still evolving.

How to open an existing database

Here is an example of a callback function to work with the local database.

var database = openDatabase("your_database", "database_version"); 
database.executeSql("SELECT * FROM mytable", function(result_1) {
// do something with the result
database.executeSql("DROP TABLE mytable", function(result_2) {
// do something with the result
alert("SQL query executed successfully”);

In the following example code, we assume that a database named "myDB" exists.

The example below shows how to open a database, create tables and handle errors if any:

Example code for opening a database, creating some tables and handling possible errors:

var displayName='Database myDB';
var maxSize = 500000; // maximum size of the database in bytes
myDB = openDatabase(shortName,version,displayName,maxSize);
if (e == 2) {
// Database version conflict or error
console.log("Unknown or wrong database version.");  
console.log("Unknown error "+e+".");  

How to create a new database

HTML5 Local Databases are now supported in the following browsers: Safari 4, iPhone/iPad OS3, Chrome 5, and Opera 10.5 (Desktop). The first task would be to check if the browser, does actually support the “openDatabase” method.

This is crucial, and the script can continue only if the support exists. The database parameters will be defined as follows.

function yourFunction() {
//Support OK, open the database
//else show the user this message:
alert('Your browser is not supporting databases.');
var user_database_name = 'myDB';
var version='1.0';

The variable user_database_name variable, is used with both SQL and browser when referring to this database.

The openDatabase version 1.0 means that the JavaScript database supports versioning. This means that the database schema can be edited and changed. When the database is being opened, the existing version will be checked against the version specified, here it would be version “1.0”. Otherwise the openDatabase will throw an exception of value “2”.

If an empty string for the version is provided, then the database will be opened whatever the database version was. It is then possible to query the version by examining the database object's version property. For example the next code will show the current database version:

var db = openDatabase(shortName, "", displayName, maxSize); var version = db.version; // e.g. "1.0"

When the version is known, the database can be updated to a new version (possibly with a modified schema or by modified data) using the changeVersion method.

The displayName refers to a screen name as the description of the database.. The maxSize is represents maximum foreseeable byte-size for the database. This is important information for memory management functions.

This page was last modified on 19 December 2012, at 13:07.
81 page views in the last 30 days.