Docs

Author: simolus3

.changeset/hungry-spiders-perform.md

@@ -0,0 +1,5 @@
+---
+'@powersync/node': minor
+---
+
+Experimental support for integrating with node:sqlite.

.changeset/khaki-years-design.md

@@ -0,0 +1,5 @@
+---
+'@powersync/node': minor
+---
+
+Support custom better-sqlite3 forks (see an example for encryption in the README).

.changeset/wet-cooks-dress.md

@@ -0,0 +1,5 @@
+---
+'@powersync/node': minor
+---
+
+Use upstream better-sqlite3 dependency instead of the PowerSync fork.

packages/node/README.md

@@ -15,9 +15,9 @@ See a summary of features [here](https://docs.powersync.com/client-sdk-reference
 
 The `@powersync/node` package is currently in a Beta release.
 
-# Installation
+## Installation
 
-## Install Package
+### Install Package
 
 ```bash
 npm install @powersync/node better-sqlite3
@@ -47,38 +47,119 @@ To resolve this, either:
 - Upgrade `node-gyp` to version 10 or later.
 - Install Python [setuptools](https://pypi.org/project/setuptools/), which includes `distutils`.
 
-# Getting Started
+#### Package better-sqlite3 not found errors
+
+This package does not import `better-sqlite3` statically (with unconditional `require()` or static `import` statements).
+Instead, to allow users to us custom `better-sqlite3` forks, a dynamic `require()` / `import` expression is used.
+This may prevent bundlers from detecting that `better-sqlite3` is used by this package.
+
+To fix this, ensure you have a dependency on `better-sqlite3` (and, if you're using TypeScript, a dev-dependency on
+`@types/better-sqlite3`).
+
+In your project, create a `PowerSync.worker.ts` file with the following contents:
+
+```TypeScript
+import Database from 'better-sqlite3';
+
+import { startPowerSyncWorker } from '@powersync/node/worker.js';
+
+async function resolveBetterSqlite3() {
+  return Database;
+}
+
+startPowerSyncWorker({ loadBetterSqlite3: resolveBetterSqlite3 });
+```
+
+Finally, when you open the `PowerSyncDatabase`, instruct PowerSync to use your custom worker:
+
+```TypeScript
+const db = new PowerSyncDatabase({
+  schema: AppSchema,
+  database: {
+    dbFilename: 'test.db',
+    openWorker: (_, options) => {
+      return new Worker(new URL('./PowerSync.worker.js', import.meta.url), options);
+    }
+  },
+  logger
+});
+```
+
+## Getting Started
 
 The [Node.js SDK reference](https://docs.powersync.com/client-sdk-references/node)
 contains everything you need to know to get started implementing PowerSync in your project.
 
-# Examples
+## Examples
 
 A simple example using `@powersync/node` is available in the [`demos/example-node/`](../demos/example-node) directory.
 
-# Proxy Support
+## Proxy Support
 
 This SDK supports HTTP, HTTPS, and WebSocket proxies via environment variables.
 
-## HTTP Connection Method
+### HTTP Connection Method
 
 Internally we probe the http environment variables and apply it to fetch requests ([undici](https://www.npmjs.com/package/undici/v/5.6.0))
 
 - Set the `HTTPS_PROXY` or `HTTP_PROXY` environment variable to automatically route HTTP requests through a proxy.
 
-## WEB Socket Connection Method
+### WEB Socket Connection Method
 
 Internally the [proxy-agent](https://www.npmjs.com/package/proxy-agent) dependency for WebSocket proxies, which has its own internal code for automatically picking up the appropriate environment variables:
 
 - Set the `WS_PROXY` or `WSS_PROXY` environment variable to route the webocket connections through a proxy.
 
-# Found a bug or need help?
+## Encryption
+
+This package can be used with the [`better-sqlite3-multiple-ciphers`](https://www.npmjs.com/package/better-sqlite3-multiple-ciphers) fork of `better-sqlite3` for encryption.
+
+This requires a custom worker loading the forked package:
+
+```TypeScript
+// encryption.worker.ts
+import Database from 'better-sqlite3-multiple-ciphers';
+
+import { startPowerSyncWorker } from '@powersync/node/worker.js';
+
+async function resolveBetterSqlite3() {
+  return Database;
+}
+
+startPowerSyncWorker({ loadBetterSqlite3: resolveBetterSqlite3 });
+```
+
+Then, when opening the database, use that custom worker:
+
+```TypeScript
+const db = new PowerSyncDatabase({
+  schema: AppSchema,
+  database: {
+    dbFilename: 'test.db',
+    openWorker: (_, options) => {
+      return new Worker(new URL('./PowerSync.worker.js', import.meta.url), options);
+    },
+    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
+});
+```
+
+## Found a bug or need help?
 
 - Join our [Discord server](https://discord.gg/powersync) where you can browse topics from our community, ask questions, share feedback, or just say hello :)
 - Please open a [GitHub issue](https://github.com/powersync-ja/powersync-js/issues) when you come across a bug.
 - Have feedback or an idea? [Submit an idea](https://roadmap.powersync.com/tabs/5-roadmap/submit-idea) via our public roadmap or [schedule a chat](https://calendly.com/powersync-product/powersync-chat) with someone from our product team.
 
-# Thanks
+## Thanks
 
 The PowerSync Node.js SDK relies on the work contributors and maintainers have put into the upstream better-sqlite3 package.
 In particular, we'd like to thank [@spinda](https://github.com/spinda) for contributing support for update, commit and rollback hooks!