Framework v4 BETA

Storage

Storage is an easy way to store key/value pairs and JSON objects. Storage uses a variety of storage engines underneath, picking the best one available depending on the platform.

When running in a native app context, Storage will prioritize using SQLite, as it's one of the most stable and widely used file-based databases, and avoids some of the pitfalls of things like localstorage and IndexedDB, such as the OS deciding to clear out such data in low disk-space situations.

When running in the web or as a Progressive Web App, Storage will attempt to use IndexedDB, WebSQL, and localstorage, in that order.

Usage

First, if you'd like to use SQLite, install the cordova-sqlite-storage plugin:

bash
ionic cordova plugin add cordova-sqlite-storage

Next, install the package (comes by default for Ionic apps > Ionic V1):

bash
npm install --save @ionic/storage

Next, add it to the imports list in your NgModule declaration (for example, in src/app/app.module.ts):

typescript
import { IonicStorageModule } from '@ionic/storage';

@NgModule({
  declarations: [
    // ...
  ],
  imports: [
    BrowserModule,
    IonicModule.forRoot(MyApp),
    IonicStorageModule.forRoot()
  ],
  bootstrap: [IonicApp],
  entryComponents: [
    // ...
  ],
  providers: [
    // ...
  ]
})
export class AppModule {}

Finally, inject it into any of your components or pages:

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

export class MyApp {
  constructor(private storage: Storage) { }

  ...

  // set a key/value
  storage.set('name', 'Max');

  // Or to get a key/value pair
  storage.get('age').then((val) => {
    console.log('Your age is', val);
  });
}

Configuring Storage

The Storage engine can be configured both with specific storage engine priorities, or custom configuration options to pass to localForage. See the localForage config docs for possible options: https://github.com/localForage/localForage#configuration

Note: Any custom configurations will be merged with the default configuration

typescript
import { IonicStorageModule } from '@ionic/storage';

@NgModule({
  declarations: [...],
  imports: [
    IonicStorageModule.forRoot({
      name: '__mydb',
driverOrder: ['indexeddb', 'sqlite', 'websql']
    })
  ],
  bootstrap: [...],
  entryComponents: [...],
   providers: [...]
})
export class AppModule { }

Instance Members

constructor

Create a new Storage instance using the order of drivers and any additional config options to pass to LocalForage.

Possible driver options are: ['sqlite', 'indexeddb', 'websql', 'localstorage'] and the default is that exact ordering.



driver

Get the name of the driver being used.



clear()

Clear the entire key value store. WARNING: HOT!

Returns: Returns a promise that resolves when the store is cleared



forEach()

Iterate through each key,value pair.

Returns: Returns a promise that resolves when the iteration has finished.

Parameters

iteratorCallback
a callback of the form (value, key, iterationNumber)


get()

Get the value associated with the given key.

Returns: Returns a promise with the value of the given key

Parameters

key
Type: string
the key to identify this value


keys()

Returns: Returns a promise that resolves with the keys in the store.



length()

Returns: Returns a promise that resolves with the number of keys stored.



ready()

Reflect the readiness of the store.

Returns: Returns a promise that resolves when the store is ready



remove()

Remove any value associated with this key.

Returns: Returns a promise that resolves when the value is removed

Parameters

key
Type: string
the key to identify this value


set()

Set the value for the given key.

Returns: Returns a promise that resolves when the key and value are set

Parameters

key
Type: string
the key to identify this value
value
Type: any
the value for this key