@powersync/op-sqlite 0.0.0-dev-20241014162857

package/src/db/OPSqliteAdapter.ts

@@ -0,0 +1,259 @@
+import {
+  BaseObserver,
+  DBAdapter,
+  DBAdapterListener,
+  DBLockOptions,
+  QueryResult,
+  SQLOpenOptions,
+  Transaction
+} from '@powersync/common';
+import { ANDROID_DATABASE_PATH, 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 { DEFAULT_SQLITE_OPTIONS, SqliteOptions } from './SqliteOptions';
+
+/**
+ * Adapter for React Native Quick SQLite
+ */
+export type OPSQLiteAdapterOptions = {
+  name: string;
+  dbLocation?: string;
+  sqliteOptions?: SqliteOptions;
+};
+
+enum LockType {
+  READ = 'read',
+  WRITE = 'write'
+}
+
+const READ_CONNECTIONS = 5;
+
+export class OPSQLiteDBAdapter extends BaseObserver<DBAdapterListener> implements DBAdapter {
+  name: string;
+  protected locks: Lock;
+
+  protected initialized: Promise<void>;
+
+  protected readConnections: OPSQLiteConnection[] | null;
+
+  protected writeConnection: OPSQLiteConnection | null;
+
+  constructor(protected options: OPSQLiteAdapterOptions) {
+    super();
+    this.name = this.options.name;
+
+    this.locks = new Lock();
+    this.readConnections = null;
+    this.writeConnection = null;
+    this.initialized = this.init();
+  }
+
+  protected async init() {
+    const { lockTimeoutMs, journalMode, journalSizeLimit, synchronous } = this.options.sqliteOptions;
+    // const { dbFilename, dbLocation } = this.options;
+    const dbFilename = this.options.name;
+    //This is needed because an undefined dbLocation will cause the open function to fail
+    const location = this.getDbLocation(this.options.dbLocation);
+    const DB: DB = open({
+      name: dbFilename,
+      location: location
+    });
+
+    const statements: string[] = [
+      `PRAGMA busy_timeout = ${lockTimeoutMs}`,
+      `PRAGMA journal_mode = ${journalMode}`,
+      `PRAGMA journal_size_limit = ${journalSizeLimit}`,
+      `PRAGMA synchronous = ${synchronous}`
+    ];
+
+    for (const statement of statements) {
+      for (let tries = 0; tries < 30; tries++) {
+        try {
+          await DB.execute(statement);
+          break;
+        } catch (e: any) {
+          if (e instanceof Error && e.message.includes('database is locked') && tries < 29) {
+            continue;
+          } else {
+            throw e;
+          }
+        }
+      }
+    }
+
+    this.loadExtension(DB);
+
+    await DB.execute('SELECT powersync_init()');
+
+    this.readConnections = [];
+    for (let i = 0; i < READ_CONNECTIONS; i++) {
+      // Workaround to create read-only connections
+      let dbName = './'.repeat(i + 1) + dbFilename;
+      const conn = await this.openConnection(location, dbName);
+      await conn.execute('PRAGMA query_only = true');
+      this.readConnections.push(conn);
+    }
+
+    this.writeConnection = new OPSQLiteConnection({
+      baseDB: DB
+    });
+
+    // Changes should only occur in the write connection
+    this.writeConnection!.registerListener({
+      tablesUpdated: (notification) => this.iterateListeners((cb) => cb.tablesUpdated?.(notification))
+    });
+  }
+
+  protected async openConnection(dbLocation: string, filenameOverride?: string): Promise<OPSQLiteConnection> {
+    const DB: DB = open({
+      name: filenameOverride ?? this.options.name,
+      location: dbLocation
+    });
+
+    //Load extension for all connections
+    this.loadExtension(DB);
+
+    await DB.execute('SELECT powersync_init()');
+
+    return new OPSQLiteConnection({
+      baseDB: DB
+    });
+  }
+
+  private getDbLocation(dbLocation?: string): string {
+    if (Platform.OS === 'ios') {
+      return dbLocation ?? IOS_LIBRARY_PATH;
+    } else {
+      return dbLocation ?? ANDROID_DATABASE_PATH;
+    }
+  }
+
+  private loadExtension(DB: DB) {
+    if (Platform.OS === 'ios') {
+      const bundlePath: string = NativeModules.PowerSyncOpSqlite.getBundlePath();
+      const libPath = `${bundlePath}/Frameworks/powersync-sqlite-core.framework/powersync-sqlite-core`;
+      DB.loadExtension(libPath, 'sqlite3_powersync_init');
+    } else {
+      DB.loadExtension('libpowersync', 'sqlite3_powersync_init');
+    }
+  }
+
+  close() {
+    this.initialized.then(() => {
+      this.writeConnection!.close();
+      this.readConnections!.forEach((c) => c.close());
+    });
+  }
+
+  async readLock<T>(fn: (tx: OPSQLiteConnection) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    await this.initialized;
+    // TODO: Use async queues to handle multiple read connections
+    const sortedConnections = this.readConnections!.map((connection, index) => ({
+      lockKey: `${LockType.READ}-${index}`,
+      connection
+    })).sort((a, b) => {
+      const aBusy = this.locks.isBusy(a.lockKey);
+      const bBusy = this.locks.isBusy(b.lockKey);
+      // Sort by ones which are not busy
+      return aBusy > bBusy ? 1 : 0;
+    });
+
+    return new Promise(async (resolve, reject) => {
+      try {
+        await this.locks.acquire(
+          sortedConnections[0].lockKey,
+          async () => {
+            resolve(await fn(sortedConnections[0].connection));
+          },
+          { timeout: options?.timeoutMs }
+        );
+      } catch (ex) {
+        reject(ex);
+      }
+    });
+  }
+
+  async writeLock<T>(fn: (tx: OPSQLiteConnection) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    await this.initialized;
+
+    return new Promise(async (resolve, reject) => {
+      try {
+        await this.locks.acquire(
+          LockType.WRITE,
+          async () => {
+            resolve(await fn(this.writeConnection!));
+          },
+          { timeout: options?.timeoutMs }
+        );
+      } catch (ex) {
+        reject(ex);
+      }
+    });
+  }
+
+  readTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    return this.readLock((ctx) => this.internalTransaction(ctx, fn));
+  }
+
+  writeTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    return this.writeLock((ctx) => this.internalTransaction(ctx, fn));
+  }
+
+  getAll<T>(sql: string, parameters?: any[]): Promise<T[]> {
+    return this.readLock((ctx) => ctx.getAll(sql, parameters));
+  }
+
+  getOptional<T>(sql: string, parameters?: any[]): Promise<T | null> {
+    return this.readLock((ctx) => ctx.getOptional(sql, parameters));
+  }
+
+  get<T>(sql: string, parameters?: any[]): Promise<T> {
+    return this.readLock((ctx) => ctx.get(sql, parameters));
+  }
+
+  execute(query: string, params?: any[]) {
+    return this.writeLock((ctx) => ctx.execute(query, params));
+  }
+
+  async executeBatch(query: string, params: any[][] = []): Promise<QueryResult> {
+    return this.writeLock((ctx) => ctx.executeBatch(query, params));
+  }
+
+  protected async internalTransaction<T>(
+    connection: OPSQLiteConnection,
+    fn: (tx: Transaction) => Promise<T>
+  ): Promise<T> {
+    let finalized = false;
+    const commit = async (): Promise<QueryResult> => {
+      if (finalized) {
+        return { rowsAffected: 0 };
+      }
+      finalized = true;
+      return connection.execute('COMMIT');
+    };
+    const rollback = async (): Promise<QueryResult> => {
+      if (finalized) {
+        return { rowsAffected: 0 };
+      }
+      finalized = true;
+      return connection.execute('ROLLBACK');
+    };
+    try {
+      await connection.execute('BEGIN');
+      const result = await fn({
+        execute: (query, params) => connection.execute(query, params),
+        get: (query, params) => connection.get(query, params),
+        getAll: (query, params) => connection.getAll(query, params),
+        getOptional: (query, params) => connection.getOptional(query, params),
+        commit,
+        rollback
+      });
+      await commit();
+      return result;
+    } catch (ex) {
+      await rollback();
+      throw ex;
+    }
+  }
+}

