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:

Capacitor
Cordova

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();