@nshiab/simple-data-analysis-core 1.0.1 → 2.0.0

package/esm/class/SimpleDB.js

@@ -1,21 +1,43 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _SimpleDB_instances, _SimpleDB_closePromise, _SimpleDB_startPromise, _SimpleDB_initialized, _SimpleDB_setup, _SimpleDB_close;
+import quoteIdentifier from "../helpers/quoteIdentifier.js";
 import { DuckDBInstance } from "@duckdb/node-api";
 import runQuery from "../helpers/runQuery.js";
 import SimpleTable from "./SimpleTable.js";
 import cleanCache from "../helpers/cleanCache.js";
-import createDirectory from "../helpers/createDirectory.js";
 import prettyDuration from "../helpers/prettyDuration.js";
 import Simple from "./Simple.js";
 import queryDB from "../helpers/queryDB.js";
 import mergeOptions from "../helpers/mergeOptions.js";
 import getTableNames from "../methods/getTableNames.js";
-import cleanPath from "../helpers/cleanPath.js";
-import getExtension from "../helpers/getExtension.js";
 import { existsSync, rmSync } from "node:fs";
-import checkVssIndexes from "../helpers/checkVssIndexes.js";
+import createDirectory from "../helpers/createDirectory.js";
+import getDbFileType from "../helpers/getDbFileType.js";
+import getCurrentDatabase from "../helpers/getCurrentDatabase.js";
+import getDbIndexes from "../helpers/getDbIndexes.js";
+import readDbMetadata from "../helpers/readDbMetadata.js";
+import writeDbMetadata from "../helpers/writeDbMetadata.js";
+import prepareDbExtensions from "../helpers/prepareDbExtensions.js";
 import setDbProps from "../helpers/setDbProps.js";
-import writeIndexes from "../helpers/writeIndexes.js";
-import getName from "../helpers/getName.js";
-import { renameSync } from "node:fs";
+import queryDbFile from "../helpers/queryDbFile.js";
+import removeTables from "../methods/removeTables.js";
+import selectTables from "../methods/selectTables.js";
+import loadDB from "../methods/loadDB.js";
+import writeDB from "../methods/writeDB.js";
+import flushAllTables, { runExemptFromFlush, } from "../helpers/flushAllTables.js";
+import { discardAllPending } from "../helpers/queueOp.js";
+import { initializeTableRegistry, listRegisteredTables, registerTable, } from "../helpers/tableRegistry.js";
+import formatMissingTables from "../helpers/formatMissingTables.js";
 /**
  * Manages a DuckDB database instance, providing a simplified interface for database operations.
  *
@@ -23,56 +45,104 @@ import { renameSync } from "node:fs";
  * ```ts
  * // Create an in-memory database instance
  * const sdb = new SimpleDB();
- * // Create a new table named "employees"
- * const employees = sdb.newTable("employees");
- * // Load data from a CSV file into the "employees" table
- * await employees.loadData("./employees.csv");
- * // Log the first few rows of the "employees" table to the console
- * await employees.logTable();
+ * // Create a table, load a CSV file, and log its first few rows
+ * const employees = await sdb
+ *   .newTable("employees")
+ *   .loadData("./employees.csv")
+ *   .log();
  * // Close the database connection and clean up resources
- * await sdb.done();
+ * await sdb.close();
  * ```
  *
  * @example
  * ```ts
- * // Create a persistent database instance, saving data to a file
- * // To load an existing database, use the `loadDB` method instead
+ * // Open or create a persistent DuckDB database. Changes persist in this file.
  * const sdb = new SimpleDB({ file: "./my_database.db" });
  * // Perform database operations...
- * // Close the database connection, which saves changes to the specified file
- * await sdb.done();
+ * // Execute pending work, save SDA metadata, and close the database connection
+ * await sdb.close();
  * ```
  *
  * @example
  * ```ts
  * // Create a database instance with custom options
  * const sdb = new SimpleDB({
- *   debug: true, // Enable debugging output
- *   nbRowsToLog: 20 // Set the number of rows to log by default
+ *   logSQL: true, // Log SQL immediately before it runs
+ *   rowsToLog: 20 // Set the number of rows to log by default
  * });
  * ```
  */