package/src/db/OPSqliteDBOpenFactory.ts

@@ -0,0 +1,25 @@
+import { DBAdapter, SQLOpenFactory, SQLOpenOptions } from '@powersync/common';
+import { OPSQLiteDBAdapter } from './OPSqliteAdapter';
+import { DEFAULT_SQLITE_OPTIONS, SqliteOptions } from './SqliteOptions';
+
+export interface OPSQLiteOpenFactoryOptions extends SQLOpenOptions {
+  sqliteOptions?: SqliteOptions;
+}
+export class OPSqliteOpenFactory implements SQLOpenFactory {
+  private sqliteOptions: Required<SqliteOptions>;
+
+  constructor(protected options: OPSQLiteOpenFactoryOptions) {
+    this.sqliteOptions = {
+      ...DEFAULT_SQLITE_OPTIONS,
+      ...this.options.sqliteOptions
+    };
+  }
+
+  openDB(): DBAdapter {
+    return new OPSQLiteDBAdapter({
+      name: this.options.dbFilename,
+      dbLocation: this.options.dbLocation,
+      sqliteOptions: this.sqliteOptions
+    });
+  }
+}

package/src/db/SqliteOptions.ts

@@ -0,0 +1,54 @@
+export interface SqliteOptions {
+  /**
+   * SQLite journal mode. Defaults to [SqliteJournalMode.wal].
+   */
+  journalMode?: SqliteJournalMode;
+
+  /**
+   * SQLite synchronous flag. Defaults to [SqliteSynchronous.normal], which
+   * is safe for WAL mode.
+   */
+  synchronous?: SqliteSynchronous;
+
+  /**
+   * Journal/WAL size limit. Defaults to 6MB.
+   * The WAL may grow larger than this limit during writes, but SQLite will
+   * attempt to truncate the file afterwards.
+   */
+  journalSizeLimit?: number;
+
+  /**
+   * Timeout in milliseconds waiting for locks to be released by other connections.
+   * Defaults to 30 seconds.
+   * Set to null or zero to fail immediately when the database is locked.
+   */
+  lockTimeoutMs?: number;
+}
+
+// SQLite journal mode. Set on the primary connection.
+// This library is written with WAL mode in mind - other modes may cause
+// unexpected locking behavior.
+enum SqliteJournalMode {
+  // Use a write-ahead log instead of a rollback journal.
+  // This provides good performance and concurrency.
+  wal = 'WAL',
+  delete = 'DELETE',
+  truncate = 'TRUNCATE',
+  persist = 'PERSIST',
+  memory = 'MEMORY',
+  off = 'OFF',
+}
+
+// SQLite file commit mode.
+enum SqliteSynchronous {
+  normal = 'NORMAL',
+  full = 'FULL',
+  off = 'OFF',
+}
+
+export const DEFAULT_SQLITE_OPTIONS: Required<SqliteOptions> = {
+  journalMode: SqliteJournalMode.wal,
+  synchronous: SqliteSynchronous.normal,
+  journalSizeLimit: 6 * 1024 * 1024,
+  lockTimeoutMs: 30000,
+};

package/src/index.ts

@@ -0,0 +1,30 @@
+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';