instance cache in api

Author: jraymakers

api/pkgs/@duckdb/node-api/README.md

@@ -45,6 +45,17 @@ console.log(duckdb.version());
 console.log(duckdb.configurationOptionDescriptions());
 ```
 
+### Connect
+
+```ts
+import { DuckDBConnection } from '@duckdb/node-api';
+
+const connection = await DuckDBConnection.create();
+```
+
+This uses the default instance.
+For advanced usage, you can create instances explicitly.
+
 ### Create Instance
 
 ```ts
@@ -66,14 +77,33 @@ Read from and write to a database file, which is created if needed:
 const instance = await DuckDBInstance.create('my_duckdb.db');
 ```
 
-Set configuration options:
+Set [configuration options](https://duckdb.org/docs/stable/configuration/overview.html#configuration-reference):
 ```ts
 const instance = await DuckDBInstance.create('my_duckdb.db', {
   threads: '4'
 });
 ```
 
-### Connect
+### Instance Cache
+
+Multiple instances in the same process should not
+attach the same database.
+
+To prevent this, an instance cache can be used:
+```ts
+const instance = await DuckDBInstance.fromCache('my_duckdb.db');
+```
+
+This uses the default instance cache. For advanced usage, you can create
+instance caches explicitly:
+```ts
+import { DuckDBInstanceCache } from '@duckdb/node-api';
+
+const cache = new DuckDBInstanceCache();
+const instance = await cache.getOrCreateInstance('my_duckdb.db');
+```
+
+### Connect to Instance
 
 ```ts
 const connection = await instance.connect();

api/src/DuckDBConnection.ts

