Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 82 additions & 30 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
# react-native-sqlite-storage

SQLite3 Native Plugin for React Native for both Android (Classic and Native), iOS and Windows

Foundation of this library is based on Chris Brody's Cordova SQLite plugin.

Features:
1. iOS and Android supported via identical JavaScript API.
2. Android in pure Java and Native modes
3. SQL transactions
4. JavaScript interface via plain callbacks or Promises.
5. Pre-populated SQLite database import from application bundle and sandbox
6. Windows supports callback API, identical to iOS and Android

1. iOS and Android supported via identical JavaScript API.
2. Android in pure Java and Native modes
3. SQL transactions
4. JavaScript interface via plain callbacks or Promises.
5. Pre-populated SQLite database import from application bundle and sandbox
6. Windows supports callback API, identical to iOS and Android

There are sample apps provided in test directory that can be used in with the AwesomeProject generated by React Native. All you have to do is to copy one of those files into your AwesomeProject replacing index.ios.js.

Expand All @@ -20,19 +22,25 @@ The library has been tested with React 16.2 (and earlier) and XCode 7,8,9 - it w
Version 3.2 is the first version compatible with RN 0.40.

# Installation

```
npm install --save react-native-sqlite-storage
```

Then follow the instructions for your platform to link react-native-sqlite-storage into your project

## Promises
To enable promises, run

To enable promises, run

```javascript
SQLite.enablePromise(true);
```

## iOS

#### Standard Method

** React Native 0.60 and above **
Run `cd ios && pod install && cd ..`. Linking is not required in React Native 0.60 and above

Expand All @@ -43,17 +51,22 @@ Run `cd ios && pod install && cd ..`. Linking is not required in React Native 0.
##### With CocoaPods:

Add this to your Podfile which should be located inside the ios project subdirectory

```ruby
pod 'React', :path => '../node_modules/react-native'
pod 'react-native-sqlite-storage', :path => '../node_modules/react-native-sqlite-storage'
```

Or use the sample Podfile included in the package by copying it over to ios subdirectory and replacing AwesomeProject inside of it with the name of your RN project.

Refresh the Pods installation

```ruby
pod install
```

OR

```ruby
pod update
```
Expand All @@ -63,21 +76,23 @@ Done, skip to Step 2.
##### Without CocoaPods:

This command should be executed in the root directory of your RN project

```shell
react-native link
```

rnpm and xcode are dependencies of this project and should get installed with the module but in case there are issue running rnpm link and rnpm/xcode are not already installed you can try to install it globally as follows:

```shell
npm -g install rnpm xcode
```

After linking project should like this:

![alt tag](instructions/after-rnpm.png)

#### Step 1a. If rnpm link does not work for you you can try manually linking according to the instructions below:


##### Drag the SQLite Xcode project as a dependency project into your React Native XCode project

