Storage

Improve this doc

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:

cordova plugin add cordova-sqlite-storage --save

Next, install the package (comes by default for Ionic 2 apps >= RC.0)

npm install --save @ionic/storage

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

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

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

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

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

export class MyApp {
  constructor(storage: Storage) {

     storage.ready().then(() => {

       // 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

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

export function provideStorage() {
  return new Storage(['sqlite', 'websql', 'indexeddb'], { name: '__mydb' });
}

@NgModule({
  declarations: ...,
  imports: ...,
  bootstrap: ...,
  entryComponents: ...,
   providers: [
     { provide: Storage, useFactory: provideStorage }
   ]
})
export class AppModule {}

Instance Members

driver

Get the name of the driver being used.

Returns:

Name of the driver

ready()

Reflect the readiness of the store.

Returns:

Promise that resolves when the store is ready

get(key)

Get the value associated with the given key.

Param Type Details
key

the key to identify this value

Returns:

Promise that resolves with the value

set(key, value)

Set the value for the given key.

Param Type Details
key

the key to identify this value

value

the value for this key

Returns:

Promise that resolves when the value is set

remove(key)

Remove any value associated with this key.

Param Type Details
key

the key to identify this value

Returns:

Promise that resolves when the value is removed

clear()

Clear the entire key value store. WARNING: HOT!

Returns:

Promise that resolves when the store is cleared

length()

Returns:

Promise that resolves with the number of keys stored.

keys()

Returns:

Promise that resolves with the keys in the store.

forEach(iteratorCallback)

Iterate through each key,value pair.

Param Type Details
iteratorCallback

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

Returns:

Promise that resolves when the iteration has finished.

API

Native

General