feat(op-sqlite): allow extensions to be loaded (#469)

.changeset/hip-poems-repair.md

@@ -0,0 +1,6 @@
+---
+'@powersync/op-sqlite': minor
+---
+
+* Allow users to load additional sqlite extensions
+* Remove `getBundledPath` function as `getDylibPath` can now be used instead

packages/powersync-op-sqlite/README.md

@@ -68,6 +68,42 @@ const factory = new OPSqliteOpenFactory({
 });
 ```
 
+### 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`:
+
+```js
+sqliteOptions: {
+  extensions: [
+      { path: libPath, entryPoint: 'sqlite3_powersync_init' }
+  ]
+}
+```
+
+More info can be found in the [OP-SQLite docs](https://op-engineering.github.io/op-sqlite/docs/api/#loading-extensions).
+
+Example usage:
+
+```ts
+import { getDylibPath } from '@op-engineering/op-sqlite';
+
+let libPath: string
+if (Platform.OS === 'ios') {
+  libPath = getDylibPath('co.powersync.sqlitecore', 'powersync-sqlite-core')
+} else {
+  libPath = 'libpowersync';
+}
+
+const factory = new OPSqliteOpenFactory({
+  dbFilename: 'sqlite.db',
+  sqliteOptions: {
+    extensions: [
+        { path: libPath, entryPoint: 'sqlite3_powersync_init' }
+    ]
+  }
+});
+```
+
 ## Native Projects
 
 This package uses native libraries. Create native Android and iOS projects (if not created already) by running:

packages/powersync-op-sqlite/android/src/main/java/com/powersync/opsqlite/PowerSyncOpSqlitePackage.kt

@@ -9,20 +9,16 @@ import java.util.HashMap
 
 class PowerSyncOpSqlitePackage : TurboReactPackage() {
   override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
-    return if (name == PowerSyncOpSqliteModule.NAME) {
-      PowerSyncOpSqliteModule(reactContext)
-    } else {
-      null
-    }
+    return null
   }
 
   override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
     return ReactModuleInfoProvider {
       val moduleInfos: MutableMap<String, ReactModuleInfo> = HashMap()
       val isTurboModule: Boolean = BuildConfig.IS_NEW_ARCHITECTURE_ENABLED
-      moduleInfos[PowerSyncOpSqliteModule.NAME] = ReactModuleInfo(
-        PowerSyncOpSqliteModule.NAME,
-        PowerSyncOpSqliteModule.NAME,
+      moduleInfos["PowerSyncOpSqlite"] = ReactModuleInfo(
+        "PowerSyncOpSqlite",
+        "PowerSyncOpSqlite",
         false,  // canOverrideExistingModule
         false,  // needsEagerInit
         true,  // hasConstants

packages/powersync-op-sqlite/ios/PowerSyncOpSqlite.mm

@@ -3,9 +3,4 @@
 @implementation PowerSyncOpSqlite
 RCT_EXPORT_MODULE()
 
-RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getBundlePath)
-{
-    return [NSBundle mainBundle].bundlePath;
-}
-
 @end

packages/powersync-op-sqlite/src/db/OPSqliteAdapter.ts

@@ -1,8 +1,21 @@
-import { BaseObserver, DBAdapter, DBAdapterListener, DBLockOptions, QueryResult, Transaction } from '@powersync/common';
-import { ANDROID_DATABASE_PATH, IOS_LIBRARY_PATH, open, type DB } from '@op-engineering/op-sqlite';
+import {
+  BaseObserver,
+  DBAdapter,
+  DBAdapterListener,
+  DBLockOptions,
+  QueryResult,
+  Transaction
+} from '@powersync/common';
+import {
+  ANDROID_DATABASE_PATH,
+  getDylibPath,
+  IOS_LIBRARY_PATH,
+  open,
+  type DB
+} from '@op-engineering/op-sqlite';
 import Lock from 'async-lock';
 import { OPSQLiteConnection } from './OPSQLiteConnection';
-import { NativeModules, Platform } from 'react-native';
+import { Platform } from 'react-native';
 import { SqliteOptions } from './SqliteOptions';
 
 /**
@@ -44,7 +57,7 @@ export class OPSQLiteDBAdapter extends BaseObserver<DBAdapterListener> implement
   }
 
   protected async init() {
-    const { lockTimeoutMs, journalMode, journalSizeLimit, synchronous, encryptionKey } = this.options.sqliteOptions;
+    const { lockTimeoutMs, journalMode, journalSizeLimit, synchronous } = this.options.sqliteOptions!;
     const dbFilename = this.options.name;
 
     this.writeConnection = await this.openConnection(dbFilename);
@@ -86,10 +99,11 @@ export class OPSQLiteDBAdapter extends BaseObserver<DBAdapterListener> implement
 
   protected async openConnection(filenameOverride?: string): Promise<OPSQLiteConnection> {
     const dbFilename = filenameOverride ?? this.options.name;
-    const DB: DB = this.openDatabase(dbFilename, this.options.sqliteOptions.encryptionKey);
+    const DB: DB = this.openDatabase(dbFilename, this.options.sqliteOptions?.encryptionKey ?? undefined);
 
-    //Load extension for all connections
-    this.loadExtension(DB);
+    //Load extensions for all connections
+    this.loadAdditionalExtensions(DB);
+    this.loadPowerSyncExtension(DB);
 
     await DB.execute('SELECT powersync_init()');
 
@@ -124,10 +138,17 @@ export class OPSQLiteDBAdapter extends BaseObserver<DBAdapterListener> implement
     }
   }
 
-  private loadExtension(DB: DB) {
+  private loadAdditionalExtensions(DB: DB) {
+    if (this.options.sqliteOptions?.extensions && this.options.sqliteOptions.extensions.length > 0) {
+      for (const extension of this.options.sqliteOptions.extensions) {
+        DB.loadExtension(extension.path, extension.entryPoint);
+      }
+    }
+  }
+
+  private async loadPowerSyncExtension(DB: DB) {
     if (Platform.OS === 'ios') {
-      const bundlePath: string = NativeModules.PowerSyncOpSqlite.getBundlePath();
-      const libPath = `${bundlePath}/Frameworks/powersync-sqlite-core.framework/powersync-sqlite-core`;
+      const libPath = getDylibPath('co.powersync.sqlitecore', 'powersync-sqlite-core');
       DB.loadExtension(libPath, 'sqlite3_powersync_init');
     } else {
       DB.loadExtension('libpowersync', 'sqlite3_powersync_init');
@@ -271,8 +292,10 @@ export class OPSQLiteDBAdapter extends BaseObserver<DBAdapterListener> implement
     await this.initialized;
     await this.writeConnection!.refreshSchema();
 
-    for (let readConnection of this.readConnections) {
-      await readConnection.connection.refreshSchema();
+    if(this.readConnections) {
+      for (let readConnection of this.readConnections) {
+        await readConnection.connection.refreshSchema();
+      }
     }
   }
 }

packages/powersync-op-sqlite/src/db/SqliteOptions.ts

@@ -28,7 +28,16 @@ export interface SqliteOptions {
    * Encryption key for the database.
    * If set, the database will be encrypted using SQLCipher.
    */
-  encryptionKey?: string;
+  encryptionKey?: string | null;
+
+  /**
+   * Load extensions using the path and entryPoint.
+   * More info can be found here https://op-engineering.github.io/op-sqlite/docs/api#loading-extensions.
+   */
+  extensions?: Array<{
+    path: string;
+    entryPoint?: string;
+  }>;
 }
 
 // SQLite journal mode. Set on the primary connection.
@@ -57,5 +66,6 @@ export const DEFAULT_SQLITE_OPTIONS: Required<SqliteOptions> = {
   synchronous: SqliteSynchronous.normal,
   journalSizeLimit: 6 * 1024 * 1024,
   lockTimeoutMs: 30000,
-  encryptionKey: null
+  encryptionKey: null,
+  extensions: []
 };

packages/powersync-op-sqlite/src/index.ts

@@ -1,30 +1,4 @@
-import { NativeModules, Platform } from 'react-native';
-
-const LINKING_ERROR =
-  `The package '@powersync/op-sqlite' doesn't seem to be linked. Make sure: \n\n` +
-  Platform.select({ ios: "- You have run 'pod install'\n", default: '' }) +
-  '- You rebuilt the app after installing the package\n' +
-  '- You are not using Expo Go\n';
-
-const isTurboModuleEnabled = global.__turboModuleProxy != null;
-
-const PowerSyncOpSqliteModule = isTurboModuleEnabled
-  ? require('./NativePowerSyncOpSqlite').default
-  : NativeModules.PowerSyncOpSqlite;
-
-const PowerSyncOpSqlite = PowerSyncOpSqliteModule
-  ? PowerSyncOpSqliteModule
-  : new Proxy(
-      {},
-      {
-        get() {
-          throw new Error(LINKING_ERROR);
-        }
-      }
-    );
-
-export function getBundlePath(): string {
-  return PowerSyncOpSqlite.getBundlePath();
-}
-
-export { OPSqliteOpenFactory, OPSQLiteOpenFactoryOptions } from './db/OPSqliteDBOpenFactory';
+export {
+  OPSqliteOpenFactory,
+  OPSQLiteOpenFactoryOptions
+} from './db/OPSqliteDBOpenFactory';

packages/powersync-op-sqlite/tsconfig.json

@@ -10,6 +10,7 @@
     "noEmit": true,
     "noFallthroughCasesInSwitch": true,
     "skipLibCheck": true,
+    "strict": true,
     "esModuleInterop": true
   },
   "references": [