![alt tag](https://raw.github.com/andpor/react-native-sqlite-storage/master/instructions/libs.png)
Expand Down Expand Up @@ -249,12 +264,22 @@ var SQLite = require('react-native-sqlite-storage')
...
```

#### Step 5. Added liteglue to proguard file

You may need to add to your proguard-rules.pro file the lines below:

```kotlin
-keep class io.liteglue.** { *; }
```

## Windows

** RNW 0.63 with Autolinking and above **

No manual steps required

** React Native 0.62 **

### Step 1: Update the solution file

Add the `SQLitePlugin` project to your solution.
Expand All @@ -267,10 +292,9 @@ Add the `SQLitePlugin` project to your solution.

Add a reference to `SQLitePlugin` to your main application project. From Visual Studio 2019:

1. Right-click main application project > Add > Reference...
1. Right-click main application project > Add > Reference...
2. Check `SQLitePlugin` from Solution Projects


### Step 3: Update the `pch.h` file

Add `#include "winrt/SQLitePlugin.h"`.
Expand All @@ -281,7 +305,6 @@ Add `PackageProviders().Append(winrt::SQLitePlugin::ReactPackageProvider());` be

Refer to this guide for more details: https://microsoft.github.io/react-native-windows/docs/next/native-modules-using


## Setting up your project to import a pre-populated SQLite database from application for iOS

#### Step 1 - Create 'www' folder.
Expand Down Expand Up @@ -313,6 +336,7 @@ Ensure your project structure after previous steps are executed looks like this
### Step 6 - Adjust openDatabase call

Modify you openDatabase call in your application adding createFromLocation param. If you named your database file in step 2 'testDB' the openDatabase call should look like something like this:

```js

...
Expand All @@ -325,6 +349,7 @@ Modify you openDatabase call in your application adding createFromLocation param
...

```

For Android, the www directory is always relative to the assets directory for the app: src/main/assets

Enjoy!
Expand All @@ -335,29 +360,29 @@ Opening a database is slightly different between iOS and Android. Where as on An

WARNING: the default location on iOS has changed in version 3.0.0 - it is now a no-sync location as mandated by Apple so the release is backward incompatible.


To open a database in default no-sync location (affects iOS *only*)::
To open a database in default no-sync location (affects iOS _only_)::

```js
SQLite.openDatabase({name: 'my.db', location: 'default'}, successcb, errorcb);
SQLite.openDatabase({ name: 'my.db', location: 'default' }, successcb, errorcb);
```

To specify a different location (affects iOS *only*):
To specify a different location (affects iOS _only_):

```js
SQLite.openDatabase({name: 'my.db', location: 'Library'}, successcb, errorcb);
SQLite.openDatabase({ name: 'my.db', location: 'Library' }, successcb, errorcb);
```

where the `location` option may be set to one of the following choices:
- `default`: `Library/LocalDatabase` subdirectory - *NOT* visible to iTunes and *NOT* backed up by iCloud
- `Library`: `Library` subdirectory - backed up by iCloud, *NOT* visible to iTunes

- `default`: `Library/LocalDatabase` subdirectory - _NOT_ visible to iTunes and _NOT_ backed up by iCloud
- `Library`: `Library` subdirectory - backed up by iCloud, _NOT_ visible to iTunes
- `Documents`: `Documents` subdirectory - visible to iTunes and backed up by iCloud
- `Shared`: app group's shared container - *see next section*
- `Shared`: app group's shared container - _see next section_

The original webSql style openDatabase still works and the location will implicitly default to 'default' option:

```js
SQLite.openDatabase("myDatabase.db", "1.0", "Demo", -1);
SQLite.openDatabase('myDatabase.db', '1.0', 'Demo', -1);
```

## Opening a database in an App Group's Shared Container (iOS)
Expand Down Expand Up @@ -386,38 +411,57 @@ In both `ios/MY_APP_NAME/Info.plist` and `ios/MY_APP_EXT_NAME/Info.plist` (along
When calling `SQLite.openDatabase` in your React Native code, you need to set the `location` param to `'Shared'`:

```js
SQLite.openDatabase({name: 'my.db', location: 'Shared'}, successcb, errorcb);
SQLite.openDatabase({ name: 'my.db', location: 'Shared' }, successcb, errorcb);
```

## Importing a pre-populated database.

You can import an existing - prepopulated database file into your application. Depending on your instructions in openDatabase call, the sqlite-storage will look at different places to locate you pre-populated database file.


Use this flavor of openDatabase call, if your folder is called www and data file is named the same as the dbName - testDB in this example

```js
SQLite.openDatabase({name : "testDB", createFromLocation : 1}, okCallback,errorCallback);
SQLite.openDatabase(
{ name: 'testDB', createFromLocation: 1 },
okCallback,
errorCallback
);
```

Use this flavor of openDatabase call if your folder is called data rather than www or your filename does not match the name of the db. In this case db is named testDB but the file is mydbfile.sqlite which is located in a data subdirectory of www

```js
SQLite.openDatabase({name : "testDB", createFromLocation : "~data/mydbfile.sqlite"}, okCallback,errorCallback);
SQLite.openDatabase(
{ name: 'testDB', createFromLocation: '~data/mydbfile.sqlite' },
okCallback,
errorCallback
);
```

Use this flavor of openDatabase call if your folder is not in application bundle but in app sandbox i.e. downloaded from some remote location. In this case the source file is located in data subdirectory of Documents location (iOS) or FilesDir (Android).

```js
SQLite.openDatabase({name : "testDB", createFromLocation : "/data/mydbfile.sqlite"}, okCallback,errorCallback);
SQLite.openDatabase(
{ name: 'testDB', createFromLocation: '/data/mydbfile.sqlite' },
okCallback,
errorCallback
);
```

## Additional options for pre-populated database file

You can provide additional instructions to sqlite-storage to tell it how to handle your pre-populated database file. By default, the source file is copied over to the internal location which works in most cases but sometimes this is not really an option particularly when the source db file is large. In such situations you can tell sqlite-storage you do not want to copy the file but rather use it in read-only fashion via direct access. You accomplish this by providing an additional optional readOnly parameter to openDatabase call

```js
SQLite.openDatabase({name : "testDB", readOnly: true, createFromLocation : "/data/mydbfile.sqlite"}, okCallback,errorCallback);
SQLite.openDatabase(
{
name: 'testDB',
readOnly: true,
createFromLocation: '/data/mydbfile.sqlite',
},
okCallback,
errorCallback
);
```

Note that in this case, the source db file will be open in read-only mode and no updates will be allowed. You cannot delete a database that was open with readOnly option. For Android, the read only option works with pre-populated db files located in FilesDir directory because all other assets are never physically located on the file system but rather read directly from the app bundle.
Expand All @@ -431,11 +475,18 @@ To archieve this, you need to open both databases and to call the attach()-metho
```js
let dbMaster, dbSecond;

dbSecond = SQLite.openDatabase({name: 'second'},
dbSecond = SQLite.openDatabase(
{ name: 'second' },
(db) => {
dbMaster = SQLite.openDatabase({name: 'master'},
dbMaster = SQLite.openDatabase(
{ name: 'master' },
(db) => {
dbMaster.attach( "second", "second", () => console.log("Database attached successfully"), () => console.log("ERROR"))
dbMaster.attach(
'second',
'second',
() => console.log('Database attached successfully'),
() => console.log('ERROR')
);
},
(err) => console.log("Error on opening database 'master'", err)
);
Expand All @@ -455,13 +506,14 @@ SELECT * FROM user INNER JOIN second.subscriptions s ON s.user_id = user.id
To detach a database, just use the detach()-method:

```js
dbMaster.detach( 'second', successCallback, errorCallback );
dbMaster.detach('second', successCallback, errorCallback);
```

For sure, their is also Promise-support available for attach() and detach(), as shown in the example-application under the
directory "examples".

# Original Cordova SQLite Bindings from Chris Brody and Davide Bertola

https://github.com/litehelpers/Cordova-sqlite-storage

The issues and limitations for the actual SQLite can be found on this site.
Expand Down
Binary file modified platforms/android-native/libs/arm64-v8a/libsqlc-native-driver.so
100755 → 100644
Binary file not shown.
Binary file modified platforms/android-native/libs/armeabi-v7a/libsqlc-native-driver.so
100755 → 100644
Binary file not shown.
Binary file modified platforms/android-native/libs/sqlite-connector.jar
Binary file not shown.
Binary file modified platforms/android-native/libs/x86/libsqlc-native-driver.so
100755 → 100644
Binary file not shown.
Binary file modified platforms/android-native/libs/x86_64/libsqlc-native-driver.so
100755 → 100644
Binary file not shown.