Storage

Provides access to the device's storage options.

This API is based on the W3C Web SQL Database Specification and W3C Web Storage API Specification. Some devices already provide an implementation of these specifications, in which case the built-in support applies. Cordova's implementation offers compatible support for those that don't.

Methods

openDatabase

Arguments

Objects

Permissions

Android

app/res/xml/config.xml

<plugin name="Storage" value="org.apache.cordova.Storage" />

BlackBerry WebWorks

www/config.xml

<feature id="blackberry.widgetcache" required="true" version="1.0.0.0" />

iOS

No permissions are required.

Windows Phone

No permissions are required.

Tizen

No permissions are required.

openDatabase

Returns a new Database object.

var dbShell = window.openDatabase(database_name, database_version, database_displayname, database_size);

Description

The method creates a new SQL Lite Database and returns a Database object that allows manipulation of the data.

Supported Platforms

Android
BlackBerry WebWorks (OS 6.0 and higher)
iOS
Tizen

Quick Example

var db = window.openDatabase("test", "1.0", "Test DB", 1000000);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Storage Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        var db = window.openDatabase("test", "1.0", "Test DB", 1000000);
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Open Database</p>
  </body>
</html>

database_name

The name of the database.

database_version

The version of the database.

database_displayname

The display name of the database.

database_size

The size of the database in bytes.

Database

Provides access to an SQL database.

Methods

transaction: Runs a database transaction.
changeVersion: Allows scripts to automatically verify the version number and change it when updating a schema.

Details

The window.openDatabase() method returns a Database object.

Supported Platforms

Android
BlackBerry WebWorks (OS 6.0 and higher)
iOS
Tizen

Transaction Quick Example

function populateDB(tx) {
    tx.executeSql('DROP TABLE IF EXISTS DEMO');
    tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
    tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
    tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
}

function errorCB(err) {
    alert("Error processing SQL: "+err.code);
}

function successCB() {
    alert("success!");
}

var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
db.transaction(populateDB, errorCB, successCB);

Change Version Quick Example

