Search docs/
Native SolutionsCore Device

Ionic Offline Storage

v2.0.0

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.

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

Index

Classes

Interfaces


Classes

SQLite

SQLite:

name: SQLite

description: Access SQLite databases on the device.

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

constructor(private sqlite: SQLite) { }

...

this.sqlite.create({ name: 'data.db', location: 'default' }) .then((db: SQLiteObject) => {

db.executeSql('create table danceMoves(name VARCHAR(32))', [])
  .then(() => console.log('Executed SQL'))
  .catch(e => console.log(e));

}) .catch(e => console.log(e));


*__classes__*: SQLiteObject

*__interfaces__*: SQLiteDatabaseConfig SQLiteTransaction

<a id="sqlite.create"></a>

###  create

▸ **create**(config: *[SQLiteDatabaseConfig](#sqlitedatabaseconfig)*): `Promise`<`SQLiteObject`>

Open or create a SQLite database file.

See the plugin docs for an explanation of all options: [https://github.com/litehelpers/Cordova-sqlite-storage#opening-a-database](https://github.com/litehelpers/Cordova-sqlite-storage#opening-a-database)

**Parameters:**

| Name | Type | Description |
| ------ | ------ | ------ |
| config | [SQLiteDatabaseConfig](#sqlitedatabaseconfig) |  database configuration |

**Returns:** `Promise`<`SQLiteObject`>
Promise<SQLiteObject>

___
<a id="sqlite.deletedatabase"></a>

###  deleteDatabase

▸ **deleteDatabase**(config: *[SQLiteDatabaseConfig](#sqlitedatabaseconfig)*): `Promise`<`any`>

Deletes a database

**Parameters:**

| Name | Type | Description |
| ------ | ------ | ------ |
| config | [SQLiteDatabaseConfig](#sqlitedatabaseconfig) |  database configuration |

**Returns:** `Promise`<`any`>

___
<a id="sqlite.echotest"></a>

###  echoTest

▸ **echoTest**(): `Promise`<`any`>

Verify that both the Javascript and native part of this plugin are installed in your application

**Returns:** `Promise`<`any`>

___
<a id="sqlite.selftest"></a>

###  selfTest

▸ **selfTest**(): `Promise`<`any`>

Automatically verify basic database access operations including opening a database

**Returns:** `Promise`<`any`>

___

___

## Interfaces

<a id="sqlitedatabaseconfig"></a>

###  SQLiteDatabaseConfig

**SQLiteDatabaseConfig**: 

<a id="sqlitedatabaseconfig.createfromlocation"></a>

### `<Optional>` createFromLocation

**● createFromLocation**: *`number`*

support opening pre-filled databases with [https://github.com/litehelpers/cordova-sqlite-ext](https://github.com/litehelpers/cordova-sqlite-ext)

___
<a id="sqlitedatabaseconfig.iosdatabaselocation"></a>

### `<Optional>` iosDatabaseLocation

**● iosDatabaseLocation**: *`string`*

iOS Database Location. Example: 'Library'

___
<a id="sqlitedatabaseconfig.key"></a>

### `<Optional>` key

**● key**: *`string`*

support encrypted databases with [https://github.com/litehelpers/Cordova-sqlcipher-adapter](https://github.com/litehelpers/Cordova-sqlcipher-adapter)

___
<a id="sqlitedatabaseconfig.location"></a>

### `<Optional>` location

**● location**: *`string`*

Location of the database. Example: 'default'

___
<a id="sqlitedatabaseconfig.name"></a>

###  name

**● name**: *`string`*

Name of the database. Example: 'my.db'

___

___

# Changelog

Other Versions