@@ -16,9 +16,12 @@ export class DuckDBConnection {
     this.connection = connection;
   }
   public static async create(
-    instance: DuckDBInstance
+    instance?: DuckDBInstance
   ): Promise<DuckDBConnection> {
-    return instance.connect();
+    if (instance) {
+      return instance.connect();
+    }
+    return (await DuckDBInstance.fromCache()).connect();
   }
   /** Same as disconnect. */
   public close() {

api/src/DuckDBInstance.ts

@@ -1,26 +1,30 @@
 import duckdb from '@duckdb/node-bindings';
+import { createConfig } from './createConfig';
 import { DuckDBConnection } from './DuckDBConnection';
+import { DuckDBInstanceCache } from './DuckDBInstanceCache';
 
 export class DuckDBInstance {
   private readonly db: duckdb.Database;
+
   constructor(db: duckdb.Database) {
     this.db = db;
   }
+
   public static async create(
     path?: string,
     options?: Record<string, string>
   ): Promise<DuckDBInstance> {
-    const config = duckdb.create_config();
-    // Set the default duckdb_api value for the api. Can be overridden.
-    duckdb.set_config(config, 'duckdb_api', 'node-neo-api');
-    if (options) {
-      for (const optionName in options) {
-        const optionValue = String(options[optionName]);
-        duckdb.set_config(config, optionName, optionValue);
-      }
-    }
+    const config = createConfig(options);
     return new DuckDBInstance(await duckdb.open(path, config));
   }
+
+  public static async fromCache(
+    path?: string,
+    options?: Record<string, string>
+  ): Promise<DuckDBInstance> {
+    return DuckDBInstanceCache.singleton.getOrCreateInstance(path, options);
+  }
+
   public async connect(): Promise<DuckDBConnection> {
     return new DuckDBConnection(await duckdb.connect(this.db));
   }

api/src/DuckDBInstanceCache.ts

@@ -0,0 +1,29 @@
+import duckdb from '@duckdb/node-bindings';
+import { DuckDBInstance } from './DuckDBInstance';
+import { createConfig } from './createConfig';
+
+export class DuckDBInstanceCache {
+  private readonly cache: duckdb.InstanceCache;
+
+  constructor() {
+    this.cache = duckdb.create_instance_cache();
+  }
+
+  public async getOrCreateInstance(
+    path?: string,
+    options?: Record<string, string>
+  ): Promise<DuckDBInstance> {
+    const config = createConfig(options);
+    const db = await duckdb.get_or_create_from_cache(this.cache, path, config);
+    return new DuckDBInstance(db);
+  }
+
+  private static singletonInstance: DuckDBInstanceCache;
+
+  public static get singleton(): DuckDBInstanceCache {
+    if (!DuckDBInstanceCache.singletonInstance) {
+      DuckDBInstanceCache.singletonInstance = new DuckDBInstanceCache();
+    }
+    return DuckDBInstanceCache.singletonInstance;
+  }
+}

api/src/createConfig.ts

@@ -0,0 +1,14 @@
+import duckdb from '@duckdb/node-bindings';
+
+export function createConfig(options?: Record<string, string>): duckdb.Config {
+  const config = duckdb.create_config();
+  // Set the default duckdb_api value for the api. Can be overridden.
+  duckdb.set_config(config, 'duckdb_api', 'node-neo-api');
+  if (options) {
+    for (const optionName in options) {
+      const optionValue = String(options[optionName]);
+      duckdb.set_config(config, optionName, optionValue);
+    }
+  }
+  return config;
+}

api/test/api.test.ts

@@ -1,3 +1,4 @@
+import fs from 'fs';
 import { assert, beforeAll, describe, test } from 'vitest';
 import {
   ANY,
@@ -111,6 +112,7 @@ import {
   uuidValue,
   version,
 } from '../src';
+import { DuckDBInstanceCache } from '../src/DuckDBInstanceCache';
 import { replaceSqlNullWithInteger } from './util/replaceSqlNullWithInteger';
 import {
   ColumnNameAndType,
@@ -1333,6 +1335,69 @@ describe('api', () => {
       ]);
     }
   });
+  test('instance cache - same instance', async () => {
+    const cache = new DuckDBInstanceCache();
+    const instance1 = await cache.getOrCreateInstance();
+    const connection1 = await instance1.connect();
+    await connection1.run(`attach ':memory:' as mem1`);
+
+    const instance2 = await cache.getOrCreateInstance();
+    const connection2 = await instance2.connect();
+    await connection2.run(`create table mem1.main.t1 as select 1`);
+  });
+  test('instance cache - different instances', async () => {
+    try {
+      const cache = new DuckDBInstanceCache();
+      const instance1 = await cache.getOrCreateInstance(
+        'instance_cache_test_a.db'
+      );
+      const connection1 = await instance1.connect();
+      await connection1.run(`attach ':memory:' as mem1`);
+
+      const instance2 = await cache.getOrCreateInstance(
+        'instance_cache_test_b.db'
+      );
+      const connection2 = await instance2.connect();
+      try {
+        await connection2.run(`create table mem1.main.t1 as select 1`);
+        assert.fail('should throw');
+      } catch (err) {
+        assert.deepEqual(
+          err,
+          new Error(`Catalog Error: Catalog with name mem1 does not exist!`)
+        );
+      }
+    } finally {
+      fs.rmSync('instance_cache_test_a.db');
+      fs.rmSync('instance_cache_test_b.db');
+    }
+  });
+  test('instance cache - different config', async () => {
+    const cache = new DuckDBInstanceCache();
+    const instance1 = await cache.getOrCreateInstance();
+    const connection1 = await instance1.connect();
+    await connection1.run(`attach ':memory:' as mem1`);
+    try {
+      await cache.getOrCreateInstance(undefined, { accces_mode: 'READ_ONLY' });
+      assert.fail('should throw');
+    } catch (err) {
+      assert.deepEqual(
+        err,
+        new Error(
+          `Connection Error: Can't open a connection to same database file with a different configuration than existing connections`
+        )
+      );
+    }
+  });
+  test('instance cache - singleton', async () => {
+    const instance = await DuckDBInstance.fromCache();
+    const connection = await instance.connect();
+    await connection.run('select 1');
+  });
+  test('create connection using instance cache', async () => {
+    const connection = await DuckDBConnection.create();
+    await connection.run('select 1');
+  });
   test('write integer vector', () => {
     const chunk = DuckDBDataChunk.create([INTEGER], 3);
     const vector = chunk.getColumnVector(0) as DuckDBIntegerVector;