OP-SQLite Factory for the PowerSync React Native SDK

Overview

This package (packages/powersync-op-sqlite) enables using OP-SQLite with PowerSync alongside the React Native SDK.

If you are not yet familiar with PowerSync, please see the PowerSync React Native SDK README for more information.

Installation

Follow the installation instructions for the React Native SDK if you haven't yet set up PowerSync in your project. However, note that this package cannot be installed alongside @journeyapps/react-native-quick-sqlite. Skip the step about installing it as a peer dependency, or uninstall it if it is already installed.

Install Package

1npx expo install @powersync/op-sqlite

When using this package without a frameowrk like Expo, we recommend adding this metro config to avoid issues related to bundling PowerSync. Without it, you may be getting TypeError: Cannot read property 'PowerSyncDatabase' of undefined or similar errors.

Install Peer Dependency:

This SDK currently requires @op-engineering/op-sqlite as a peer dependency.

Install it in your app with:

1npx expo install @op-engineering/op-sqlite

Usage

1import { OPSqliteOpenFactory } from '@powersync/op-sqlite';
2import { PowerSyncDatabase } from '@powersync/react-native';
3
4const factory = new OPSqliteOpenFactory({
5  dbFilename: 'sqlite.db'
6});
7
8this.powersync = new PowerSyncDatabase({ database: factory, schema: AppSchema });

Encryption with SQLCipher

To enable SQLCipher you need to add the following configuration option to your application's package.json. Note that for monorepos you may have to add this configuration to the monorepo root package.json instead, this depends on where your package manager tool hoists modules.

1{
2  // your normal package.json
3  // ...
4  "op-sqlite": {
5    "sqlcipher": true
6  }
7}

Additionally you will need to add an encryption key to the OPSQLite factory constructor

1const factory = new OPSqliteOpenFactory({
2  dbFilename: 'sqlite.db',
3  sqliteOptions: {
4    encryptionKey: 'your-encryption-key'
5  }
6});

Loading SQLite extensions

To load additional SQLite extensions include the extensions option in sqliteOptions which expects an array of objects with a path and an entryPoint:

1sqliteOptions: {
2  extensions: [{ path: libPath, entryPoint: 'sqlite3_powersync_init' }];
3}

More info can be found in the OP-SQLite docs.

Example usage:

1import { getDylibPath } from '@op-engineering/op-sqlite';
2
3let libPath: string;
4if (Platform.OS === 'ios') {
5  libPath = getDylibPath('co.powersync.sqlitecore', 'powersync-sqlite-core');
6} else {
7  libPath = 'libpowersync';
8}
9
10const factory = new OPSqliteOpenFactory({
11  dbFilename: 'sqlite.db',
12  sqliteOptions: {
13    extensions: [{ path: libPath, entryPoint: 'sqlite3_powersync_init' }]
14  }
15});

Native Projects

This package uses native libraries. Create native Android and iOS projects (if not created already) by running:

1npx expo run:android
2# OR
3npx expo run:ios