Working towards sqlcipher upgrade options.

Author: Chriztiaan

.changeset/rotten-pugs-beam.md

@@ -1,12 +1,12 @@
 ---
-'@powersync/op-sqlite': major
+'@powersync/op-sqlite': minor
 ---
 
 Initial stable version release.
 
-Updated op-sqlite upstream dependency from 11.x.x to 14.0.2, the @powersync/op-sqlite package will now reflect the supported major version in its version (for example 0.14.x indicates support for version of 14.x.x of op-sqlite).
+Updated op-sqlite upstream peer dependency from 11.x.x to support ^13.x.x and ^14.x.x,
 
-Noteworthy changes for 11 > 14 bump include:
+Noteworthy changes from version 11 to version 14 include:
 
 1. SQLite updated to 3.49.1
 2. Major/breaking update to SQLCipher 4.8. Be careful when upgrading to this version, your sqlcipher database will need to be updated as well (upgrading instructions [here](https://discuss.zetetic.net/t/upgrading-to-sqlcipher-4/3283)), read more on the [sqlcipher repo](https://github.com/sqlcipher/sqlcipher). Be sure to test your changes before upgrading.

packages/powersync-op-sqlite/package.json

@@ -65,7 +65,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@op-engineering/op-sqlite": "^14.0.2",
+    "@op-engineering/op-sqlite": "^13.0.0 || ^14.0.0",
     "@powersync/common": "workspace:^1.31.1",
     "react": "*",
     "react-native": "*"

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

@@ -3,7 +3,7 @@ import { BaseObserver, DBAdapter, DBAdapterListener, DBLockOptions, QueryResult,
 import Lock from 'async-lock';
 import { Platform } from 'react-native';
 import { OPSQLiteConnection } from './OPSQLiteConnection';
-import { SqliteOptions } from './SqliteOptions';
+import { CipherVersion, SqliteOptions } from './SqliteOptions';
 
 /**
  * Adapter for React Native Quick SQLite
@@ -50,7 +50,7 @@ export class OPSQLiteDBAdapter extends BaseObserver<DBAdapterListener> implement
       this.options.sqliteOptions!;
     const dbFilename = this.options.name;
 
-    this.writeConnection = await this.openConnection(dbFilename);
+    this.writeConnection = await this.openConnection(dbFilename, true);
 
     const baseStatements = [
       `PRAGMA busy_timeout = ${lockTimeoutMs}`,
@@ -97,9 +97,13 @@ export class OPSQLiteDBAdapter extends BaseObserver<DBAdapterListener> implement
     }
   }
 
-  protected async openConnection(filenameOverride?: string): Promise<OPSQLiteConnection> {
+  protected async openConnection(filenameOverride?: string, writeConnection?: boolean): Promise<OPSQLiteConnection> {
     const dbFilename = filenameOverride ?? this.options.name;
-    const DB: DB = this.openDatabase(dbFilename, this.options.sqliteOptions?.encryptionKey ?? undefined);
+    const DB: DB = await this.openDatabase(
+      dbFilename,
+      this.options.sqliteOptions?.encryptionKey ?? undefined,
+      writeConnection
+    );
 
     //Load extensions for all connections
     this.loadAdditionalExtensions(DB);
@@ -120,16 +124,12 @@ export class OPSQLiteDBAdapter extends BaseObserver<DBAdapterListener> implement
     }
   }
 
-  private openDatabase(dbFilename: string, encryptionKey?: string): DB {
+  private async openDatabase(dbFilename: string, encryptionKey?: string, writeConnection?: boolean): Promise<DB> {
     //This is needed because an undefined/null dbLocation will cause the open function to fail
     const location = this.getDbLocation(this.options.dbLocation);
     //Simarlily if the encryption key is undefined/null when using SQLCipher it will cause the open function to fail
     if (encryptionKey) {
-      return open({
-        name: dbFilename,
-        location: location,
-        encryptionKey: encryptionKey
-      });
+      return await this.openSQLCipher(dbFilename, location, encryptionKey, writeConnection);
     } else {
       return open({
         name: dbFilename,
@@ -138,6 +138,57 @@ export class OPSQLiteDBAdapter extends BaseObserver<DBAdapterListener> implement
     }
   }
 
+  /**
+   * We set up SQLCipher compatibility here.
+   *
+   * - For compability with SQLCipher 3 databases, we set the cipher_compatibility pragma to 3 for all connections.
+   * - For upgrading SQLCipher 3 databases to version 4, we do the migration on the write connection.
+   * - For SQLCipher 4 databases, we do not need to set the cipher_compatibility pragma, as it is the default.
+   */
+  private async openSQLCipher(
+    dbFilename: string,
+    location: string,
+    encryptionKey?: string,
+    writeConnection?: boolean
+  ): Promise<DB> {
+    const openDb = () =>
+      open({
+        name: dbFilename,
+        location: location,
+        encryptionKey: encryptionKey
+      });
+    const db = openDb();
+
+    const cipherVersion = this.options.sqliteOptions?.cipherVersion;
+
+    if (cipherVersion == CipherVersion.VERSION_3) {
+      await db.execute('PRAGMA cipher_compatibility = 3;');
+      return db;
+    } else if (cipherVersion == CipherVersion.UPGRADE_3_TO_4 && writeConnection) {
+      // Based on steps described at https://www.zetetic.net/sqlcipher/sqlcipher-api/#cipher_migrate
+      try {
+        // Valid version agnostic query to confirm SQLCipher version
+        await db.execute('SELECT count(*) FROM sqlite_master;');
+        // Query succeeded, so we are on SQLCipher 4 and don't have to do anything
+        console.log('SQLCipher 4 database detected, no migration needed.');
+        return db;
+      } catch (e: any) {
+        // Query failed, assuming we are on SQLCipher 3 and need to upgrade
+        // Catch any error
+      }
+
+      db.close();
+      const reopenedDB = openDb();
+
+      const migrationResult = await reopenedDB.execute('PRAGMA cipher_migrate;');
+      console.log('SQLCipher migration result:', migrationResult);
+
+      return reopenedDB;
+    }
+
+    return db;
+  }
+
   private loadAdditionalExtensions(DB: DB) {
     if (this.options.sqliteOptions?.extensions && this.options.sqliteOptions.extensions.length > 0) {
       for (const extension of this.options.sqliteOptions.extensions) {

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

@@ -30,6 +30,18 @@ export interface SqliteOptions {
    */
   encryptionKey?: string | null;
 
+  /**
+   * SQLCipher version compatibility option. Only applicable when encryptionKey is set.
+   *
+   * - '4': Use SQLCipher 4 format (recommended for new databases)
+   * - 'upgrade3to4': Automatically attempt to upgrade SQLCipher 3 databases to version 4
+   * - '3': Use SQLCipher 3 compatibility mode for existing databases (used by default)
+   *
+   * Note: The 'upgrade3to4' option will attempt migration only when needed and may
+   * be expensive on first run. Migration requires the correct encryption key.
+   */
+  cipherVersion?: CipherVersion | null;
+
   /**
    * Where to store SQLite temporary files. Defaults to 'MEMORY'.
    * Setting this to `FILESYSTEM` can cause issues with larger queries or datasets.
@@ -55,6 +67,12 @@ export interface SqliteOptions {
   }>;
 }
 
+export enum CipherVersion {
+  VERSION_4 = '4',
+  UPGRADE_3_TO_4 = 'upgrade3to4',
+  VERSION_3 = '3'
+}
+
 export enum TemporaryStorageOption {
   MEMORY = 'memory',
   FILESYSTEM = 'file'
@@ -89,5 +107,6 @@ export const DEFAULT_SQLITE_OPTIONS: Required<SqliteOptions> = {
   temporaryStorage: TemporaryStorageOption.MEMORY,
   lockTimeoutMs: 30000,
   encryptionKey: null,
+  cipherVersion: CipherVersion.VERSION_3,
   extensions: []
 };

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

@@ -1,4 +1,3 @@
-export {
-  OPSqliteOpenFactory,
-  OPSQLiteOpenFactoryOptions
-} from './db/OPSqliteDBOpenFactory';
+export { OPSqliteOpenFactory, OPSQLiteOpenFactoryOptions } from './db/OPSqliteDBOpenFactory';
+
+export * from './db/SqliteOptions';