feat(duckdb-driver): Add support for local fs duckdb database path (#7799)

* Add support for duckdb database file path

* Parameter must be undefined if no fields.

* Fix linter errors

Author: JichaoS

docs/pages/product/configuration/data-sources/duckdb.mdx

@@ -62,6 +62,7 @@ deployment][ref-demo-deployment] in Cube Cloud.
 | `CUBEJS_DB_DUCKDB_MEMORY_LIMIT`         | The maximum memory limit for DuckDB. Equivalent to `SET memory_limit=<MEMORY_LIMIT>`. Default is 75% of available RAM | A valid memory limit                                          |    ❌    |                                    ✅                                     |
 | `CUBEJS_DB_DUCKDB_SCHEMA`               | The [default search schema][link-duckdb-configuration-ref]                                                            | A valid schema name                                           |    ❌    |                                    ✅                                     |
 | `CUBEJS_DB_DUCKDB_MOTHERDUCK_TOKEN`     | The service token to use for connections to MotherDuck                                                                | A valid [MotherDuck service token][motherduck-docs-svc-token] |    ❌    |                                    ✅                                     |
+| `CUBEJS_DB_DUCKDB_DATABASE_PATH`        | The database filepath to use for connection to a local database.                                                      | A valid duckdb database file path                             |    ❌    |                                    ✅                                     |
 | `CUBEJS_DB_DUCKDB_S3_ACCESS_KEY_ID`     | The Access Key ID to use for database connections                                                                     | A valid Access Key ID                                         |    ❌    |                                    ✅                                     |
 | `CUBEJS_DB_DUCKDB_S3_SECRET_ACCESS_KEY` | The Secret Access Key to use for database connections                                                                 | A valid Secret Access Key                                     |    ❌    |                                    ✅                                     |
 | `CUBEJS_DB_DUCKDB_S3_ENDPOINT`          | The S3 endpoint                                                                                                       | A valid [S3 endpoint][duckdb-docs-s3-import]                  |    ✅    |                                    ✅                                     |

docs/pages/reference/configuration/environment-variables.mdx

@@ -238,6 +238,14 @@ MotherDuck.
 | -------------------------------- | ---------------------- | --------------------- |
 | A valid MotherDuck service token | N/A                    | N/A                   |
 
+## `CUBEJS_DB_DUCKDB_DATABASE_PATH`
+
+The database filepath to use for connection to a local database.
+
+| Possible Values                   | Default in Development | Default in Production |
+| --------------------------------- | ---------------------- | --------------------- |
+| A valid duckdb database file path | N/A                    | N/A                   |
+
 ## `CUBEJS_DB_DUCKDB_S3_ACCESS_KEY_ID`
 
 The AWS Access Key ID to use for S3 connections.

packages/cubejs-backend-shared/src/env.ts

@@ -1408,6 +1408,16 @@ const variables: Record<string, (...args: any) => any> = {
     ]
   ),
 
+  duckdbDatabasePath: ({
+    dataSource
+  }: {
+    dataSource: string,
+  }) => (
+    process.env[
+      keyByDataSource('CUBEJS_DB_DUCKDB_DATABASE_PATH', dataSource)
+    ]
+  ),
+
   duckdbS3Region: ({
     dataSource
   }: {

packages/cubejs-duckdb-driver/src/DuckDBDriver.ts

@@ -57,13 +57,26 @@ export class DuckDBDriver extends BaseDriver implements DriverInterface {
 
   protected async init(): Promise<InitPromise> {
     const token = getEnv('duckdbMotherDuckToken', this.config);
+    const dbPath = getEnv('duckdbDatabasePath', this.config);
+    
+    // Determine the database URL based on the provided db_path or token
+    let dbUrl: string;
+    if (dbPath) {
+      dbUrl = dbPath;
+    } else if (token) {
+      dbUrl = `md:?motherduck_token=${token}&custom_user_agent=Cube/${version}`;
+    } else {
+      dbUrl = ':memory:';
+    }
+
+    let dbOptions;
+    if (token) {
+      dbOptions = { custom_user_agent: `Cube/${version}` };
+    }
+
+    // Create a new Database instance with the determined URL and custom user agent
+    const db = new Database(dbUrl, dbOptions);
 
-    const db = new Database(
-      token ? `md:?motherduck_token=${token}&custom_user_agent=Cube/${version}` : ':memory:',
-      {
-        custom_user_agent: `Cube/${version}`,
-      }
-    );
     // Under the hood all methods of Database uses internal default connection, but there is no way to expose it
     const defaultConnection = db.connect();
     const execAsync: (sql: string, ...params: any[]) => Promise<void> = promisify(defaultConnection.exec).bind(defaultConnection) as any;