Ionic Storage

To use Ionic Storage in a React, Vue, or Vanilla JavaScript project, install the core package via npm.

npm install @ionic/storage

To use SQLite in non-enterprise apps via Cordova or Capacitor, follow these steps:

1. Install the SQLite plugin:
   • Cordova: ionic cordova plugin add cordova-sqlite-storage
   • Capacitor: npm install cordova-sqlite-storage
2. Install the driver: npm install localforage-cordovasqlitedriver
3. Configure the driver: Add CordovaSQLiteDriver._driver to your driverOrder.
4. Register the driver: Call await storage.defineDriver(CordovaSQLiteDriver) before any data operations.

import CordovaSQLiteDriver from 'localforage-cordovasqlitedriver';
import { Storage, Drivers } from '@ionic/storage';

// Configuration
const store = new Storage({
  driverOrder: [CordovaSQLiteDriver._driver, Drivers.IndexedDB, Drivers.LocalStorage]
});

// Registration
await store.defineDriver(CordovaSQLiteDriver);

If you are building an Angular application, install the @ionic/storage-angular package instead of the core package to benefit from Angular-specific integration like Dependency Injection and Modules.

npm install @ionic/storage-angular

In Angular, you must import IonicStorageModule in your NgModule and then inject the Storage class into your components or services.

Note: create() should be called only once in the application lifecycle. For complex apps, it is recommended to wrap storage logic in an Angular Service.

// 1. Import IonicStorageModule in your AppModule
import { IonicStorageModule } from '@ionic/storage-angular';

@NgModule({
  imports: [
    IonicStorageModule.forRoot()
  ]
})
export class AppModule { }

// 2. Inject Storage into a component
import { Component } from '@angular/core';
import { Storage } from '@ionic/storage-angular';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html'
})
export class AppComponent {
  constructor(private storage: Storage) {}

  async ngOnInit() {
    await this.storage.create();
  }
}

You can configure the storage engine by specifying a name for the database and a driverOrder to define the priority of storage engines (e.

React/Vue/Vanilla JS: Pass options to the Storage constructor. Angular: Pass options to IonicStorageModule.forRoot() in your NgModule.

// React/Vue/Vanilla JS
const storage = new Storage({
  name: '__mydb',
  driverOrder: [Drivers.IndexedDB, Drivers.LocalStorage]
});

// Angular
@NgModule({
  imports: [
   IonicStorageModule.forRoot({
     name: '__mydb',
     driverOrder: [Drivers.IndexedDB, Drivers.LocalStorage]
   })
  ]
})
export class AppModule { }

In non-Angular projects, instantiate the Storage class and call create() to initialize the storage engine before performing operations.

import { Storage } from '@ionic/storage';

const store = new Storage();
await store.create();

For sophisticated usage in Angular, create a dedicated service to manage database initialization and operations. This ensures create() is called in a single location and provides a clean API for the rest of your app.

import { Injectable } from '@angular/core';
import { Storage } from '@ionic/storage-angular';

@Injectable({
  providedIn: 'root'
})
export class StorageService {
  private _storage: Storage | null = null;

  constructor(private storage: Storage) {
    this.init();
  }

  async init() {
    const storage = await this.storage.create();
    this._storage = storage;
  }

  public set(key: string, value: any) {
    this._storage?.set(key, value);
  }
}

Ionic Storage v3+ supports encryption when used in conjunction with Ionic Secure Storage. You can enable this by calling the setEncryptionKey(key) method on your Storage instance. This allows you to use the standard key-value API while ensuring data is encrypted at rest. For advanced key management and biometric authentication, this can be paired with Ionic Identity Vault.

// Assuming storage is initialized and IonicSecureStorageDriver is defined
await storage.setEncryptionKey('your-secret-key');

The Storage instance provides the following methods for key-value operations:

• set(key, value): Stores a value associated with a key. Returns a Promise.
• get(key): Retrieves the value associated with a key. Returns a Promise.
• remove(key): Removes the item associated with the key. Returns a Promise.
• clear(): Removes all items from the storage. Returns a Promise.
• keys(): Returns an array of all stored keys. Returns a Promise.
• length(): Returns the number of key/value pairs stored. Returns a Promise.
• forEach((key, value, index) => { ... }): Enumerates the stored key/value pairs.

await storage.set('name', 'Mr. Ionitron');
const name = await storage.get('name');
await storage.remove('name');
await storage.clear();
await storage.keys();
await storage.length();
storage.forEach((key, value, index) => {
  // logic here
});

The Storage class provides the following asynchronous methods for managing data:

• get(key: string): Returns the value associated with the given key.
• set(key: string, value: any): Sets the value for the given key.
• remove(key: string): Removes the value associated with the key.
• clear(): Clears the entire key-value store.
• length(): Returns the number of keys in the store.
• keys(): Returns an array of all keys in the store.
• forEach(iteratorCallback): Iterates through each key-value pair using a callback with the signature (value, key, iterationNumber).

// Example of forEach
await storage.forEach((value, key, iterationNumber) => {
  console.log(`Key: ${key}, Value: ${value}, Index: ${iterationNumber}`);
});