-export default class SimpleDB extends Simple {
+class SimpleDB extends Simple {
     /**
      * Creates a new SimpleDB instance.
      *
+     * DuckDB sessions use UTC so temporal parsing, extraction, and returned
+     * `TIMESTAMP WITH TIME ZONE` strings are consistent across environments.
+     *
+     * Existing tables and SDA index metadata are restored on first use. The
+     * `__sda` schema is reserved for versioned SDA metadata. SQLite files can be
+     * imported with `loadDB()` but cannot be used as the persistent database.
+     *
      * @param options - Configuration options for the SimpleDB instance.
-     * @param options.file - The path to the database file. If not provided, an in-memory database is used.
-     * @param options.overwrite - A flag indicating whether to overwrite the database file if it already exists.
+     * @param options.file - A `.db` or `.duckdb` file to open or create. Defaults to an in-memory database.
+     * @param options.overwrite - If true, replaces an existing file on first use. Defaults to false, which opens the existing file.
+     * @param options.readOnly - Opens an existing DuckDB file read-only. Defaults to false. Requires a file and cannot be combined with overwrite.
      * @param options.logDuration - A flag indicating whether to log the total execution duration.
-     * @param options.nbRowsToLog - The number of rows to display when logging a table.
-     * @param options.nbCharactersToLog - The maximum number of characters to display for text-based cells.
-     * @param options.types - A flag indicating whether to include data types when logging a table.
-     * @param options.cacheVerbose - A flag indicating whether to log verbose cache-related messages.
-     * @param options.debug - A flag indicating whether to log debugging information.
+     * @param options.rowsToLog - The number of rows to display when logging a table.
+     * @param options.charsToLog - The maximum number of characters to display for text-based cells.
+     * @param options.typesToLog - A flag indicating whether to include data types when logging a table.
+     * @param options.cacheVerbose - Whether to log cache hits and misses, code and input changes, TTL status, and cache read/write timing.
+     * @param options.logSQL - A flag indicating whether to log SQL immediately before execution.
+     * @param options.explainSQL - A flag indicating whether to log DuckDB query plans for supported statements.
      * @param options.duckDbCache - A flag indicating whether to use DuckDB's external file cache.
      * @param options.progressBar - A flag indicating whether to display a progress bar for long-running operations.
      * @param options.memoryLimit - The maximum amount of memory DuckDB is allowed to use (e.g., `'4GB'`). Defaults to 80% of system RAM.
-     * @param options.tempDirectory - The path to the directory used for temporary files when data exceeds the memory limit (e.g., `'/tmp/duckdb_swap'`). Defaults to `.tmp` for in-memory databases or `<file>.tmp` for file-based databases. Automatically removed when calling `done()`.
+     * @param options.tempDir - The path to the directory used for temporary files when data exceeds the memory limit (e.g., `'/tmp/duckdb_swap'`). Defaults to `.tmp` for in-memory databases or `<file>.tmp` for file-based databases. Automatically removed when calling `close()`.
      * @category Constructor
+     *
+     * @example
+     * ```ts
+     * const sdb = new SimpleDB({
+     *   logSQL: true,
+     *   explainSQL: true,
+     * });
+     * ```
      */
     constructor(options = {}) {
         super(options);
+        _SimpleDB_instances.add(this);
+        /**
+         * Whether to log each SQL statement immediately before execution.
+         *
+         * @defaultValue `false`
+         * @category Properties
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ logSQL: true });
+         * ```
+         */
+        Object.defineProperty(this, "logSQL", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * Whether to log DuckDB query plans before supported statements execute.
+         *
+         * @defaultValue `false`
+         * @category Properties
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ explainSQL: true });
+         * ```
+         */
+        Object.defineProperty(this, "explainSQL", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /**
          * An array of paths to the data sources used in the cache.
          *
@@ -122,19 +192,8 @@ export default class SimpleDB extends Simple {
             value: void 0
         });
         /**
-         * An array of table instances associated with this database.
-         *
-         * @defaultValue `[]`
-         * @category Properties
-         */
-        Object.defineProperty(this, "tables", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        /**
-         * A flag indicating whether to log verbose cache-related messages.
+         * Whether to log cache hits and misses, code and input changes, TTL status,
+         * and cache read/write timing.
          *
          * @defaultValue `false`
          * @category Properties
@@ -181,6 +240,75 @@ export default class SimpleDB extends Simple {
             writable: true,
             value: void 0
         });
+        /**
+         * The in-flight flush of the pending chains, if one is running. Concurrent
+         * observers await it instead of reading mid-flush state. This is for
+         * internal use only.
+         *
+         * @defaultValue `null`
+         * @internal
+         */
+        Object.defineProperty(this, "flushPromise", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        _SimpleDB_closePromise.set(this, null);
+        _SimpleDB_startPromise.set(this, null);
+        _SimpleDB_initialized.set(this, false);
+        /**
+         * The database lifecycle state. This is for internal use only.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "lifecycleState", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * The number of queued operations across all tables, so query execution
+         * points skip the flush entirely when nothing is pending. This is for
+         * internal use only.
+         *
+         * @defaultValue `0`
+         * @internal
+         */
+        Object.defineProperty(this, "pendingCount", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * A counter stamping queued operations with their position in program
+         * order across all tables, so flushes replay them in the order they were
+         * queued. This is for internal use only.
+         *
+         * @defaultValue `0`
+         * @internal
+         */
+        Object.defineProperty(this, "opSequence", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * A flag indicating that the spatial extension has been loaded on this
+         * connection, so it's only loaded once. This is for internal use only.
+         *
+         * @defaultValue `false`
+         * @internal
+         */
+        Object.defineProperty(this, "spatialLoaded", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /**
          * A flag indicating whether to use DuckDB's external file cache.
          *
@@ -206,19 +334,20 @@ export default class SimpleDB extends Simple {
             value: void 0
         });
         /**
-         * The path to the directory used for temporary files when data exceeds the memory limit (e.g., `'/tmp/duckdb_swap'`). Defaults to `.tmp` for in-memory databases or `<file>.tmp` for file-based databases. Temporary directories are automatically removed when calling `done()`.
+         * The path to the directory used for temporary files when data exceeds the memory limit (e.g., `'/tmp/duckdb_swap'`). Defaults to `.tmp` for in-memory databases or `<file>.tmp` for file-based databases. Temporary directories are automatically removed when calling `close()`.
          *
          * @defaultValue `undefined`
          * @category Properties
          */
-        Object.defineProperty(this, "tempDirectory", {
+        Object.defineProperty(this, "tempDir", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
         /**
-         * The path to the database file. If not provided, an in-memory database is used.
+         * The path to the persistent DuckDB database, opened or created on first use.
+         * If not provided, an in-memory database is used. Imports and exports do not change this path.
          *
          * @defaultValue `:memory:`
          * @category Properties
@@ -230,7 +359,7 @@ export default class SimpleDB extends Simple {
             value: void 0
         });
         /**
-         * A flag indicating whether to overwrite the database file if it already exists.
+         * Whether to replace an existing DuckDB file on first use instead of opening it.
          *
          * @defaultValue `false`
          * @category Properties
@@ -241,10 +370,30 @@ export default class SimpleDB extends Simple {
             writable: true,
             value: void 0
         });
+        /**
+         * Whether the persistent DuckDB file is opened read-only. Requires an existing
+         * file and cannot be combined with `overwrite`. DuckDB rejects writes to it.
+         *
+         * @defaultValue `false`
+         * @category Properties
+         * @example
+         * ```ts
+         * const sdb = new SimpleDB({ file: "./archive.duckdb", readOnly: true });
+         * const table = await sdb.getTable("employees");
+         * await table.log();
+         * await sdb.close();
+         * ```
+         */
+        Object.defineProperty(this, "readOnly", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /**
          * The class used to create table instances. Defaults to `SimpleTable`.
          * Override this property when subclassing to ensure all table-creating
-         * methods (e.g., `newTable()`, `cloneTable()`) return instances of your
+         * methods (e.g., `newTable()`, `clone()`) return instances of your
          * custom table class.
          *
          * @defaultValue `SimpleTable`
@@ -275,10 +424,13 @@ export default class SimpleDB extends Simple {
             value: SimpleTable
         });
         this.file = options.file ?? ":memory:";
+        this.logSQL = options.logSQL ?? false;
+        this.explainSQL = options.explainSQL ?? false;
         this.overwrite = options.overwrite ?? false;
+        this.readOnly = options.readOnly ?? false;
         this.logDuration = options.logDuration ?? false;
         this.tableIncrement = 1;
-        this.tables = [];
+        initializeTableRegistry(this);
         this.cacheSourcesUsed = [];
         this.cacheVerbose = options.cacheVerbose ?? false;
         this.cacheTimeSaved = 0;
@@ -288,7 +440,12 @@ export default class SimpleDB extends Simple {
             ? false
             : options.duckDbCache;
         this.memoryLimit = options.memoryLimit;
-        this.tempDirectory = options.tempDirectory;
+        this.tempDir = options.tempDir;
+        this.flushPromise = null;
+        this.lifecycleState = "open";
+        this.pendingCount = 0;
+        this.opSequence = 0;
+        this.spatialLoaded = false;
         this.runQuery = runQuery;
         if (this.cacheVerbose || this.logDuration) {
             this.durationStart = Date.now();
@@ -302,58 +459,19 @@ export default class SimpleDB extends Simple {
      * @category Lifecycle
      */
     async start() {
-        if (this.db === undefined || this.connection === undefined) {
-            if (this.file !== ":memory:") {
-                if (getExtension(this.file) !== "db") {
-                    throw new Error(`The file extension must be .db. The current file is ${this.file}.`);
-                }
-                if (existsSync(this.file) && this.overwrite === false) {
-                    throw new Error(`The file ${this.file} already exists. Set the overwrite option to true to overwrite it. Otherwise, use the loadDB() method to load an existing database with more options.`);
-                }
-                else if (existsSync(this.file) && this.overwrite === true) {
-                    rmSync(this.file);
-                }
-            }
-            this.db = await DuckDBInstance.create(this.file);
-            this.connection = await this.db.connect();
-            // By default, DuckDB does not compress in-memory databases, so we enable it here.
-            if (this.file === ":memory:") {
-                await this.customQuery("ATTACH OR REPLACE ':memory:' AS memory (COMPRESS);");
-            }
-            if (this.duckDbCache === true) {
-                await this.customQuery("SET enable_external_file_cache=true;");
-            }
-            else if (this.duckDbCache === false) {
-                await this.customQuery("SET enable_external_file_cache=false;");
-            }
-            if (this.progressBar) {
-                await this.customQuery(`SET enable_progress_bar = TRUE; SET progress_bar_time = 0;`);
-            }
-            if (this.memoryLimit !== undefined) {
-                await this.customQuery(`SET memory_limit = '${this.memoryLimit}';`);
-            }
-            if (this.tempDirectory !== undefined) {
-                await this.customQuery(`SET temp_directory = '${this.tempDirectory}';`);
-            }
+        if (this.lifecycleState === "closed") {
+            throw new Error(`start() cannot use a SimpleDB that is ${this.lifecycleState}.`);
         }
-        return this;
-    }
-    /**
-     * Adds a SimpleTable instance to the internal list of tables.
-     *
-     * @param table - The SimpleTable instance to add.
-     * @internal
-     * @category Table Management
-     */
-    pushTable(table) {
-        const TableClass = this.tableClass;
-        if (!(table instanceof TableClass)) {
-            throw new Error(`The table must be an instance of ${TableClass.name}.`);
-        }
-        if (this.tables.map((t) => t.name).includes(table.name)) {
-            throw new Error(`Table ${table.name} already exists.`);
+        if (__classPrivateFieldGet(this, _SimpleDB_startPromise, "f") === null) {
+            // The setup queries below must run before any queued operation, so
+            // they must not trigger a flush.
+            __classPrivateFieldSet(this, _SimpleDB_startPromise, runExemptFromFlush(this, async () => {
+                await __classPrivateFieldGet(this, _SimpleDB_instances, "m", _SimpleDB_setup).call(this);
+                __classPrivateFieldSet(this, _SimpleDB_initialized, true, "f");
+                return this;
+            }), "f");
         }
-        this.tables.push(table);
+        return await __classPrivateFieldGet(this, _SimpleDB_startPromise, "f");
     }
     /**
      * Creates a new SimpleTable instance within the database.
@@ -365,39 +483,49 @@ export default class SimpleDB extends Simple {
      * @example
      * ```ts
      * // Create a table with a default name (e.g., "table1", "table2", etc.)
-     * const dataTable = sdb.newTable();
+     * const dataTable = await sdb
+     *   .newTable()
+     *   .loadArray([{ value: 1 }])
+     *   .log();
      * ```
      *
      * @example
      * ```ts
      * // Create a table with a specific name
-     * const employees = sdb.newTable("employees");
+     * const employees = await sdb
+     *   .newTable("employees")
+     *   .loadData("employees.csv")
+     *   .log();
      * ```
      */
     newTable(name) {
+        if (this.lifecycleState !== "open") {
+            throw new Error(`newTable() cannot use a SimpleDB that is ${this.lifecycleState}.`);
+        }
         const TableClass = this.tableClass;
-        // SHOULD MATCH cloneTable
+        // SHOULD MATCH clone
         let table;
         if (typeof name === "string") {
             table = new TableClass(name, this, {
-                debug: this.debug,
-                nbRowsToLog: this.nbRowsToLog,
-                nbCharactersToLog: this.nbCharactersToLog,
-                types: this.types,
+                rowsToLog: this.rowsToLog,
+                charsToLog: this.charsToLog,
+                typesToLog: this.typesToLog,
             });
             table.defaultTableName = false;
         }
         else {
+            while (this.getTables().some((table) => table.name.toLowerCase() === `table${this.tableIncrement}`)) {
+                this.tableIncrement++;
+            }
             table = new TableClass(`table${this.tableIncrement}`, this, {
-                debug: this.debug,
-                nbRowsToLog: this.nbRowsToLog,
-                nbCharactersToLog: this.nbCharactersToLog,
-                types: this.types,
+                rowsToLog: this.rowsToLog,
+                charsToLog: this.charsToLog,
+                typesToLog: this.typesToLog,
             });
             table.defaultTableName = true;
             this.tableIncrement += 1;
         }
-        this.pushTable(table);
+        registerTable(this, table);
         return table;
     }
     /**
@@ -411,22 +539,25 @@ export default class SimpleDB extends Simple {
      * ```ts
      * // Retrieve the "employees" table
      * const employees = await sdb.getTable("employees");
+     * await employees.log();
      * ```
      */
     async getTable(name) {
-        const table = this.tables.find((t) => t.name === name);
+        await this.start();
+        const tables = this.getTables();
+        const table = tables.find((t) => t.name === name);
         if (table) {
             return await table;
         }
         else {
-            throw new Error(`Table ${name} not found.`);
+            throw new Error(formatMissingTables("getTable()", [name], tables.map((availableTable) => availableTable.name)));
         }
     }
     /**
      * Removes one or more tables from the database.
      *
      * @param tables - A single table or an array of tables to remove, specified by name or as SimpleTable instances. Pass `"all"` to remove all tables.
-     * @returns A promise that resolves when the tables have been removed.
+     * @returns A promise that resolves to the database, so methods can be chained.
      * @category Table Management
      *
      * @example
@@ -456,24 +587,14 @@ export default class SimpleDB extends Simple {
      * ```
      */
     async removeTables(tables) {
-        const tablesToBeRemoved = tables === "all"
-            ? [...this.tables]
-            : Array.isArray(tables)
-                ? tables
-                : [tables];
-        await queryDB(this, tablesToBeRemoved.map((d) => `DROP TABLE "${d instanceof SimpleTable ? d.name : d}";`).join("\n"), mergeOptions(this, {
-            table: null,
-            method: "removeTable()",
-            parameters: {},
-        }));
-        const tablesNamesToBeRemoved = tablesToBeRemoved.map((t) => t instanceof SimpleTable ? t.name : t);
-        this.tables = this.tables.filter((t) => !tablesNamesToBeRemoved.includes(t.name));
+        await removeTables(this, tables);
+        return this;
     }
     /**
      * Selects one or more tables to keep in the database, removing all others.
      *
      * @param tables - A single table or an array of tables to select, specified by name or as SimpleTable instances.
-     * @returns A promise that resolves when the tables have been selected.
+     * @returns A promise that resolves to the database, so methods can be chained.
      * @category Table Management
      *
      * @example
@@ -497,20 +618,8 @@ export default class SimpleDB extends Simple {
      * ```
      */
     async selectTables(tables) {
-        const tablesToBeSelected = (Array.isArray(tables) ? tables : [tables]).map((t) => t instanceof SimpleTable ? t.name : t);
-        for (const table of tablesToBeSelected) {
-            if (!(await this.hasTable(table))) {
-                throw new Error(`Table ${table} not found.`);
-            }
-        }
-        const tablesToBeRemoved = this.tables.filter((t) => !tablesToBeSelected.includes(t.name));
-        await queryDB(this, tablesToBeRemoved.map((d) => `DROP TABLE "${d instanceof SimpleTable ? d.name : d}";`).join("\n"), mergeOptions(this, {
-            table: null,
-            method: "removeTable()",
-            parameters: {},
-        }));
-        const tablesNamesToBeRemoved = tablesToBeRemoved.map((t) => t instanceof SimpleTable ? t.name : t);
-        this.tables = this.tables.filter((t) => !tablesNamesToBeRemoved.includes(t.name));
+        await selectTables(this, tables);
+        return this;
     }
     /**
      * Returns an array of all table names in the database, sorted alphabetically.
@@ -531,7 +640,7 @@ export default class SimpleDB extends Simple {
     /**
      * Logs the names of all tables in the database to the console, sorted alphabetically.
      *
-     * @returns A promise that resolves when the table names have been logged.
+     * @returns A promise that resolves to the database, so methods can be chained.
      * @category Table Management
      *
      * @example
@@ -549,21 +658,25 @@ export default class SimpleDB extends Simple {
         else {
             console.log(`\nSimpleDB - No tables found.`);
         }
+        return this;
     }
     /**
      * Returns an array of all SimpleTable instances in the database.
      *
-     * @returns A promise that resolves to an array of SimpleTable instances.
+     * The returned array is a snapshot and cannot mutate the database's internal
+     * table registry.
+     *
+     * @returns A read-only array of SimpleTable instances.
      * @category Table Management
      *
      * @example
      * ```ts
      * // Get all SimpleTable instances
-     * const tables = await sdb.getTables();
+     * const tables = sdb.getTables();
      * ```
      */
-    async getTables() {
-        return await this.tables;
+    getTables() {
+        return listRegisteredTables(this);
     }
     /**
      * Checks if a table exists in the database.
@@ -607,7 +720,7 @@ export default class SimpleDB extends Simple {
      */
     async getExtensions() {
         return (await queryDB(this, `FROM duckdb_extensions();`, mergeOptions(this, {
-            returnDataFrom: "query",
+            returnData: true,
             table: null,
             method: "getExtensions()",
             parameters: {},
@@ -615,15 +728,20 @@ export default class SimpleDB extends Simple {
     }
     /**
      * Executes a custom SQL query directly against the DuckDB instance.
+     * Queries run in UTC. When data is returned, temporal values use the same
+     * JavaScript representations as `SimpleTable.getData()`.
      *
-     * If you want to force the returned data to match the types of the columns, you can use the `types` option.
+     * `customQuery()` bypasses the dependency and table-generation tracking used
+     * by `SimpleTable.cache()`. Reading or changing a table with `customQuery()`
+     * can therefore cause `cache()` to return stale data. Include a value that
+     * identifies the custom query's dependencies in the cache's `options.inputs`
+     * (such as a table content hash), or use tracked `SimpleTable` methods.
      *
      * @param query - The SQL query string to execute.
      * @param options - Configuration options for the query.
-     * @param options.returnDataFrom - Specifies whether to return data from the query. Can be `"query"` to return data or `"none"` (default) to not return data.
+     * @param options.returnData - If `true`, the query result is returned. Defaults to `false`.
      * @param options.table - The name of the table associated with the query, primarily used for debugging and logging.
-     * @param options.types - An optional object specifying data types for the query parameters.
-     * @returns A promise that resolves to the query result as an array of objects if `returnDataFrom` is `"query"`, otherwise `null`.
+     * @returns A promise that resolves to the query result as an array of objects if `returnData` is `true`, otherwise `null`.
      * @category DuckDB
      *
      * @example
@@ -637,29 +755,33 @@ export default class SimpleDB extends Simple {
      * // Execute a query and return the results
      * const youngEmployees = await sdb.customQuery(
      *   "SELECT * FROM employees WHERE age < 30",
-     *   { returnDataFrom: "query" }
+     *   { returnData: true }
      * );
      * console.log(youngEmployees);
      * ```
      */
     async customQuery(query, options = {}) {
         return await queryDB(this, query, mergeOptions(this, {
-            returnDataFrom: options.returnDataFrom,
+            returnData: options.returnData ?? false,
             table: options.table ?? null,
             method: "customQuery()",
             parameters: { query, options },
-            types: options.types,
         }));
     }
     /**
-     * Loads a database from a specified file into the current SimpleDB instance.
-     * Supported file types are `.db` (DuckDB) and `.sqlite` (SQLite).
-     *
-     * @param file - The absolute path to the database file (e.g., "./my_database.db").
-     * @param options - Configuration options for loading the database.
-     * @param options.name - The name to assign to the loaded database within the DuckDB instance. Defaults to the file name without extension.
-     * @param options.detach - If `true` (default), the database is detached after loading its contents into memory. If `false`, the database remains attached.
-     * @returns A promise that resolves when the database has been loaded.
+     * Imports a copy of a `.db` or `.duckdb` (DuckDB) or `.sqlite` (SQLite)
+     * file into the current database. The source is opened read-only and detached
+     * after importing; subsequent transformations do not modify the source file.
+     * Imports work with in-memory and writable persistent databases. Existing
+     * table-name conflicts are rejected and a failed copy is rolled back.
+     *
+     * DuckDB files restore embedded SDA index definitions when present. SQLite
+     * imports copy data without SDA index metadata. The `__sda` schema is reserved
+     * for SDA metadata.
+     * To edit an existing DuckDB file in place, use `new SimpleDB({ file })`.
+     *
+     * @param file - The relative or absolute path to the database file.
+     * @returns A promise that resolves to the database, so methods can be chained.
      * @category File Operations
      *
      * @example
@@ -670,85 +792,42 @@ export default class SimpleDB extends Simple {
      *
      * @example
      * ```ts
-     * // Load a SQLite database file and keep it attached
-     * await sdb.loadDB("./my_database.sqlite", { detach: false });
+     * // Import SQLite tables without modifying the original file
+     * await sdb.loadDB("./my_database.sqlite");
      * ```
      *
      * @example
      * ```ts
-     * // Load a database with a custom name
-     * await sdb.loadDB("./archive.db", { name: "archive_db" });
+     * // Import a copy into a persistent DuckDB database
+     * const sdb = new SimpleDB({ file: "./analysis.duckdb" });
+     * await sdb.loadDB("./archive.db");
+     * await sdb.close();
      * ```
      */
-    async loadDB(file, options = {}) {
-        const name = options.name ?? "my_database";
-        const detach = options.detach ?? true;
-        if (!existsSync(file)) {
-            throw new Error(`The file ${file} does not exist.`);
-        }
-        const extension = getExtension(file);
-        const allIndexesFile = `${file.replace(`.${extension}`, "")}_indexes.json`;
-        const vssIndex = checkVssIndexes(allIndexesFile);
-        if (vssIndex) {
-            await this.customQuery(`INSTALL vss; LOAD vss;`);
-        }
-        if (extension === "db") {
-            if (detach) {
-                await queryDB(this, `ATTACH '${cleanPath(file)}' AS ${name};
-COPY FROM DATABASE ${name} TO memory;
-DETACH ${name};`, mergeOptions(this, {
-                    returnDataFrom: "none",
-                    table: null,
-                    method: "loadDB()",
-                    parameters: {},
-                }));
-            }
-            else {
-                await queryDB(this, `ATTACH '${cleanPath(file)}' AS ${name};
-          USE ${name};`, mergeOptions(this, {
-                    returnDataFrom: "none",
-                    table: null,
-                    method: "loadDB()",
-                    parameters: {},
-                }));
-            }
-        }
-        else if (extension === "sqlite") {
-            if (detach) {
-                await queryDB(this, `INSTALL sqlite; LOAD sqlite;
-        ATTACH '${cleanPath(file)}' AS ${name} (TYPE SQLITE);
-COPY FROM DATABASE ${name} TO memory;
-DETACH ${name};`, mergeOptions(this, {
-                    returnDataFrom: "none",
-                    table: null,
-                    method: "loadDB()",
-                    parameters: {},
-                }));
-            }
-            else {
-                await queryDB(this, `INSTALL sqlite; LOAD sqlite;
-        ATTACH '${cleanPath(file)}' AS ${name} (TYPE SQLITE);
-        USE ${name};`, mergeOptions(this, {
-                    returnDataFrom: "none",
-                    table: null,
-                    method: "loadDB()",
-                    parameters: {},
-                }));
-            }
-        }
-        else {
-            throw new Error(`The extension ${extension} is not supported. Please use .db or .sqlite instead.`);
-        }
-        await setDbProps(this, allIndexesFile);
+    async loadDB(file) {
+        await loadDB(this, file);
+        return this;
     }
     /**
-     * Writes the current state of the database to a specified file.
-     * Supported output file types are `.db` (DuckDB) and `.sqlite` (SQLite).
+     * Exports a snapshot of the current database after executing pending work.
+     * Does not change the working database or where subsequent changes persist.
+     * DuckDB outputs (`.db` and `.duckdb`) preserve database objects and embed SDA
+     * index definitions in the reserved `__sda` schema.
+     *
+     * SQLite output (`.sqlite`) materializes main-schema tables and views as
+     * tables. It does not preserve DuckDB schemas, indexes, constraints, or SDA
+     * metadata, and SQLite type conversion may lose type information. Unsupported
+     * conversions fail without replacing an existing destination.
+     *
+     * Existing files require explicit overwrite permission. The completed export
+     * is published only after its connection is detached. Database files attached
+     * to this instance, directories, and symbolic links cannot be replaced.
      *
-     * @param file - The absolute path to the output file (e.g., "./my_exported_database.db").
+     * @param file - The relative or absolute path to the output file.
      * @param options - Configuration options for writing the database.
-     * @param options.noMetaData - If `true`, metadata files (indexes) are not created alongside the database file. Defaults to `false`.
-     * @returns A promise that resolves when the database has been written to the file.
+     * @param options.overwrite - If true, permits atomic replacement of an existing output file. Defaults to false.
+     * @param options.metadata - If false, omits logical SDA index definitions from DuckDB exports. Defaults to true. Does not control physical indexes; SQLite exports never include SDA metadata.
+     * @returns A promise that resolves to the database, so methods can be chained.
      * @category File Operations
      *
      * @example
@@ -759,96 +838,202 @@ DETACH ${name};`, mergeOptions(this, {
      *
      * @example
      * ```ts
-     * // Write the current database to a SQLite file without metadata
-     * await sdb.writeDB("./my_exported_database.sqlite", { noMetaData: true });
+     * // Explicitly replace an earlier snapshot
+     * await sdb.writeDB("./my_exported_database.duckdb", { overwrite: true });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Export table data for use with SQLite
+     * await sdb.writeDB("./my_exported_database.sqlite");
      * ```
      */
     async writeDB(file, options = {}) {
-        const noMetaData = options.noMetaData ?? false;
-        if (existsSync(file)) {
-            rmSync(file);
-        }
-        createDirectory(file);
-        const extension = getExtension(file);
-        if (!noMetaData) {
-            writeIndexes(this, extension, file);
-        }
-        const name = getName(file);
-        if (extension === "db") {
-            await queryDB(this, `ATTACH '${cleanPath(file)}' AS ${name};
-COPY FROM DATABASE ${getName(this.file)} TO ${name};
-DETACH ${name};`, mergeOptions(this, {
-                returnDataFrom: "none",
-                table: null,
-                method: "writeDB()",
-                parameters: {},
-            }));
-        }
-        else if (extension === "sqlite") {
-            await queryDB(this, `INSTALL sqlite; LOAD sqlite;
-        ATTACH '${cleanPath(file)}' AS ${name} (TYPE SQLITE);
-COPY FROM DATABASE ${getName(this.file)} TO ${name};
-DETACH ${name};`, mergeOptions(this, {
-                returnDataFrom: "none",
-                table: null,
-                method: "writeDB()",
-                parameters: {},
-            }));
-        }
-        else {
-            throw new Error(`The extension ${extension} is not supported. Please use .db or .sqlite instead.`);
+        await writeDB(this, file, options);
+        return this;
+    }
+    /**
+     * Executes all queued methods across every table in the database. Sync
+     * builder methods (like `filter()` or `convert()`) only queue their
+     * operation; execution happens when an async observer method (like
+     * `getData()`, `log()`, or `writeData()`) is awaited. Use `run()` when
+     * your script ends in pure mutations with nothing to observe and you want
+     * the work done now.
+     *
+     * The whole database is flushed in program order, so operations on
+     * different tables execute exactly in the order they were queued. This is
+     * the database-level counterpart to `SimpleTable.run()`.
+     *
+     * @returns A promise that resolves to the SimpleDB instance once the queued methods have been executed.
+     * @category Lifecycle
+     *
+     * @example
+     * ```ts
+     * // Nothing is observed after the mutations, so run() executes them.
+     * table1.loadData("data1.csv").convert({ price: "number" });
+     * table2.loadData("data2.csv").filter(`price > 0`);
+     * await sdb.run();
+     * ```
+     */
+    async run() {
+        if (this.lifecycleState !== "open") {
+            throw new Error(`run() cannot use a SimpleDB that is ${this.lifecycleState}.`);
         }
+        await flushAllTables(this);
+        return this;
     }
     /**
-     * Frees up memory by closing the database connection and instance, and cleans up the cache.
-     * If the database is file-based, it also compacts the database file to optimize storage.
+     * Executes pending transformations, saves SDA metadata for writable persistent
+     * databases, and closes the connection and instance. Also cleans up temporary
+     * files and the cache. Does not copy, compact, or replace the database file.
      *
      * @returns A promise that resolves to the SimpleDB instance after cleanup.
+     * @throws An error after cleanup when pending execution or cleanup fails.
      * @category Lifecycle
      *
      * @example
      * ```ts
-     * // Close the database and clean up resources
-     * await sdb.done();
+     * // close() executes queued transformations before cleaning up resources.
+     * table.loadData("data.csv").convert({ price: "number" });
+     * await sdb.close();
      * ```
      */
-    async done() {
-        if (this.file !== ":memory:") {
-            await this.customQuery("CHECKPOINT;");
-            // To make sure the files will have the proper names.
-            writeIndexes(this, getExtension(this.file), this.file);
-            await this.writeDB(this.file.replace(".db", "_compacted.db"), {
-                noMetaData: true,
-            });
+    async close() {
+        if (__classPrivateFieldGet(this, _SimpleDB_closePromise, "f") !== null) {
+            return await __classPrivateFieldGet(this, _SimpleDB_closePromise, "f");
+        }
+        this.lifecycleState = "closing";
+        const closePromise = __classPrivateFieldGet(this, _SimpleDB_instances, "m", _SimpleDB_close).call(this);
+        __classPrivateFieldSet(this, _SimpleDB_closePromise, closePromise, "f");
+        return await closePromise;
+    }
+}
+_SimpleDB_closePromise = new WeakMap(), _SimpleDB_startPromise = new WeakMap(), _SimpleDB_initialized = new WeakMap(), _SimpleDB_instances = new WeakSet(), _SimpleDB_setup = async function _SimpleDB_setup() {
+    if (this.readOnly && (this.file === ":memory:" || this.overwrite)) {
+        throw new Error("readOnly requires an existing database file and cannot be combined with overwrite.");
+    }
+    if (this.file !== ":memory:") {
+        if (getDbFileType(this.file) !== "duckdb") {
+            throw new Error("Persistent databases must use .db or .duckdb. Use loadDB() to import SQLite files.");
+        }
+        if (this.readOnly && !existsSync(this.file)) {
+            throw new Error(`The file ${this.file} does not exist.`);
+        }
+        if (existsSync(this.file) && this.overwrite) {
             rmSync(this.file);
-            renameSync(this.file.replace(".db", "_compacted.db"), this.file);
+            // A WAL belongs to the database being explicitly replaced.
+            rmSync(`${this.file}.wal`, { force: true });
+        }
+        if (!this.readOnly)
+            createDirectory(this.file);
+    }
+    this.db = await DuckDBInstance.create(this.file, this.readOnly ? { access_mode: "READ_ONLY" } : {});
+    this.connection = await this.db.connect();
+    // Keep temporal parsing, extraction, and serialization deterministic
+    // across machines. DuckDB otherwise inherits the process timezone.
+    await this.customQuery("SET TimeZone = 'UTC';");
+    // By default, DuckDB does not compress in-memory databases, so we enable it here.
+    if (this.file === ":memory:") {
+        await this.customQuery(`ATTACH OR REPLACE ':memory:' AS ${quoteIdentifier("memory")} (COMPRESS);`);
+    }
+    if (this.duckDbCache === true) {
+        await this.customQuery("SET enable_external_file_cache=true;");
+    }
+    else if (this.duckDbCache === false) {
+        await this.customQuery("SET enable_external_file_cache=false;");
+    }
+    if (this.progressBar) {
+        await this.customQuery(`SET enable_progress_bar = TRUE; SET progress_bar_time = 0;`);
+    }
+    if (this.memoryLimit !== undefined) {
+        await this.customQuery(`SET memory_limit = '${this.memoryLimit}';`);
+    }
+    if (this.tempDir !== undefined) {
+        await this.customQuery(`SET temp_directory = '${this.tempDir}';`);
+    }
+    if (this.file !== ":memory:") {
+        const database = await getCurrentDatabase(this);
+        const indexes = await readDbMetadata(this, database);
+        await prepareDbExtensions(this, database, indexes);
+        const existingNames = new Set((await this.getTableNames()).map((name) => name.toLowerCase()));
+        const conflicts = this.getTables().filter((table) => existingNames.has(table.name.toLowerCase()));
+        if (conflicts.length > 0) {
+            throw new Error(`Tables already exist in ${this.file}: ${conflicts.map((table) => table.name).join(", ")}. Use getTable() to access them.`);
+        }
+        await setDbProps(this, indexes);
+    }
+}, _SimpleDB_close = async function _SimpleDB_close() {
+    let operationError;
+    try {
+        await flushAllTables(this);
+        if (this.file !== ":memory:" && !this.readOnly && __classPrivateFieldGet(this, _SimpleDB_initialized, "f")) {
+            const database = await getCurrentDatabase(this);
+            await readDbMetadata(this, database);
+            await writeDbMetadata(this, database, getDbIndexes(this));
+            await queryDbFile(this, `CHECKPOINT ${quoteIdentifier(database)};`);
         }
-        if (this.db instanceof DuckDBInstance) {
+    }
+    catch (error) {
+        operationError = error;
+        // A failed flush can requeue work belonging to other tables. The
+        // connection is about to close, so release those captured values.
+        discardAllPending(this);
+    }
+    const cleanupErrors = [];
+    if (this.db instanceof DuckDBInstance) {
+        try {
             this.connection.closeSync();
+        }
+        catch (error) {
+            cleanupErrors.push(error);
+        }
+        try {
             this.db.closeSync();
         }
-        const tmpDir = this.tempDirectory ??
+        catch (error) {
+            cleanupErrors.push(error);
+        }
+    }
+    try {
+        const tmpDir = this.tempDir ??
             (this.file === ":memory:" ? ".tmp" : `${this.file}.tmp`);
         if (existsSync(tmpDir)) {
             rmSync(tmpDir, { recursive: true });
         }
         cleanCache(this);
-        if (typeof this.durationStart === "number") {
-            let string = prettyDuration(this.durationStart, {
-                prefix: "\n\nSimpleDB - Done in ",
-            });
-            if (this.cacheTimeSaved > 0) {
-                string += ` / ${prettyDuration(0, {
-                    end: this.cacheTimeSaved,
-                })} saved by using the cache`;
-            }
-            if (this.cacheTimeWriting > 0) {
-                string += ` / ${prettyDuration(0, {
-                    end: this.cacheTimeWriting,
-                })} spent writing the cache`;
-            }
-            console.log(`${string}\n`);
+    }
+    catch (error) {
+        cleanupErrors.push(error);
+    }
+    this.lifecycleState = "closed";
+    if (operationError !== undefined && cleanupErrors.length > 0) {
+        throw new AggregateError([operationError, ...cleanupErrors], "Pending execution and database cleanup both failed.", { cause: operationError });
+    }
+    if (operationError !== undefined) {
+        throw operationError;
+    }
+    if (cleanupErrors.length === 1) {
+        throw cleanupErrors[0];
+    }
+    if (cleanupErrors.length > 1) {
+        throw new AggregateError(cleanupErrors, "Multiple errors occurred while cleaning up the database.", { cause: cleanupErrors[0] });
+    }
+    if (typeof this.durationStart === "number") {
+        let string = prettyDuration(this.durationStart, {
+            prefix: "\n\nSimpleDB ran for ",
+        });
+        if (this.cacheTimeSaved > 0) {
+            string += ` / ${prettyDuration(0, {
+                end: this.cacheTimeSaved,
+            })} saved by using the cache`;
+        }
+        if (this.cacheTimeWriting > 0) {
+            string += ` / ${prettyDuration(0, {
+                end: this.cacheTimeWriting,
+            })} spent writing the cache`;
         }
-        return await this;
+        console.log(`${string}\n`);
     }
-}
+    return await this;
+};
+export default SimpleDB;