Cordova Plugin: Database Copy

2.1.2 · maintenance · verified Wed Apr 22

cordova-plugin-dbcopy is a Cordova/Phonegap plugin designed to copy a pre-populated SQLite database from the `www` directory of an application to the device's native app database directory. The current stable version is 2.1.2. This plugin addresses a common need for mobile applications that require initial data or a pre-configured database upon first launch, providing methods to copy the database, check its existence, and handle different storage locations, especially for iOS iCloud backup exclusion. Its release cadence appears to be stable rather than rapid, focusing on core functionality within the Cordova ecosystem. A key differentiator is its explicit handling of platform-specific database locations and error responses for common issues like file not found or already existing databases.

Common errors

```
message contains the response string like Invalid DB Location or DB Doesn't Exists or Db Copied Successfully, code: 404
```
cause The specified database file (`dbname`) was not found in the `www` directory, or the source/destination path for external storage operations is invalid.

fix Verify that your database file (e.g., `mydata.db`) is correctly placed inside the `www` folder of your Cordova project. Ensure the filename passed to `copy` is exact (including extension if present). For `checkDbOnStorage` or `copyDbFromStorage`, confirm the `source` path is a valid native file system path.
```
message contains the response string like Db Already Exists, code: 516
```
cause A database with the specified name already exists at the target location and the plugin is configured not to overwrite it.

fix This is often expected behavior. If you need to overwrite, you might need to manually delete the existing database first using a file system plugin (e.g., `cordova-plugin-file`) or handle the error gracefully if overwriting is not desired. The `copy` method itself doesn't offer an overwrite option directly; subsequent calls will fail if the DB exists.

Warnings

gotcha For Android, the `target-sdk-version` in `config.xml` must be set to a minimum of 26 to ensure proper plugin functionality, particularly regarding file access permissions.
Fix: Add `<preference name="android-targetSdkVersion" value="26" />` to your `config.xml` file.
gotcha The `location` parameter for the `copy` method has different meanings and recommendations for iOS and Android. For Android, always use `0`. For iOS, `0` disables iCloud Backup, `1` copies to `Library` (synced by iCloud), and `2` copies to the default SQLite Database directory.
Fix: Ensure `location = 0` for Android. For iOS, choose `0`, `1`, or `2` based on iCloud backup requirements. For example, `window.plugins.sqlDB.copy(dbname, 0, success, error);`
gotcha When specifying the database filename, include the full name with any extensions (e.g., `sample.db` or `sample.sqlite`). The plugin will use the exact string provided.
Fix: Pass the complete filename string including its extension, if any, to the `dbname` parameter. For example, `window.plugins.sqlDB.copy('mydata.sqlite', ...);`
deprecated The `copyDbFromStorage` method is marked as 'untested' in the README and its reliability may be questionable. Use with caution or consider contributing to its testing and improvement.
Fix: If `copyDbFromStorage` is critical for your use case, test thoroughly across target platforms and consider reviewing or contributing to the plugin's source code. Otherwise, prioritize the `copy` method.

Install

npm install cordova-plugin-dbcopy npm
yarn add cordova-plugin-dbcopy yarn
pnpm add cordova-plugin-dbcopy pnpm

Imports

window.plugins.sqlDB
wrong:
```
import { sqlDB } from 'cordova-plugin-dbcopy';
```
correct:
```
document.addEventListener('deviceready', function() { console.log(window.plugins.sqlDB); });
```
Cordova plugins expose their APIs globally on the `window.plugins` object after the `deviceready` event fires. Direct ES module or CommonJS imports are not applicable.
window.plugins.sqlDB.copy
wrong:
```
const copy = require('cordova-plugin-dbcopy').copy;
```
correct:
```
window.plugins.sqlDB.copy(dbname, location, successCallback, errorCallback);
```
Access the `copy` method directly from the globally available `window.plugins.sqlDB` object. Ensure `deviceready` has fired.
window.plugins.sqlDB.checkDbOnStorage
wrong:
```
checkDbOnStorage(dbname, sourcePath, successCallback, errorCallback);
```
correct:
```
window.plugins.sqlDB.checkDbOnStorage(dbname, sourcePath, successCallback, errorCallback);
```
Like other plugin methods, `checkDbOnStorage` must be called on the `window.plugins.sqlDB` object. It is not globally available by itself.

Quickstart

This code snippet demonstrates how to copy a pre-populated database from the `www` directory to the app's data directory after the Cordova `deviceready` event. It includes basic error handling.

document.addEventListener('deviceready', function() {
  const dbName = 'myprepopulated.db';
  // For iOS, location 0 disables iCloud backup. For Android, use 0.
  const location = 0; 

  window.plugins.sqlDB.copy(dbName, location, function(response) {
    console.log('Database copy success:', response.message, 'Code:', response.code);
    // Now you can open the database using SQLitePlugin
    // const db = window.sqlitePlugin.openDatabase({
    //   name: dbName, 
    //   location: 'default' // Or other appropriate location based on 'location' param above
    // });
    // db.transaction(function(tx) { /* ... */ });
  }, function(error) {
    console.error('Database copy error:', error.message, 'Code:', error.code);
  });
}, false);

view raw JSON →