var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
db.changeVersion("1.0", "1.1");

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Storage Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
        db.transaction(populateDB, errorCB, successCB);
    }

    // Populate the database
    //
    function populateDB(tx) {
        tx.executeSql('DROP TABLE IF EXISTS DEMO');
        tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
        tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
        tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
    }

    // Transaction error callback
    //
    function errorCB(tx, err) {
        alert("Error processing SQL: "+err);
    }

    // Transaction success callback
    //
    function successCB() {
        alert("success!");
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Database</p>
  </body>
</html>

SQLTransaction

Allows execution of SQL statements against the Database.

Methods

executeSql: executes a SQL statement.

Details

Calling a Database object's transaction method, passes a SQLTransaction object to the specified callback method.

Supported Platforms

Android
BlackBerry WebWorks (OS 6.0 and higher)
iOS
Tizen

Execute SQL Quick Example

function populateDB(tx) {
    tx.executeSql('DROP TABLE IF EXISTS DEMO');
    tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
    tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
    tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
}

function errorCB(err) {
    alert("Error processing SQL: "+err);
}

function successCB() {
    alert("success!");
}

var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
db.transaction(populateDB, errorCB, successCB);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Storage Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
        db.transaction(populateDB, errorCB, successCB);
    }

    // Populate the database
    //
    function populateDB(tx) {
        tx.executeSql('DROP TABLE IF EXISTS DEMO');
        tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
        tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
        tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
    }

    // Transaction error callback
    //
    function errorCB(err) {
        alert("Error processing SQL: "+err);
    }

    // Transaction success callback
    //
    function successCB() {
        alert("success!");
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>SQLTransaction</p>
  </body>
</html>

SQLResultSet

When a SQLTransaction object's executeSql method is called, the specified callback executes with a SQLResultSet parameter.

Properties

insertId: The row ID of the row that the SQLResultSet object's SQL statement inserted into the database.
rowsAffected: The number of rows changed by the SQL statement, zero if the statement did not affect any rows.
rows: a SQLResultSetRowList representing the rows returned, empty if no rows are returned.

Details

When a SQLTransaction object's executeSql method is called, the specified callback executes with a SQLResultSet parameter containing three properties:

The insertId returns the row number of a successly SQL insertion statement. If the SQL does not insert any rows, the insertId is not set.
The rowsAffected is always 0 for a SQL select statement. For insert or update statements it returns the number of modified rows.
The final SQLResultSetList contains the data returned from a SQL select statement.

Supported Platforms

Android
BlackBerry WebWorks (OS 6.0 and higher)
iOS
Tizen

Execute SQL Quick Example

function queryDB(tx) {
    tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
}

function querySuccess(tx, results) {
    console.log("Returned rows = " + results.rows.length);
    // this will be true since it was a select statement and so rowsAffected was 0
    if (!results.rowsAffected) {
        console.log('No rows affected!');
        return false;
    }
    // for an insert statement, this property will return the ID of the last inserted row
    console.log("Last inserted row ID = " + results.insertId);
}

function errorCB(err) {
    alert("Error processing SQL: "+err.code);
}

var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
db.transaction(queryDB, errorCB);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Storage Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Populate the database
    //
    function populateDB(tx) {
        tx.executeSql('DROP TABLE IF EXISTS DEMO');
        tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
        tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
        tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
    }

    // Query the database
    //
    function queryDB(tx) {
        tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
    }

    // Query the success callback
    //
    function querySuccess(tx, results) {
        console.log("Returned rows = " + results.rows.length);
        // this will be true since it was a select statement and so rowsAffected was 0
        if (!results.rowsAffected) {
            console.log('No rows affected!');
            return false;
        }
        // for an insert statement, this property will return the ID of the last inserted row
        console.log("Last inserted row ID = " + results.insertId);
    }

    // Transaction error callback
    //
    function errorCB(err) {
        console.log("Error processing SQL: "+err.code);
    }

    // Transaction success callback
    //
    function successCB() {
        var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
        db.transaction(queryDB, errorCB);
    }

    // device APIs are available
    //
    function onDeviceReady() {
        var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
        db.transaction(populateDB, errorCB, successCB);
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Database</p>
  </body>
</html>

SQLResultSetRowList

One of the properties of the SQLResultSet containing the rows returned from a SQL query.

Properties

length: the number of rows returned by the SQL query.

Methods

item: returns the row at the specified index represented by a JavaScript object.

Details

The SQLResultSetRowList contains the data returned from a SQL select statement. The object contains a length property indicating how many rows the select statement returns. To get a row of data, call the item method to specify an index. It returns a JavaScript Object whose properties are the database columns the select statement was executed against.

Supported Platforms

Android
BlackBerry WebWorks (OS 6.0 and higher)
iOS
Tizen

Execute SQL Quick Example

function queryDB(tx) {
    tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
}

function querySuccess(tx, results) {
    var len = results.rows.length;
        console.log("DEMO table: " + len + " rows found.");
        for (var i=0; i<len; i++){
            console.log("Row = " + i + " ID = " + results.rows.item(i).id + " Data =  " + results.rows.item(i).data);
        }
    }

    function errorCB(err) {
        alert("Error processing SQL: "+err.code);
    }

    var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
    db.transaction(queryDB, errorCB);

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Storage Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Populate the database
    //
    function populateDB(tx) {
        tx.executeSql('DROP TABLE IF EXISTS DEMO');
        tx.executeSql('CREATE TABLE IF NOT EXISTS DEMO (id unique, data)');
        tx.executeSql('INSERT INTO DEMO (id, data) VALUES (1, "First row")');
        tx.executeSql('INSERT INTO DEMO (id, data) VALUES (2, "Second row")');
    }

    // Query the database
    //
    function queryDB(tx) {
        tx.executeSql('SELECT * FROM DEMO', [], querySuccess, errorCB);
    }

    // Query the success callback
    //
    function querySuccess(tx, results) {
        var len = results.rows.length;
        console.log("DEMO table: " + len + " rows found.");
        for (var i=0; i<len; i++){
            console.log("Row = " + i + " ID = " + results.rows.item(i).id + " Data =  " + results.rows.item(i).data);
        }
    }

    // Transaction error callback
    //
    function errorCB(err) {
        console.log("Error processing SQL: "+err.code);
    }

    // Transaction success callback
    //
    function successCB() {
        var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
        db.transaction(queryDB, errorCB);
    }

    // device APIs are available
    //
    function onDeviceReady() {
        var db = window.openDatabase("Database", "1.0", "Cordova Demo", 200000);
        db.transaction(populateDB, errorCB, successCB);
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Database</p>
  </body>
</html>

SQLError

A SQLError object is thrown when an error occurs.

Properties

code: One of the predefined error codes listed below.
message: A description of the error.

Constants

SQLError.UNKNOWN_ERR
SQLError.DATABASE_ERR
SQLError.VERSION_ERR
SQLError.TOO_LARGE_ERR
SQLError.QUOTA_ERR
SQLError.SYNTAX_ERR
SQLError.CONSTRAINT_ERR
SQLError.TIMEOUT_ERR

Description

The SQLError object is thrown when an error occurs when manipulating a database.

localStorage

Provides access to a W3C Storage interface

var storage = window.localStorage;

Methods

key: Returns the name of the key at the specified position.
getItem: Returns the item identified by the specified key.
setItem: Assigns a keyed item's value.
removeItem: Removes the item identified by the specified key.
clear: Removes all of the key/value pairs.

Details

The window.localStorage interface is based on the W3C Web Storage interface. An app can use it to save persistent data using key-value pairs. The window.sessionStorage interface works the same way, but all data is cleared each time the app closes.

Supported Platforms

Android
BlackBerry WebWorks (OS 6.0 and higher)
iOS
Tizen
Windows Phone 7 and 8

Key Quick Example

var keyName = window.localStorage.key(0);

Set Item Quick Example

window.localStorage.setItem("key", "value");

Get Item Quick Example

    var value = window.localStorage.getItem("key");
    // value is now equal to "value"

Remove Item Quick Example

    window.localStorage.removeItem("key");

Clear Quick Example

    window.localStorage.clear();

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Storage Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        window.localStorage.setItem("key", "value");
        var keyname = window.localStorage.key(i);
        // keyname is now equal to "key"
        var value = window.localStorage.getItem("key");
        // value is now equal to "value"
        window.localStorage.removeItem("key");
        window.localStorage.setItem("key2", "value2");
        window.localStorage.clear();
        // localStorage is now empty
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>localStorage</p>
  </body>
</html>

Windows Phone 7 Quirks

Dot notation is not available on Windows Phone 7. Be sure to use setItem or getItem, rather than accessing keys directly from the storage object, such as window.localStorage.someKey.

Storage

API Reference

Guides

Android

app/res/xml/config.xml

BlackBerry WebWorks

www/config.xml

iOS

Windows Phone

Tizen