Offline Storage

Ionic Offline Storage is a cross-platform data storage system that works on iOS and Android. Powered by SQLite, a SQL database engine for building powerful, data-driven apps entirely in JavaScript.

This solution makes it easy to add offline storage to Ionic apps that are secure (encrypted on device using 256-bit AES), highly performant, and provide advanced data querying. Learn more.

Installation#

If you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.

Next, install the plugin:

npm install @ionic-enterprise/offline-storage
npx cap sync

Getting Started#

Offline Storage is powered by SQLite, so it's incredibly easy to use - simply leverage familiar SQL query syntax.

If using Angular, start by injecting Offline Storage as a provider to the project in app.module.ts:

import { SQLite } from '@ionic-enterprise/offline-storage/ngx';
@NgModule({
// ... snip ...
providers: [
SQLite
],
bootstrap: [AppComponent]
})
export class AppModule {}

Next, import @ionic-enterprise/offline-storage into the desired class (A dedicated service that encapsulates Offline Storage logic is recommended).

import { SQLite, SQLiteObject } from '@ionic-enterprise/offline-storage/ngx';

Next, initialize the database then immediately create (or open) a table:

private database: SQLiteObject;
constructor(private sqlite: SQLite) {
this.initializeDatabase();
}
private async initializeDatabase() {
// Create or open a table
this.sqlite.create({
name: "images.db",
location: "default",
// Key/Password used to encrypt the database
// Strongly recommended to use Identity Vault to manage this
key: "password"
}).then((db: SQLiteObject) => {
this.database = db;
db.executeSql(
'CREATE TABLE IF NOT EXISTS software(name, company, type, version)', [])
.then(() => console.log('Successfully created software table.'))
.catch(e => console.log(e));
}).catch(e => console.log(e));
}

Basic Queries#

Insert data into a database table:

this.database.transaction((tx) => {
tx.executeSql("INSERT INTO software (name, company, type, version) VALUES (?,?,?,?)",
[ "offline-storage", "ionic", "native", "2.0"], (tx, result) => {
console.log("insertId: " + result.insertId); // New Id number
console.log("rowsAffected: " + result.rowsAffected); // 1
});
});

Read data from a database table:

this.database.transaction((tx) => {
tx.executeSql("SELECT * from software", [], (tx, result) => {
// Rows is an array of results. Use zero-based indexing to access
// each element in the result set: item(0), item(1), etc.
for (let i = 0; i < result.rows.length; i++) {
// { name: "offline-storage", company: "ionic", type: "native", version: "2.0" }
console.log(result.rows.item(i));
// ionic
console.log(result.rows.item(i).company);
}
});
});

Update data:

this.database.transaction((tx) => {
tx.executeSql("UPDATE software SET version = ? WHERE company = ?", [ "2.2", "ionic" ],
(tx, result) => {
console.log("Rows affected: " + result.rowsAffected); // 1
});
});

Delete data:

this.database.transaction((tx) => {
tx.executeSql("DELETE FROM software WHERE company = ?", [ "ionic" ],
(tx, result) => {
console.log("Rows affected: " + result.rowsAffected); // 1
});
});

Close the database:

await this.database.close();

Delete the database (provide the same configuration details used when creating it):

await this.sqlite.deleteDatabase({
name: "images.db",
location: "default",
key: "password"
});

Transactions#

Single-statement Transactions#

this.database.transaction((tx) => {
tx.executeSql('CREATE TABLE IF NOT EXISTS software (name, company)');
tx.executeSql('INSERT INTO software VALUES (?,?)', ['offline', "ionic"]);
tx.executeSql('INSERT INTO software VALUES (?,?)', ['auth-connect', "ionic"]);
});

Batch Transactions#

this.database.sqlBatch([
'CREATE TABLE IF NOT EXISTS software (name, company)',
[ 'INSERT INTO software VALUES (?,?)', ['offline', "ionic"] ],
[ 'INSERT INTO software VALUES (?,?)', ['auth-connect', "ionic"] ]
]);

Test Functions#

Useful for debugging issues.

// Verify that both the JavaScript and native part of this plugin
// are installed in your Ionic app
await this.sqlite.echoTest();
// Verify basic database access operations including opening a database
// Prints "OPEN database: OK"
await this.sqlite.selfTest();