fix: respect access mode and file open flags

packages/duckdb-wasm/.gitignore

@@ -6,4 +6,5 @@
 /duckdb_webapi.*
 /dist
 /docs
+/test_temp
 *.d.ts.map

packages/duckdb-wasm/src/bindings/bindings_base.ts

@@ -1,5 +1,5 @@
 import { DuckDBModule, PThread } from './duckdb_module';
-import { DuckDBConfig } from './config';
+import { DuckDBAccessMode, DuckDBConfig } from './config';
 import { Logger } from '../log';
 import { InstantiationProgress } from './progress';
 import { DuckDBBindings } from './bindings_interface';
@@ -508,9 +508,9 @@ export abstract class DuckDBBindingsBase implements DuckDBBindings {
         }
         dropResponseBuffers(this.mod);
     }
-    public async prepareFileHandle(fileName: string, protocol: DuckDBDataProtocol): Promise<void> {
+    public async prepareFileHandle(fileName: string, protocol: DuckDBDataProtocol, accessMode?: DuckDBAccessMode): Promise<void> {
         if (protocol === DuckDBDataProtocol.BROWSER_FSACCESS && this._runtime.prepareFileHandles) {
-            const list = await this._runtime.prepareFileHandles([fileName], DuckDBDataProtocol.BROWSER_FSACCESS);
+            const list = await this._runtime.prepareFileHandles([fileName], DuckDBDataProtocol.BROWSER_FSACCESS, accessMode);
             for (const item of list) {
                 const { handle, path: filePath, fromCached } = item;
                 if (!fromCached && handle.getSize()) {
@@ -522,9 +522,9 @@ export abstract class DuckDBBindingsBase implements DuckDBBindings {
         throw new Error(`prepareFileHandle: unsupported protocol ${protocol}`);
     }
     /** Prepare a file handle that could only be acquired aschronously */
-    public async prepareDBFileHandle(path: string, protocol: DuckDBDataProtocol): Promise<void> {
+    public async prepareDBFileHandle(path: string, protocol: DuckDBDataProtocol, accessMode?: DuckDBAccessMode): Promise<void> {
         if (protocol === DuckDBDataProtocol.BROWSER_FSACCESS && this._runtime.prepareDBFileHandle) {
-            const list = await this._runtime.prepareDBFileHandle(path, DuckDBDataProtocol.BROWSER_FSACCESS);
+            const list = await this._runtime.prepareDBFileHandle(path, DuckDBDataProtocol.BROWSER_FSACCESS, accessMode);
             for (const item of list) {
                 const { handle, path: filePath, fromCached } = item;
                 if (!fromCached && handle.getSize()) {

packages/duckdb-wasm/src/bindings/bindings_interface.ts

@@ -1,4 +1,4 @@
-import { DuckDBConfig, DuckDBConnection, DuckDBDataProtocol, FileStatistics, InstantiationProgress } from '.';
+import { DuckDBAccessMode, DuckDBConfig, DuckDBConnection, DuckDBDataProtocol, FileStatistics, InstantiationProgress } from '.';
 import { CSVInsertOptions, JSONInsertOptions, ArrowInsertOptions } from './insert_options';
 import { ScriptTokens } from './tokens';
 import { WebFile } from './web_file';
@@ -54,8 +54,8 @@ export interface DuckDBBindings {
         protocol: DuckDBDataProtocol,
         directIO: boolean,
     ): Promise<HandleType>;
-    prepareFileHandle(path: string, protocol: DuckDBDataProtocol): Promise<void>;
-    prepareDBFileHandle(path: string, protocol: DuckDBDataProtocol): Promise<void>;
+    prepareFileHandle(path: string, protocol: DuckDBDataProtocol, accessMode?: DuckDBAccessMode): Promise<void>;
+    prepareDBFileHandle(path: string, protocol: DuckDBDataProtocol, accessMode?: DuckDBAccessMode): Promise<void>;
     globFiles(path: string): WebFile[];
     dropFile(name: string): void;
     dropFiles(): void;

packages/duckdb-wasm/src/bindings/runtime.ts

@@ -1,3 +1,4 @@
+import { DuckDBAccessMode } from './config';
 import { DuckDBModule } from './duckdb_module';
 import { UDFFunction } from './udf_function';
 import * as udf_rt from './udf_runtime';
@@ -58,6 +59,16 @@ export enum FileFlags {
     FILE_FLAGS_FILE_CREATE_NEW = 1 << 4,
     //! Open file in append mode
     FILE_FLAGS_APPEND = 1 << 5,
+    //! Open file with restrictive permissions (600 on linux/mac) can only be used when creating, throws if file exists
+    FILE_FLAGS_PRIVATE = 1 << 6,
+    //! Return NULL if the file does not exist instead of throwing an error
+    FILE_FLAGS_NULL_IF_NOT_EXISTS = 1 << 7,
+    //! Multiple threads may perform reads and writes in parallel
+    FILE_FLAGS_PARALLEL_ACCESS = 1 << 8,
+    //! Ensure that this call creates the file, throw is file exists
+    FILE_FLAGS_EXCLUSIVE_CREATE = 1 << 9,
+    //!  Return NULL if the file exist instead of throwing an error
+    FILE_FLAGS_NULL_IF_EXISTS = 1 << 10,
 }
 
 /** Configuration for the AWS S3 Filesystem */
@@ -158,8 +169,8 @@ export interface DuckDBRuntime {
 
     // Prepare a file handle that could only be acquired aschronously
     prepareFileHandle?: (path: string, protocol: DuckDBDataProtocol) => Promise<PreparedDBFileHandle[]>;
-    prepareFileHandles?: (path: string[], protocol: DuckDBDataProtocol) => Promise<PreparedDBFileHandle[]>;
-    prepareDBFileHandle?: (path: string, protocol: DuckDBDataProtocol) => Promise<PreparedDBFileHandle[]>;
+    prepareFileHandles?: (path: string[], protocol: DuckDBDataProtocol, accessMode?: DuckDBAccessMode) => Promise<PreparedDBFileHandle[]>;
+    prepareDBFileHandle?: (path: string, protocol: DuckDBDataProtocol, accessMode?: DuckDBAccessMode) => Promise<PreparedDBFileHandle[]>;
 
     // Internal API - experimental
     progressUpdate(final: number, percentage: number, iteration: number): void;

packages/duckdb-wasm/src/bindings/runtime_browser.ts

@@ -16,6 +16,7 @@ import {
 } from './runtime';
 import { DuckDBModule } from './duckdb_module';
 import * as udf from './udf_runtime';
+import { DuckDBAccessMode } from './config';
 
 const OPFS_PREFIX_LEN = 'opfs://'.length;
 const PATH_SEP_REGEX = /\/|\\/;
@@ -110,8 +111,11 @@ export const BROWSER_RUNTIME: DuckDBRuntime & {
             BROWSER_RUNTIME._opfsRoot = await navigator.storage.getDirectory();
         }
     },
-    /** Prepare a file handle that could only be acquired aschronously */
-    async prepareFileHandles(filePaths: string[], protocol: DuckDBDataProtocol): Promise<PreparedDBFileHandle[]> {
+    /** Prepare a file handle that could only be acquired asynchronously */
+    async prepareFileHandles(filePaths: string[], protocol: DuckDBDataProtocol, accessMode?: DuckDBAccessMode): Promise<PreparedDBFileHandle[]> {
+        // DuckDBAccessMode.UNDEFINED will be treated as READ_WRITE
+        // See: https://github.com/duckdb/duckdb/blob/5f5512b827df6397afd31daedb4bbdee76520019/src/main/database.cpp#L442-L444
+        const isReadWrite = !accessMode || accessMode === DuckDBAccessMode.READ_WRITE;
         if (protocol === DuckDBDataProtocol.BROWSER_FSACCESS) {
             await BROWSER_RUNTIME.assignOPFSRoot();
             const prepare = async (path: string): Promise<PreparedDBFileHandle> => {
@@ -135,13 +139,16 @@ export const BROWSER_RUNTIME: DuckDBRuntime & {
                     }
                     // mkdir -p
                     for (const folder of folders) {
-                        dirHandle = await dirHandle.getDirectoryHandle(folder, { create: true });
+                        dirHandle = await dirHandle.getDirectoryHandle(folder, { create: isReadWrite });
                     }
                 }
                 const fileHandle = await dirHandle.getFileHandle(fileName, { create: false }).catch(e => {
                     if (e?.name === 'NotFoundError') {
-                        console.debug(`File ${path} does not exists yet, creating...`);
-                        return dirHandle.getFileHandle(fileName, { create: true });
+                        if (isReadWrite) {
+                            console.debug(`File ${path} does not exists yet, creating...`);
+                            return dirHandle.getFileHandle(fileName, { create: true });
+                        }
+                        console.debug(`File ${path} does not exists, aborting as we are in read-only mode`);
                     }
                     throw e;
                 });
@@ -166,11 +173,11 @@ export const BROWSER_RUNTIME: DuckDBRuntime & {
         }
         throw new Error(`Unsupported protocol ${protocol} for paths ${filePaths} with protocol ${protocol}`);
     },
-    /** Prepare a file handle that could only be acquired aschronously */
-    async prepareDBFileHandle(dbPath: string, protocol: DuckDBDataProtocol): Promise<PreparedDBFileHandle[]> {
+    /** Prepare a file handle that could only be acquired asynchronously */
+    async prepareDBFileHandle(dbPath: string, protocol: DuckDBDataProtocol, accessMode?: DuckDBAccessMode): Promise<PreparedDBFileHandle[]> {
         if (protocol === DuckDBDataProtocol.BROWSER_FSACCESS && this.prepareFileHandles) {
             const filePaths = [dbPath, `${dbPath}.wal`];
-            return this.prepareFileHandles(filePaths, protocol);
+            return this.prepareFileHandles(filePaths, protocol, accessMode);
         }
         throw new Error(`Unsupported protocol ${protocol} for path ${dbPath} with protocol ${protocol}`);
     },

packages/duckdb-wasm/src/bindings/runtime_node.ts

@@ -74,16 +74,32 @@ export const NODE_RUNTIME: DuckDBRuntime & {
             switch (file?.dataProtocol) {
                 // Native file
                 case DuckDBDataProtocol.NODE_FS: {
+                    let openFlags = fs.constants.O_RDONLY;
+                    if (flags & FileFlags.FILE_FLAGS_WRITE) {
+                        openFlags = fs.constants.O_RDWR;
+                    }
+                    if (flags & FileFlags.FILE_FLAGS_FILE_CREATE) {
+                        openFlags |= fs.constants.O_CREAT;
+                    } else if (flags & FileFlags.FILE_FLAGS_FILE_CREATE_NEW) {
+                        openFlags |= fs.constants.O_TRUNC;
+                    }
                     let fd = NODE_RUNTIME._files?.get(file.dataUrl!);
-                    if (fd === null || fd === undefined) {
-                        fd = fs.openSync(
-                            file.dataUrl!,
-                            fs.constants.O_CREAT | fs.constants.O_RDWR,
-                            fs.constants.S_IRUSR | fs.constants.S_IWUSR,
-                        );
-                        NODE_RUNTIME._filesById?.set(file.fileId!, fd);
+                    let fileSize = 0;
+                    try {
+                        if (fd === null || fd === undefined) {
+                            fd = fs.openSync(file.dataUrl!, openFlags, fs.constants.S_IRUSR | fs.constants.S_IWUSR);
+                            NODE_RUNTIME._filesById?.set(file.fileId!, fd);
+                        }
+                        fileSize = fs.fstatSync(fd).size;
+                    }
+                    catch (e: any) {
+                        if (e.code === 'ENOENT' && (flags & FileFlags.FILE_FLAGS_NULL_IF_NOT_EXISTS)) {
+                            // No-op because we intend to ignore ENOENT while the file does not exist
+                            return 0; // nullptr
+                        } else {
+                            throw e;
+                        }
                     }
-                    const fileSize = fs.fstatSync(fd).size;
                     const result = mod._malloc(2 * 8);
                     mod.HEAPF64[(result >> 3) + 0] = +fileSize;
                     mod.HEAPF64[(result >> 3) + 1] = 0;

packages/duckdb-wasm/src/parallel/worker_dispatcher.ts

@@ -136,8 +136,9 @@ export abstract class AsyncDuckDBDispatcher implements Logger {
 
                 case WorkerRequestType.OPEN: {
                     const path = request.data.path;
+                    const accessMode = request.data.accessMode;
                     if (path?.startsWith('opfs://')) {
-                        await this._bindings.prepareDBFileHandle(path, DuckDBDataProtocol.BROWSER_FSACCESS);
+                        await this._bindings.prepareDBFileHandle(path, DuckDBDataProtocol.BROWSER_FSACCESS, accessMode);
                         request.data.useDirectIO = true;
                     }
                     this._bindings.open(request.data);

packages/duckdb-wasm/test/index_node.ts

@@ -69,6 +69,7 @@ import { testAllTypes, testAllTypesAsync } from './all_types.test';
 import { testBindings, testAsyncBindings } from './bindings.test';
 import { testBatchStream } from './batch_stream.test';
 import { testFilesystem } from './filesystem.test';
+import { testNodeFS } from './nodefs.test';
 import { testAsyncBatchStream } from './batch_stream_async.test';
 import { testArrowInsert, testArrowInsertAsync } from './insert_arrow.test';
 import { testJSONInsert, testJSONInsertAsync } from './insert_json.test';
@@ -92,6 +93,7 @@ testAsyncBindings(() => adb!, dataDir, duckdb.DuckDBDataProtocol.NODE_FS);
 testBatchStream(() => db!);
 testAsyncBatchStream(() => adb!);
 testFilesystem(() => adb!, resolveData, dataDir, duckdb.DuckDBDataProtocol.NODE_FS);
+testNodeFS(() => adb!);
 testArrowInsert(() => db!);
 testArrowInsertAsync(() => adb!);
 testJSONInsert(() => db!);

packages/duckdb-wasm/test/nodefs.test.ts

@@ -0,0 +1,77 @@
+import * as duckdb from '../src/';
+import { randomUUID } from 'crypto';
+import { unlink } from 'fs/promises';
+import { mkdirSync } from 'fs';
+import path from 'path';
+
+const tmpdir = () => {
+    const tmp = path.resolve(__dirname, '../test_temp');
+    mkdirSync(tmp, { recursive: true });
+    return tmp;
+}
+
+export function testNodeFS(db: () => duckdb.AsyncDuckDB): void {
+    const files: string[] = [];
+
+    afterAll(async () => {
+        await Promise.all(files.map(file => unlink(file).catch(() => {})));
+        await db().flushFiles();
+        await db().dropFiles();
+    });
+
+    describe('Node FS', () => {
+        it('Should not create an empty DB file in read-only mode for non-existent path', async () => {
+            const tmp = tmpdir();
+            const filename = `duckdb_test_${randomUUID().replace(/-/g, '')}`;
+            files.push(path.join(tmp, filename));
+
+            await expectAsync(
+                db().open({
+                    path: path.join(tmp, filename),
+                    accessMode: duckdb.DuckDBAccessMode.READ_ONLY,
+                }),
+            ).toBeRejectedWithError(/database does not exist/);
+        });
+
+        it('Should create DB file in read-write mode for non-existent path', async () => {
+            const tmp = tmpdir();
+            const filename = `duckdb_test_${randomUUID().replace(/-/g, '')}`;
+            files.push(path.join(tmp, filename));
+
+            await expectAsync(
+                db().open({
+                    path: path.join(tmp, filename),
+                    accessMode: duckdb.DuckDBAccessMode.READ_WRITE,
+                }),
+            ).toBeResolved();
+        });
+
+        it('Should create an empty DB file in read-only mode for non-existent path with direct I/O', async () => {
+            const tmp = tmpdir();
+            const filename = `duckdb_test_${randomUUID().replace(/-/g, '')}`;
+            files.push(path.join(tmp, filename));
+
+            await expectAsync(
+                db().open({
+                    path: path.join(tmp, filename),
+                    accessMode: duckdb.DuckDBAccessMode.READ_ONLY,
+                    useDirectIO: true,
+                }),
+            ).toBeRejectedWithError(/database does not exist/);
+        });
+
+        it('Should create DB file in read-write mode for non-existent path with direct I/O', async () => {
+            const tmp = tmpdir();
+            const filename = `duckdb_test_${randomUUID().replace(/-/g, '')}`;
+            files.push(path.join(tmp, filename));
+
+            await expectAsync(
+                db().open({
+                    path: path.join(tmp, filename),
+                    accessMode: duckdb.DuckDBAccessMode.READ_WRITE,
+                    useDirectIO: true,
+                }),
+            ).toBeResolved();
+        });
+    });
+}

packages/duckdb-wasm/test/opfs.test.ts

@@ -276,6 +276,85 @@ export function testOPFS(baseDir: string, bundle: () => duckdb.DuckDBBundle): vo
         });
     });
 
+    describe('Open database in OPFS', () => {
+        it('should not open a non-existent DB file in read-only', async () => {
+            const logger = new duckdb.ConsoleLogger(LogLevel.ERROR);
+            const worker = new Worker(bundle().mainWorker!);
+            const db_ = new duckdb.AsyncDuckDB(logger, worker);
+            await db_.instantiate(bundle().mainModule, bundle().pthreadWorker);
+
+            await expectAsync(db_.open({
+                path: 'opfs://non_existent.db',
+                accessMode: duckdb.DuckDBAccessMode.READ_ONLY,
+            })).toBeRejectedWithError(Error, /file or directory could not be found/);
+
+            await db_.terminate();
+            await worker.terminate();
+
+            // Files should not be found with DuckDBAccessMode.READ_ONLY
+            const opfsRoot = await navigator.storage.getDirectory();
+            await expectAsync(opfsRoot.getFileHandle('non_existent.db', { create: false }))
+                .toBeRejectedWithError(Error, /file or directory could not be found/);
+        });
+
+        it('should not open a non-existent DB file and mkdir in read-only', async () => {
+            const logger = new duckdb.ConsoleLogger(LogLevel.ERROR);
+            const worker = new Worker(bundle().mainWorker!);
+            const db_ = new duckdb.AsyncDuckDB(logger, worker);
+            await db_.instantiate(bundle().mainModule, bundle().pthreadWorker);
+
+            await expectAsync(db_.open({
+                path: 'opfs://duckdb_test/path/to/non_existent.db',
+                accessMode: duckdb.DuckDBAccessMode.READ_ONLY,
+            })).toBeRejectedWithError(Error, /file or directory could not be found/);
+
+            await db_.terminate();
+            await worker.terminate();
+        });
+
+        it('should open a non-existent DB file and mkdir in read-write', async () => {
+            const logger = new duckdb.ConsoleLogger(LogLevel.ERROR);
+            const worker = new Worker(bundle().mainWorker!);
+            const db_ = new duckdb.AsyncDuckDB(logger, worker);
+            await db_.instantiate(bundle().mainModule, bundle().pthreadWorker);
+
+            await expectAsync(db_.open({
+                path: 'opfs://duckdb_test/path/to/duck.db',
+                accessMode: duckdb.DuckDBAccessMode.READ_WRITE,
+            })).toBeResolved();
+
+            await db_.terminate();
+            await worker.terminate();
+        });
+
+        it('should open a non-existent DB file in read-write and create files', async () => {
+            const logger = new duckdb.ConsoleLogger(LogLevel.ERROR);
+            const worker = new Worker(bundle().mainWorker!);
+            const db_ = new duckdb.AsyncDuckDB(logger, worker);
+            await db_.instantiate(bundle().mainModule, bundle().pthreadWorker);
+
+            const opfsRoot = await navigator.storage.getDirectory();
+
+            // Ensure files do not exist
+            await expectAsync(opfsRoot.getFileHandle('non_existent_2.db', { create: false }))
+                .toBeRejectedWithError(Error, /file or directory could not be found/);
+            await expectAsync(opfsRoot.getFileHandle('non_existent_2.db.wal', { create: false }))
+                .toBeRejectedWithError(Error, /file or directory could not be found/);
+
+            await expectAsync(db_.open({
+                path: 'opfs://non_existent_2.db',
+                accessMode: duckdb.DuckDBAccessMode.READ_WRITE,
+            })).toBeResolved();
+
+            await db_.terminate();
+            await worker.terminate();
+
+            // Files should be found with DuckDBAccessMode.READ_WRITE
+            await expectAsync(opfsRoot.getFileHandle('non_existent_2.db', { create: false })).toBeResolved();
+            await expectAsync(opfsRoot.getFileHandle('non_existent_2.db.wal', { create: false })).toBeResolved();
+        });
+    })
+
     async function removeFiles() {
         const opfsRoot = await navigator.storage.getDirectory();
         await opfsRoot.removeEntry('test.db').catch(() => {});
@@ -292,5 +371,12 @@ export function testOPFS(baseDir: string, bundle: () => duckdb.DuckDBBundle): vo
             //
         }
         await opfsRoot.removeEntry('datadir').catch(() => {});
+
+        // In case of failure caused leftovers
+        await opfsRoot.removeEntry('non_existent.db').catch(() => {});
+        await opfsRoot.removeEntry('non_existent.db.wal').catch(() => {});
+        await opfsRoot.removeEntry('non_existent_2.db').catch(() => {});
+        await opfsRoot.removeEntry('non_existent_2.db.wal').catch(() => {});
+        await opfsRoot.removeEntry('duckdb_test', { recursive: true }).catch(() => {});
     }
 }