Installation

Follow these steps to install Secure Storage into your app.

Don't have a Secure Storage subscription? Try it free now.

Installation

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

Next, install the plugin:

Capacitor

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

Cordova

ionic cordova plugin add @ionic-enterprise/secure-storage 

NOTE: npm 7+ is recommended. For previous versions, install @ionic-native/core as a dependency.

Angular Usage

In Angular, start by defining the SQLite class as provider in one of your component modules. We recommend your AppModule for usage across your app:

import { SQLite } from '@ionic-enterprise/secure-storage/ngx';

@NgModule({
  // ... snip ...
  providers: [SQLite],
  bootstrap: [AppComponent],
})
export class AppModule {}

Next, import @ionic-enterprise/secure-storage/ngx into your file and inject it into your constructor:

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

class MyComponent {
  constructor(private sqlite: SQLite) {}
}

Initializing the database can be done immediately in the constructor:

private database: SQLiteObject;

constructor(private sqlite: SQLite) {
  this.initializeDatabase();
}

private async initializeDatabase() {
  // Create or open a table
  try {
    const db = await this.sqlite.create({
      name: "mydb",
      location: "default",
      // Key/Password used to encrypt the database
      // Strongly recommended to use Identity Vault to manage this
      key: "password"
    });

    this.database = db;

    // Create our initial schema
    await db.executeSql('CREATE TABLE IF NOT EXISTS software(name, company, type, version)', [])
  } catch (e) {
    console.error('Unable to initialize database', e);
  }
}

Note: starting with version @ionic-enterprise.secure-storage@2.3.0 the distribution of this plugin changed in a way that is non-breaking for up to date applications. Applications using older versions of Angular and TypeScript may have problems, however.

If your application uses an version of TypeScript older than 4.x you need to change the import path to @ionic-enterprise/secure-storage/dist/ngx until such time as you can upgrade the rest of your project. In such a case, it is suggested that you upgrade the rest of your dependencies as soon as possible.

React Usage

Begin by importing Secure Storage into one of your component source files then create a state variable for the database:

import { SQLite, SQLiteObject, SQLiteTransaction } from '@ionic-enterprise/secure-storage';
import { useEffect, useState } from 'react';

const App: React.FC = () => {
  const [db, setDb] = useState<SQLiteObject | null>(null);
}

Next, initialize the database immediately and create the database tables:

useEffect(() => {
  async function createDb() {
    try {
      const newDb = await SQLite.create({
        name: 'mydb',
        location: 'default',
        // Key/Password used to encrypt the database
        // Strongly recommended to use Identity Vault to manage this
        key: "password"
      });

      setDb(newDb);

      // create tables
      await newDb.executeSql('CREATE TABLE IF NOT EXISTS software(name, company, type, version)', [])
    } catch (e) {
      console.error('Unable to create database', e);
    }
  }

  createDb();
}, []);

Vue Usage

Begin by importing Secure Storage into one of your components:

import { SQLite, SQLiteObject, SQLiteTransaction } from '@ionic-enterprise/secure-storage';

Next, create a ref object for the database instance, then initialize the database immediately:

export default defineComponent({
  name: 'App',
  components: {
    IonApp,
    IonRouterOutlet
  },
  setup() {
    const db = ref<SQLiteObject>();

    async function createDb() {
      try {
        const newDb = await SQLite.create({
          name: 'mydb',
          location: 'default',
          // Key/Password used to encrypt the database
          // Strongly recommended to use Identity Vault to manage this
          key: "password"
        });

        db.value = newDb;
        console.log('Created database!', newDb);

        // create tables
        await db.executeSql('CREATE TABLE IF NOT EXISTS software(name, company, type, version)', [])
      } catch (e) {
        console.error('Unable to create database', e);
      }
    }

    createDb();
  }
});

Basic SQL operations

Insert data into a database table:

this.database.transaction((tx) => {
  tx.executeSql("INSERT INTO software (name, company, type, version) VALUES (?,?,?,?)",
  [ "secure-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: "secure-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

Transactions are strongly recommended for performance reasons, especially when using encryption, and are also critical for building atomic operations that only commit to the database if all statements execute correctly.

Single-statement Transactions

Transactions can be performed one statement at a time using SQLiteTransaction.executeSql:

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']);
});

Or can be performed in a batch SQLiteObject.sqlBatch:

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