This is a fork of https://github.com/andpor/react-native-sqlite-storage in order to:
SQLite3 Native Plugin for React Native for both Android & iOS.
Features:
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.
Please let me know your projects that use these SQLite React Native modules. I will list them in the reference section. If there are any features that you think would benefit this library please post them.
The library has been tested with React 18.2, React Native 0.72.0 and XCode 15.4 - it works fine out of the box without any need for tweaks or code changes.
# Install this lib as an alias of react-native-sqlite-storage
yarn add react-native-sqlite-storage@npm:@boltcode/react-native-sqlite-storage
# Add typescript if need
yarn add -D @types/react-native-sqlite-storageAs react-native-sqlite-storage original repository is kind of industry standard for React Native and is used in a lot of awesome library (typeorm for example),
using an alias make us able to use this package as it was the original one, so package that depend on react-native-sqlite-storage will not break.
Also note that you should continue to import the library like:
# CommonJS
var SQLite = require('react-native-sqlite-storage');
# Typescript
import SQLite from 'react-native-sqlite-storage';Don't forget to run cd ios && pod install && cd .. to link the library with iOS.
Since we now only use the SQLite version bundled with this library, there is no extra steps on Android.
Note: if you come from the original repository you may delete what you added in react-native.config.js under dependency -> platforms -> android.
Promise are not enable by default, if you want to enable it, run:
SQLite.enablePromise(false);In the following documentation, we consider enablePromise is enable.
Opening a database is slightly different between iOS and Android. Where as on Android the location of the database file is fixed, there are three choices of where the database file can be located on iOS. The 'location' parameter you provide to openDatabase call indicated where you would like the file to be created. This parameter is neglected on Android.
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)::
const db = await SQLite.openDatabase({name: 'my.db', location: 'default'});To specify a different location (affects iOS only):
const db = await SQLite.openDatabase({name: 'my.db', location: 'Library'});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 iCloudLibrary: Library subdirectory - backed up by iCloud, NOT visible to iTunesDocuments: Documents subdirectory - visible to iTunes and backed up by iCloudShared: app group's shared container - see next sectionIf you have an iOS app extension which needs to share access to the same DB instance as your main app, you must use the shared container of a registered app group.
Assuming you have already set up an app group and turned on the "App Groups" entitlement of both the main app and app extension, setting them to the same app group name, the following extra steps must be taken:
Info.plistsIn both ios/MY_APP_NAME/Info.plist and ios/MY_APP_EXT_NAME/Info.plist (along with any other app extensions you may have), you simply need to add the AppGroupName key to the main dictionary with your app group name as the string value:
<plist version="1.0">
<dict>
<!-- ... -->
<key>AppGroupName</key>
<string>MY_APP_GROUP_NAME</string>
<!-- ... -->
</dict>
</plist>When calling SQLite.openDatabase in your React Native code, you need to set the location param to 'Shared':
await SQLite.openDatabase({name: 'my.db', location: 'Shared'});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
await SQLite.openDatabase({name : "testDB", createFromLocation : 1});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
await SQLite.openDatabase({name : "testDB", createFromLocation : "~data/mydbfile.sqlite"});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).
await SQLite.openDatabase({name : "testDB", createFromLocation : "/data/mydbfile.sqlite"});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
await SQLite.openDatabase({name : "testDB", readOnly: true, createFromLocation : "/data/mydbfile.sqlite"});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.
Sqlite3 offers the capability to attach another database to an existing database-instance, i.e. for making cross database JOINs available. This feature allows to SELECT and JOIN tables over multiple databases with only one statement and only one database connection. To archieve this, you need to open both databases and to call the attach()-method of the destination (or master) -database to the other ones.
const dbSecond = await SQLite.openDatabase({name: 'second'});
const dbMaster = await SQLite.openDatabase({name: 'master'});
await dbMaster.attach("second", "second");The first argument of attach() is the name of the database, which is used in SQLite.openDatabase(). The second argument is the alias, that is used to query on tables of the attached database.
The following statement would select data from the master database and include the "second"-database within a simple SELECT/JOIN-statement:
SELECT * FROM user INNER JOIN second.subscriptions s ON s.user_id = user.idTo detach a database, just use the detach()-method:
await dbMaster.detach('second');For sure, their is also Callback-support available for attach() and detach().
Thank you to all authors & contributors of the following repository, PR, issues, without whom it would not have been possible:
If you want to know how this repository is build & managed, you can follow the documentation under docs folder