Encryption example

Author: simolus3

demos/example-node/.env

@@ -1,4 +1,5 @@
 BACKEND=http://localhost:6060
 SYNC_SERVICE=http://localhost:8080
 POWERSYNC_TOKEN=
-POWERSYNC_DEBUG=1
+POWERSYNC_DEBUG=1
+ENCRYPTION_KEY=

demos/example-node/README.md

@@ -15,6 +15,13 @@ Results from the query are printed every time it changes. Try:
 1. Updating a row in the backend database and see changes reflected in the running client.
 2. Enter `add('my list')` and see the new list show up in the backend database.
 
+## Encryption
+
+This demo can use encrypted databases with the `better-sqlite3-multiple-ciphers` package.
+To test encryption, set the `ENCRYPTION_KEY` in `.env` to a non-empty value.
+
+## References
+
 For more details, see the documentation for [the PowerSync node package](https://docs.powersync.com/client-sdk-references/node) and check other examples:
 
 - [example-electron-node](../example-electron-node/): An Electron example that runs PowerSync in the main process using the Node.js SDK.

demos/example-node/package.json

@@ -11,10 +11,13 @@
   },
   "dependencies": {
     "@powersync/node": "workspace:*",
+    "better-sqlite3": "^12.2.0",
+    "better-sqlite3-multiple-ciphers": "^12.2.0",
     "dotenv": "^16.4.7",
     "undici": "^7.11.0"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.2"
   }

demos/example-node/src/encryption.worker.ts

@@ -0,0 +1,12 @@
+// This worker uses bindings to sqlite3 multiple ciphers instead of the original better-sqlite3 worker.
+//
+// It is used in main.ts only when an encryption key is set.
+import Database from 'better-sqlite3-multiple-ciphers';
+
+import { startPowerSyncWorker } from '@powersync/node/worker.js';
+
+async function resolveBetterSqlite3() {
+  return Database;
+}
+
+startPowerSyncWorker({ loadBetterSqlite3: resolveBetterSqlite3 });

demos/example-node/src/main.ts

@@ -1,5 +1,6 @@
 import { once } from 'node:events';
 import repl_factory from 'node:repl';
+import { Worker } from 'node:worker_threads';
 
 import {
   createBaseLogger,
@@ -11,11 +12,14 @@ import {
 import { exit } from 'node:process';
 import { AppSchema, DemoConnector } from './powersync.js';
 import { enableUncidiDiagnostics } from './UndiciDiagnostics.js';
+import { WorkerOpener } from 'node_modules/@powersync/node/src/db/options.js';
+import { LockContext } from 'node_modules/@powersync/node/dist/bundle.cjs';
 
 const main = async () => {
   const baseLogger = createBaseLogger();
   const logger = createLogger('PowerSyncDemo');
   const debug = process.env.POWERSYNC_DEBUG == '1';
+  const encryptionKey = process.env.ENCRYPTION_KEY ?? '';
   baseLogger.useDefaults({ defaultLevel: debug ? logger.TRACE : logger.WARN });
 
   // Enable detailed request/response logging for debugging purposes.
@@ -30,10 +34,27 @@ const main = async () => {
     return;
   }
 
+  let customWorker: WorkerOpener | undefined;
+  if (encryptionKey.length) {
+    customWorker = (_, options) => {
+      return new Worker(new URL('./encryption.worker.js', import.meta.url), options);
+    };
+  }
+
   const db = new PowerSyncDatabase({
     schema: AppSchema,
     database: {
-      dbFilename: 'test.db'
+      dbFilename: 'test.db',
+      openWorker: customWorker,
+      initializeConnection: async (db) => {
+        if (encryptionKey.length) {
+          const escapedKey = encryptionKey.replace("'", "''");
+          await db.execute(`pragma key = '${escapedKey}'`);
+        }
+
+        // Make sure the database is readable, this fails early if the key is wrong.
+        await db.execute('pragma user_version');
+      }
     },
     logger
   });

packages/node/README.md

@@ -20,7 +20,7 @@ The `@powersync/node` package is currently in a Beta release.
 ## Install Package
 
 ```bash
-npm install @powersync/node
+npm install @powersync/node better-sqlite3
 ```
 
 Both `@powersync/node` and the `better-sqlite3` packages have install scripts that need to run to compile

packages/node/src/db/BetterSqliteWorker.ts

@@ -65,11 +65,7 @@ class BlockingAsyncDatabase implements AsyncDatabase {
 export async function openDatabase(worker: PowerSyncWorkerOptions, options: AsyncDatabaseOpenOptions) {
   const BetterSQLite3Database = await worker.loadBetterSqlite3();
   const baseDB = new BetterSQLite3Database(options.path);
-  baseDB.pragma('journal_mode = WAL');
   baseDB.loadExtension(worker.extensionPath(), 'sqlite3_powersync_init');
-  if (!options.isWriter) {
-    baseDB.pragma('query_only = true');
-  }
 
   const asyncDb = new BlockingAsyncDatabase(baseDB);
   return asyncDb;

packages/node/src/db/NodeSqliteWorker.ts

@@ -57,11 +57,7 @@ export async function openDatabase(worker: PowerSyncWorkerOptions, options: Asyn
   const { DatabaseSync } = await dynamicImport('node:sqlite');
 
   const baseDB = new DatabaseSync(options.path, { allowExtension: true });
-  baseDB.exec('pragma journal_mode = WAL');
   baseDB.loadExtension(worker.extensionPath());
-  if (!options.isWriter) {
-    baseDB.exec('pragma query_only = true');
-  }
 
   return new BlockingNodeDatabase(baseDB, options.isWriter);
 }

packages/node/src/db/WorkerConnectionPool.ts

@@ -131,7 +131,17 @@ export class WorkerConnectionPool extends BaseObserver<DBAdapterListener> implem
         await database.execute("SELECT powersync_update_hooks('install');", []);
       }
 
-      return new RemoteConnection(worker, comlink, database);
+      const connection = new RemoteConnection(worker, comlink, database);
+      if (this.options.initializeConnection) {
+        await this.options.initializeConnection(connection, isWriter);
+      }
+
+      await connection.execute('pragma journal_mode = WAL');
+      if (!isWriter) {
+        await connection.execute('pragma query_only = true');
+      }
+
+      return connection;
     };
 
     // Open the writer first to avoid multiple threads enabling WAL concurrently (causing "database is locked" errors).

packages/node/src/db/options.ts

@@ -1,5 +1,5 @@
 import { type Worker } from 'node:worker_threads';
-import { SQLOpenOptions } from '@powersync/common';
+import { LockContext, SQLOpenOptions } from '@powersync/common';
 
 export type WorkerOpener = (...args: ConstructorParameters<typeof Worker>) => InstanceType<typeof Worker>;
 
@@ -41,4 +41,11 @@ export interface NodeSQLOpenOptions extends SQLOpenOptions {
    * @returns the resolved worker.
    */
   openWorker?: WorkerOpener;
+
+  /**
+   * Initializes a created database connection.
+   *
+   * This can be used to e.g. set encryption keys, if an encrypted database should be used.
+   */
+  initializeConnection?: (db: LockContext, isWriter: boolean) => Promise<void>;
 }