# Cordova SQLite Storage Plugin

This Cordova/PhoneGap plugin uses SQLite databases on Android, iOS and Windows with an HTML5/Web SQL API.

* Repository: <https://github.com/litehelpers/Cordova-sqlite-storage>
* Plugin ID/package name: `cordova-sqlite-storage`
* Tested version: 6.1.0

{% hint style="info" %}
To check the third party Cordova plugins, you need to create a custom build debugger ([Android version](https://en.docs.monaca.io/products_guide/debugger/installation/debugger_android#build-and-install-a-custom-monaca-debugger) or [iOS version](https://en.docs.monaca.io/products_guide/debugger/installation/debugger_ios#building-a-custom-monaca-debugger)).
{% endhint %}

## Demo

[<img src="https://docs.monaca.io/images/common/import_img.png" alt="" data-size="line">Import the SQLite storage plugin demo to your Monaca account](https://monaca.mobi/ja/directimport?pid=64cb0450e78885302d01d556)

![](https://docs.monaca.io/images/samples/sqlite.png)

## Enable the plugin in Monaca IDE

1. From the IDE menu, go to **Config → Manage Cordova Plugins** .
2. Click the **Import Cordova Plugin** button. Then, you can choose to import the plugin using a ZIP file or a URL/package name.

## Usage

After importing the plugin into the project, you can initialize your database. Please make sure to call the plugin API after the Cordova is loaded.

```javascript
var database = null;

document.addEventListener("deviceready", function(){
    // Initialize the database after the Cordova is ready.
    initDatabase();
});

function initDatabase() {
    database = window.sqlitePlugin.openDatabase({name: 'sample.db', location: 'default'});

    database.transaction(function(transaction) {
        transaction.executeSql('CREATE TABLE SampleTable (name, score)');
    });
}
```

## API references

This section describes some of the main functions used in the [Demo](https://monaca.mobi/en/directimport?pid=5ac33652e78885cd208b4567). For complete API references, please refer to the [repository](https://github.com/litehelpers/Cordova-sqlite-storage).

### Self-test functions

#### echoTest()

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

```javascript
window.sqlitePlugin.echoTest(successCallback, errorCallback);
```

**Return Value**

* `Promise`

#### selfTest()

Verify that this plugin is able to open a database, execute the CRUD (create, read, update, and delete) operations, and clean it up properly.

```javascript
window.sqlitePlugin.selfTest(successCallback, errorCallback);
```

**Return Value**

* `Promise`

### Opening a database

Open a database access handle object.

```javascript
window.sqlitePlugin.openDatabase({name: String, [location: String], [iosDatabaseLocation: String]}, [successCallback], [errorCallback]);
```

**Parameter**

| Name                  | Type   | Description                                               |
| --------------------- | ------ | --------------------------------------------------------- |
| `name`                | String | Name of the database                                      |
| `location`            | String | \[optional] Location of the database                      |
| `iosDatabaseLocation` | String | \[optional] iOS Database Location. Available options are: |

**Return Value**

* `Promise`&#x20;

**Example**

An example of opening a database access handle object with a default or a specified location:

```javascript
// use the default location
var database = window.sqlitePlugin.openDatabase({name: 'my.db', location: 'default'});

// use a specified location for iOS only
var database = window.sqlitePlugin.openDatabase({name: 'my.db', iosDatabaseLocation: 'Library'});
```

The `successcb` and `errorcb` callback parameters are optional but can be extremely helpful in case anything goes wrong. For example:

```javascript
window.sqlitePlugin.openDatabase({name: 'my.db', location: 'default'}, function(db) {
  db.transaction(function(tx) {
    // ...
  }, function(err) {
    console.log('Open database ERROR: ' + JSON.stringify(err));
  });
});
```

### SQL transactions

Execute SQL on the opened database.

```javascript
database.executeSql(SQL_STATEMENT: String, [] , [successCallback], [errorCallback]);
```

**Return Value**

* `Promise`&#x20;

**Example**

```javascript
database.transaction(function(transaction) {
    transaction.executeSql('SELECT count(*) AS recordCount FROM SampleTable', [], function(ignored, resultSet) {
        $('#result').text('RECORD COUNT: ' + resultSet.rows.item(0).recordCount);
    });
}, function(error) {
    alert('SELECT count error: ' + error.message);
});
```

```javascript
database.transaction(function(transaction) {
    transaction.executeSql('DELETE FROM SampleTable');
}, function(error) {
    alert('DELETE error: ' + error.message);
}, function() {
    alert('DELETE OK');
});
```

### Deleting a database

Delete a database access handle object.

```javascript
window.sqlitePlugin.deleteDatabase({name: String, [location: String], [iosDatabaseLocation: String]}, [successCallback], [errorCallback]);
```

**Parameter**

| Name                  | Type   | Description                                               |
| --------------------- | ------ | --------------------------------------------------------- |
| `name`                | String | Name of the database                                      |
| `location`            | String | \[optional] Location of the database                      |
| `iosDatabaseLocation` | String | \[optional] iOS Database Location. Available options are: |

**Return Value**

* `Promise`&#x20;

**Example**

```javascript
// use the default location
window.sqlitePlugin.deleteDatabase({name: 'my.db', location: 'default'}, successcb, errorcb);

// use a specified location for iOS only
window.sqlitePlugin.deleteDatabase({name: 'my.db', iosDatabaseLocation: 'Library'});
```