Improve documentation on dbLocation and related error message on node

.changeset/lazy-moons-prove.md

@@ -0,0 +1,5 @@
+---
+'@powersync/node': patch
+---
+
+Fix compilation errors on Windows.

.changeset/nice-steaks-approve.md

@@ -0,0 +1,5 @@
+---
+'@powersync/node': patch
+---
+
+Provide a more actionable error message when using the `dbLocation` option with a directory that doesn't exist.

packages/common/src/client/SQLOpenFactory.ts

@@ -7,6 +7,9 @@ export interface SQLOpenOptions {
   dbFilename: string;
   /**
    * Directory where the database file is located.
+   * 
+   * When set, the directory must exist when the database is opened, it will
+   * not be created automatically.
    */
   dbLocation?: string;
 

packages/node/package.json

@@ -46,7 +46,7 @@
     "@powersync/common": "workspace:^1.22.0"
   },
   "dependencies": {
-    "@powersync/better-sqlite3": "^0.1.0",
+    "@powersync/better-sqlite3": "^0.1.1",
     "@powersync/common": "workspace:*",
     "async-lock": "^1.4.0",
     "bson": "^6.6.0",

packages/node/src/db/BetterSQLite3DBAdapter.ts

@@ -1,3 +1,4 @@
+import fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { Worker } from 'node:worker_threads';
 import * as Comlink from 'comlink';
@@ -53,6 +54,19 @@ export class BetterSQLite3DBAdapter extends BaseObserver<DBAdapterListener> impl
   async initialize() {
     let dbFilePath = this.options.dbFilename;
     if (this.options.dbLocation !== undefined) {
+      // Make sure the dbLocation exists, we get a TypeError from better-sqlite3 otherwise.
+      let directoryExists = false;
+      try {
+        const stat = await fs.stat(this.options.dbLocation);
+        directoryExists = stat.isDirectory();
+      } catch (_) {
+        // If we can't even stat, the directory won't be accessible to SQLite either.
+      }
+
+      if (!directoryExists) {
+        throw new Error(`The dbLocation directory at "${this.options.dbLocation}" does not exist. Please create it before opening the PowerSync database!`);
+      }
+
       dbFilePath = path.join(this.options.dbLocation, dbFilePath);
     }
 
@@ -65,7 +79,7 @@ export class BetterSQLite3DBAdapter extends BaseObserver<DBAdapterListener> impl
       if (isCommonJsModule) {
         worker = workerFactory(path.resolve(__dirname, 'DefaultWorker.cjs'), { name: workerName });
       } else {
-        worker = workerFactory(new URL('./DefaultWorker.js', import.meta.url), { name: workerName});
+        worker = workerFactory(new URL('./DefaultWorker.js', import.meta.url), { name: workerName });
       }
 
       const listeners = new WeakMap<EventListenerOrEventListenerObject, (e: any) => void>();

packages/node/src/db/SqliteWorker.ts

@@ -138,7 +138,7 @@ export function startPowerSyncWorker(options?: Partial<PowerSyncWorkerOptions>)
 
       return resolved;
     },
-    ...options,
+    ...options
   };
 
   Comlink.expose(new BetterSqliteWorker(resolvedOptions), parentPort! as Comlink.Endpoint);

packages/node/tests/PowerSyncDatabase.test.ts

@@ -1,8 +1,9 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
 import { Worker } from 'node:worker_threads';
-import fs from 'node:fs/promises';
 
-import { vi, expect, test, onTestFinished } from 'vitest';
-import { AppSchema, createTempDir, databaseTest } from './utils';
+import { vi, expect, test } from 'vitest';
+import { AppSchema, databaseTest, tempDirectoryTest } from './utils';
 import { PowerSyncDatabase } from '../lib';
 import { WorkerOpener } from '../lib/db/options';
 
@@ -12,15 +13,14 @@ test('validates options', async () => {
       schema: AppSchema,
       database: {
         dbFilename: '/dev/null',
-        readWorkerCount: 0,
+        readWorkerCount: 0
       }
     });
     await database.init();
   }).rejects.toThrowError('Needs at least one worker for reads');
 });
 
-test('can customize loading workers', async () => {
-  const directory = await createTempDir();
+tempDirectoryTest('can customize loading workers', async ({ tmpdir }) => {
   const defaultWorker: WorkerOpener = (...args) => new Worker(...args);
 
   const openFunction = vi.fn(defaultWorker); // Wrap in vi.fn to count invocations
@@ -29,7 +29,7 @@ test('can customize loading workers', async () => {
     schema: AppSchema,
     database: {
       dbFilename: 'test.db',
-      dbLocation: directory,
+      dbLocation: tmpdir,
       openWorker: openFunction,
       readWorkerCount: 2
     }
@@ -38,8 +38,6 @@ test('can customize loading workers', async () => {
   await database.get('SELECT 1;'); // Make sure the database is ready and works
   expect(openFunction).toHaveBeenCalledTimes(3); // One writer, two readers
   await database.close();
-
-  onTestFinished(async () => fs.rm(directory, { recursive: true }));
 });
 
 databaseTest('links powersync', async ({ database }) => {
@@ -95,6 +93,22 @@ databaseTest('can watch tables', async ({ database }) => {
   await expect.poll(() => fn).toHaveBeenCalledTimes(2);
 });
 
+tempDirectoryTest('throws error if target directory does not exist', async ({ tmpdir }) => {
+  const directory = path.join(tmpdir, 'some', 'nested', 'location', 'that', 'does', 'not', 'exist');
+
+  expect(async () => {
+    const database = new PowerSyncDatabase({
+      schema: AppSchema,
+      database: {
+        dbFilename: 'test.db',
+        dbLocation: directory,
+        readWorkerCount: 2
+      }
+    });
+    await database.waitForReady();
+  }).rejects.toThrowError(/The dbLocation directory at ".+" does not exist/);
+});
+
 databaseTest.skip('can watch queries', async ({ database }) => {
   const query = await database.watch('SELECT * FROM todos;', [])[Symbol.asyncIterator]();
   expect((await query.next()).value.rows).toHaveLength(0);

packages/node/tests/utils.ts

@@ -23,17 +23,23 @@ export const AppSchema = new Schema({
 
 export type Database = (typeof AppSchema)['types'];
 
-export const databaseTest = test.extend<{ database: PowerSyncDatabase }>({
-  database: async ({}, use) => {
+export const tempDirectoryTest = test.extend<{ tmpdir: string }>({
+  tmpdir: async ({}, use) => {
     const directory = await createTempDir();
+    await use(directory);
+    await fs.rm(directory, { recursive: true });
+  }
+});
+
+export const databaseTest = tempDirectoryTest.extend<{ database: PowerSyncDatabase }>({
+  database: async ({ tmpdir }, use) => {
     const database = new PowerSyncDatabase({
       schema: AppSchema,
       database: {
         dbFilename: 'test.db',
-        dbLocation: directory
+        dbLocation: tmpdir
       }
     });
     await use(database);
-    await fs.rm(directory, { recursive: true });
   }
 });