@flowblade/sqlduck 0.10.0 → 0.11.0

package/README.md

@@ -4,6 +4,74 @@
 
 ## Quick start
 
+### Create a database connection
+
+```typescript
+import { DuckDBInstance } from '@duckdb/node-api';
+DuckDBInstance.create(undefined, {
+   access_mode: 'READ_WRITE',
+   max_memory: '512M',
+});
+export const conn = await instance.connect();
+```
+
+### Append data to a database
+
+```typescript
+import { SqlDuck, DuckDatabaseManager } from "@flowblade/sqlduck";
+import * as z from "zod";
+import { conn } from "./db.config.ts";
+
+const dbManager = new DuckDatabaseManager(conn);
+const database = await dbManager.attach({
+    type: ':memory:', // can be 'duckdb', ...
+    alias: 'mydb',
+    options: { COMPRESS: 'false' },
+});
+
+const sqlDuck = new SqlDuck({ conn });
+
+// Define a zod schema, it will be used to create the table
+const userSchema = z.object({
+    id: z.int32().min(1).meta({ primaryKey: true }),
+    name: z.string(),
+});
+
+// Example of a datasource (can be generator, async generator, async iterable)
+async function* getUsers(): AsyncIterableIterator<
+    z.infer<typeof userSchema>
+> {
+    // database or api call
+    yield { id: 1, name: 'John' };
+    yield { id: 2, name: 'Jane' };
+}
+
+// Create a table from the schema and the datasource
+const result = await sqlDuck.toTable({
+    table: new Table({ name: 'user', database: database.alias }),
+    schema: userSchema, // The schema to use to create the table
+    rowStream: getUsers(), // The async iterable that yields rows
+    // 👇Optional:
+    chunkSize: 2048, // Number of rows to append when using duckdb appender. Default is 2048
+    onDataAppended: ({ timeMs, totalRows, rowsPerSecond }) => {
+        console.log(
+            `Appended ${totalRows} in time ${timeMs}ms, est: ${rowsPerSecond} rows/s`
+        );
+    },
+    // Optional table creation options
+    createOptions: {
+        create: 'CREATE_OR_REPLACE',
+    },
+});
+
+console.log(`Inserted ${result.totalRows} rows in ${result.timeMs}ms`);
+console.log(`Table created with DDL: ${result.createTableDDL}`);
+
+const reader = await conn.runAndReadAll('select * from mydb.user');
+const rows = reader.getRowObjectsJS();
+// [{id: 1, name: 'John'}, {id: 2, name: 'Jane'}]]
+```
+
 ### Create a memory table
 
 ```typescript
@@ -35,7 +103,6 @@ const result = sqlDuck.toTable({
   onDataAppended: ({ total }) => {
     console.log(`Appended ${total} rows so far`);
   },
-  onDataAppendedBatchSize: 4096, // Call onDataAppended every 4096 rows
   // Optional table creation options
   createOptions: {
     create: "CREATE_OR_REPLACE",

package/dist/index.cjs

@@ -21,13 +21,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-let _logtape_logtape = require("@logtape/logtape");
 let _duckdb_node_api = require("@duckdb/node-api");
+let _logtape_logtape = require("@logtape/logtape");
 let zod = require("zod");
 zod = __toESM(zod);
-//#region src/config/flowblade-logtape-sqlduck.config.ts
-const flowbladeLogtapeSqlduckConfig = { categories: ["flowblade", "sqlduck"] };
-//#endregion
+let _httpx_assert = require("@httpx/assert");
+let _httpx_plain_object = require("@httpx/plain-object");
 //#region src/helpers/duck-exec.ts
 var DuckExec = class {
 	#conn;
@@ -124,9 +123,6 @@ var DuckMemory = class {
 	};
 };
 //#endregion
-//#region src/logger/sqlduck-default-logtape-logger.ts
-const sqlduckDefaultLogtapeLogger = (0, _logtape_logtape.getLogger)(flowbladeLogtapeSqlduckConfig.categories);
-//#endregion
 //#region src/appender/data-appender-callback.ts
 const isOnDataAppendedAsyncCb = (v) => {
 	return v.constructor.name === "AsyncFunction";
@@ -148,6 +144,12 @@ const createOnDataAppendedCollector = () => {
 	};
 };
 //#endregion
+//#region src/config/flowblade-logtape-sqlduck.config.ts
+const flowbladeLogtapeSqlduckConfig = { categories: ["flowblade", "sqlduck"] };
+//#endregion
+//#region src/logger/sqlduck-default-logtape-logger.ts
+const sqlduckDefaultLogtapeLogger = (0, _logtape_logtape.getLogger)(flowbladeLogtapeSqlduckConfig.categories);
+//#endregion
 //#region src/table/get-duckdb-number-column-type.ts
 const isFloatValue = (value) => {
 	if (!Number.isFinite(value)) return true;
@@ -181,7 +183,7 @@ const createOptions = {
 	CREATE_OR_REPLACE: "CREATE OR REPLACE TABLE",
 	IF_NOT_EXISTS: "CREATE TABLE IF NOT EXISTS"
 };
-const duckDbTypes = [
+const duckDbTypesMap = new Map([
 	["VARCHAR", _duckdb_node_api.VARCHAR],
 	["BIGINT", _duckdb_node_api.BIGINT],
 	["TIMESTAMP", _duckdb_node_api.TIMESTAMP],
@@ -190,8 +192,7 @@ const duckDbTypes = [
 	["INTEGER", _duckdb_node_api.INTEGER],
 	["DOUBLE", _duckdb_node_api.DOUBLE],
 	["FLOAT", _duckdb_node_api.FLOAT]
-];
-const duckDbTypesMap = new Map(duckDbTypes);
+]);
 const getTableCreateFromZod = (params) => {
 	const { table, schema, options } = params;
 	const { create = "CREATE" } = options ?? {};
@@ -327,10 +328,10 @@ async function* rowsToColumnsChunks(params) {
 //#endregion
 //#region src/sql-duck.ts
 var SqlDuck = class {
-	#duck;
+	#conn;
 	#logger;
 	constructor(params) {
-		this.#duck = params.conn;
+		this.#conn = params.conn;
 		this.#logger = params.logger ?? sqlduckDefaultLogtapeLogger;
 	}
 	/**
@@ -375,12 +376,12 @@ var SqlDuck = class {
 		if (!Number.isSafeInteger(chunkSize) || chunkSize < 1 || chunkSize > 2048) throw new Error("chunkSize must be a number between 1 and 2048");
 		const timeStart = Date.now();
 		const { columnTypes, ddl } = await createTableFromZod({
-			conn: this.#duck,
+			conn: this.#conn,
 			schema,
 			table,
 			options: createOptions
 		});
-		const appender = await this.#duck.createAppender(table.tableName, table.schemaName, table.databaseName);
+		const appender = await this.#conn.createAppender(table.tableName, table.schemaName, table.databaseName);
 		const chunkTypes = Array.from(columnTypes.values());
 		let totalRows = 0;
 		const dataAppendedCollector = createOnDataAppendedCollector();
@@ -423,7 +424,39 @@ var SqlDuck = class {
 	};
 };
 //#endregion
-//#region src/table/table.ts
+//#region src/utils/zod-codecs.ts
+const zodCodecs = {
+	dateToString: zod.codec(zod.date(), zod.iso.datetime(), {
+		decode: (date) => date.toISOString(),
+		encode: (isoString) => new Date(isoString)
+	}),
+	bigintToString: zod.codec(zod.bigint(), zod.string().meta({ format: "int64" }), {
+		decode: (bigint) => bigint.toString(),
+		encode: BigInt
+	})
+};
+//#endregion
+//#region src/objects/database.ts
+var Database = class {
+	#params;
+	get alias() {
+		return this.#params.alias;
+	}
+	constructor(params) {
+		this.#params = params;
+	}
+	toJson() {
+		return {
+			type: "database",
+			params: { alias: this.#params.alias }
+		};
+	}
+	[Symbol.toStringTag]() {
+		return this.alias;
+	}
+};
+//#endregion
+//#region src/objects/table.ts
 var Table = class Table {
 	#fqTable;
 	get tableName() {
@@ -465,21 +498,272 @@ var Table = class Table {
 	};
 };
 //#endregion
-//#region src/utils/zod-codecs.ts
-const zodCodecs = {
-	dateToString: zod.codec(zod.date(), zod.iso.datetime(), {
-		decode: (date) => date.toISOString(),
-		encode: (isoString) => new Date(isoString)
-	}),
-	bigintToString: zod.codec(zod.bigint(), zod.string().meta({ format: "int64" }), {
-		decode: (bigint) => bigint.toString(),
-		encode: BigInt
-	})
+//#region src/validation/core/duckdb-reserved-keywords.ts
+/**
+* DuckDB reserved keywords that cannot be used as unquoted identifiers.
+* @see https://duckdb.org/docs/sql/keywords-and-identifiers.html
+*/
+const duckdbReservedKeywords = [
+	"ALL",
+	"ANALYSE",
+	"ANALYZE",
+	"AND",
+	"ANY",
+	"ARRAY",
+	"AS",
+	"ASC",
+	"ASYMMETRIC",
+	"BOTH",
+	"CASE",
+	"CAST",
+	"CHECK",
+	"COLLATE",
+	"COLUMN",
+	"CONSTRAINT",
+	"CREATE",
+	"CROSS",
+	"CURRENT_CATALOG",
+	"CURRENT_DATE",
+	"CURRENT_ROLE",
+	"CURRENT_SCHEMA",
+	"CURRENT_TIME",
+	"CURRENT_TIMESTAMP",
+	"CURRENT_USER",
+	"DEFAULT",
+	"DEFERRABLE",
+	"DESC",
+	"DISTINCT",
+	"DO",
+	"ELSE",
+	"END",
+	"EXCEPT",
+	"EXISTS",
+	"EXTRACT",
+	"FALSE",
+	"FETCH",
+	"FOR",
+	"FOREIGN",
+	"FROM",
+	"GRANT",
+	"GROUP",
+	"HAVING",
+	"IF",
+	"ILIKE",
+	"IN",
+	"INITIALLY",
+	"INNER",
+	"INTERSECT",
+	"INTO",
+	"IS",
+	"ISNULL",
+	"JOIN",
+	"LATERAL",
+	"LEADING",
+	"LEFT",
+	"LIKE",
+	"LIMIT",
+	"LOCALTIME",
+	"LOCALTIMESTAMP",
+	"NATURAL",
+	"NOT",
+	"NOTNULL",
+	"NULL",
+	"OFFSET",
+	"ON",
+	"ONLY",
+	"OR",
+	"ORDER",
+	"OUTER",
+	"OVERLAPS",
+	"PLACING",
+	"PRIMARY",
+	"REFERENCES",
+	"RETURNING",
+	"RIGHT",
+	"ROW",
+	"SELECT",
+	"SESSION_USER",
+	"SIMILAR",
+	"SOME",
+	"SYMMETRIC",
+	"TABLE",
+	"THEN",
+	"TO",
+	"TRAILING",
+	"TRUE",
+	"UNION",
+	"UNIQUE",
+	"USING",
+	"VARIADIC",
+	"VERBOSE",
+	"WHEN",
+	"WHERE",
+	"WINDOW",
+	"WITH"
+];
+//#endregion
+//#region src/validation/zod/duckdb-valid-names.schemas.ts
+const duckdbMaximumObjectNameLength = 120;
+const duckDbObjectNameRegex = /^[a-z_]\w*$/i;
+const duckdbReservedKeywordsSet = new Set(duckdbReservedKeywords.map((k) => k.toUpperCase()));
+const duckTableNameSchema = zod.string().min(1).max(duckdbMaximumObjectNameLength).regex(duckDbObjectNameRegex, "Table name must start with a letter or underscore, and contain only letters, numbers and underscores").refine((value) => !duckdbReservedKeywordsSet.has(value.toUpperCase()), { error: `Value is a DuckDB reserved keyword and cannot be used as a table name` });
+const duckTableAliasSchema = duckTableNameSchema;
+//#endregion
+//#region src/manager/database/duck-database-manager.schemas.ts
+const duckdbAttachOptionsSchema = zod.strictObject({
+	ACCESS_MODE: zod.optional(zod.enum([
+		"READ_ONLY",
+		"READ_WRITE",
+		"AUTOMATIC"
+	])),
+	COMPRESS: zod.optional(zod.enum(["true", "false"])),
+	TYPE: zod.optional(zod.enum(["DUCKDB", "SQLITE"])),
+	BLOCK_SIZE: zod.optional(zod.int32().min(16384).max(262144)),
+	ROW_GROUP_SIZE: zod.optional(zod.int32().positive()),
+	STORAGE_VERSION: zod.optional(zod.string().startsWith("v").regex(/^v?\d{1,4}\.\d{1,4}\.\d{1,4}$/)),
+	ENCRYPTION_KEY: zod.optional(zod.string().min(8)),
+	ENCRYPTION_CIPHER: zod.optional(zod.enum([
+		"CBC",
+		"CTR",
+		"GCM"
+	]))
+});
+const duckDatabaseManagerDbParamsSchema = zod.discriminatedUnion("type", [zod.strictObject({
+	type: zod.literal(":memory:"),
+	alias: duckTableAliasSchema,
+	options: zod.optional(duckdbAttachOptionsSchema)
+}), zod.strictObject({
+	type: zod.literal("duckdb"),
+	path: zod.string().min(4).endsWith(".db"),
+	alias: duckTableAliasSchema,
+	options: zod.optional(duckdbAttachOptionsSchema)
+})]);
+//#endregion
+//#region src/manager/database/commands/duck-database-attach-command.ts
+var DuckDatabaseAttachCommand = class {
+	options;
+	dbParams;
+	constructor(dbParams, options) {
+		this.dbParams = dbParams;
+		this.options = options ?? {};
+	}
+	getRawSql = () => {
+		const dbParams = this.dbParams;
+		const parts = ["ATTACH", this.options.behaviour].filter(Boolean);
+		const { type, alias } = dbParams;
+		switch (type) {
+			case ":memory:":
+				parts.push("':memory:'");
+				break;
+			case "duckdb":
+				parts.push(`'${dbParams.path}'`);
+				break;
+			default: (0, _httpx_assert.assertNever)(type);
+		}
+		if (alias !== null) parts.push("AS", `${alias}`);
+		const options = (0, _httpx_plain_object.isPlainObject)(dbParams.options) ? Object.entries(dbParams.options).map(([key, value]) => {
+			return key === "ACCESS_MODE" ? value : `${key} '${value}'`;
+		}) : [];
+		if (options.length > 0) parts.push(`(${options.join(", ")})`);
+		return parts.filter(Boolean).join(" ");
+	};
+};
+//#endregion
+//#region src/manager/database/duck-database-manager.ts
+var DuckDatabaseManager = class {
+	#conn;
+	#logger;
+	constructor(conn, params) {
+		this.#conn = conn;
+		this.#logger = params?.logger ?? sqlduckDefaultLogtapeLogger.with({ source: "DuckDatabaseManager" });
+	}
+	/**
+	* Attach a database to the current connection
+	*
+	* @example
+	* ```typescript
+	* const dbManager = new DuckDatabaseManager(conn);
+	* const database = dbManager.attach({
+	*   type: ':memory:', // can be 'duckdb', 's3'...
+	*   alias: 'mydb',
+	*   options: { COMPRESS: 'true' }
+	* });
+	*
+	* console.log(database.alias); // 'mydb'
+	* ```
+	*/
+	attach = async (dbParams, options) => {
+		const params = zod.parse(duckDatabaseManagerDbParamsSchema, dbParams);
+		const rawSql = new DuckDatabaseAttachCommand(params, options).getRawSql();
+		await this.#executeRawSqlCommand(`attach(${params.alias})`, rawSql);
+		return new Database({ alias: params.alias });
+	};
+	attachOrReplace = async (dbParams) => {
+		return this.attach(dbParams, { behaviour: "OR REPLACE" });
+	};
+	attachIfNotExists = async (dbParams) => {
+		return this.attach(dbParams, { behaviour: "IF NOT EXISTS" });
+	};
+	showDatabases = async () => {
+		return await this.#executeRawSqlCommand("showDatabases()", `SHOW DATABASES`);
+	};
+	detach = async (dbAlias) => {
+		const safeAlias = zod.parse(duckTableAliasSchema, dbAlias);
+		await this.#executeRawSqlCommand(`detach(${safeAlias})`, `DETACH ${safeAlias}`);
+		return true;
+	};
+	detachIfExists = async (dbAlias) => {
+		const safeAlias = zod.parse(duckTableAliasSchema, dbAlias);
+		await this.#executeRawSqlCommand(`detachIfExists(${safeAlias})`, `DETACH IF EXISTS ${safeAlias}`);
+		return true;
+	};
+	/**
+	* The statistics recomputed by the ANALYZE statement are only used for join order optimization.
+	*
+	* It is therefore recommended to recompute these statistics for improved join orders,
+	* especially after performing large updates (inserts and/or deletes).
+	*
+	* @link https://duckdb.org/docs/stable/sql/statements/analyze
+	*/
+	analyze = async () => {
+		await this.#executeRawSqlCommand("analyze()", "ANALYZE");
+		return true;
+	};
+	checkpoint = async (dbAlias) => {
+		const safeAlias = zod.parse(duckTableAliasSchema, dbAlias);
+		await this.#executeRawSqlCommand(`checkpoint(${safeAlias})`, `CHECKPOINT ${safeAlias}`);
+		return true;
+	};
+	#executeRawSqlCommand = async (name, rawSql) => {
+		const startTime = Date.now();
+		try {
+			const result = await this.#conn.runAndReadAll(rawSql);
+			const timeMs = Math.round(Date.now() - startTime);
+			const data = result.getRowObjectsJS();
+			this.#logger.info(`DuckDatabaseManager.${name} in ${timeMs}ms`, { timeMs });
+			return data;
+		} catch (e) {
+			const msg = `DuckDatabaseManager: failed to run "${name}" - ${e?.message ?? ""}`;
+			const timeMs = Math.round(Date.now() - startTime);
+			this.#logger.error(msg, {
+				name,
+				sql: rawSql,
+				timeMs
+			});
+			throw new Error(msg, { cause: e });
+		}
+	};
 };
 //#endregion
+exports.Database = Database;
+exports.DuckDatabaseManager = DuckDatabaseManager;
 exports.DuckMemory = DuckMemory;
 exports.SqlDuck = SqlDuck;
 exports.Table = Table;
+exports.duckDatabaseManagerDbParamsSchema = duckDatabaseManagerDbParamsSchema;
+exports.duckTableAliasSchema = duckTableAliasSchema;
+exports.duckTableNameSchema = duckTableNameSchema;
+exports.duckdbReservedKeywords = duckdbReservedKeywords;
 exports.flowbladeLogtapeSqlduckConfig = flowbladeLogtapeSqlduckConfig;
 exports.getTableCreateFromZod = getTableCreateFromZod;
 exports.sqlduckDefaultLogtapeLogger = sqlduckDefaultLogtapeLogger;

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import * as _duckdb_node_api0 from "@duckdb/node-api";
 import { DuckDBConnection, DuckDBType } from "@duckdb/node-api";
 import * as _logtape_logtape0 from "@logtape/logtape";
 import { Logger } from "@logtape/logtape";
@@ -23,11 +24,6 @@ type OnDataAppendedSyncCb = (stats: OnDataAppendedStats) => void;
 type OnDataAppendedAsyncCb = (stats: OnDataAppendedStats) => Promise<void>;
 type OnDataAppendedCb = OnDataAppendedSyncCb | OnDataAppendedAsyncCb;
 //#endregion
-//#region src/config/flowblade-logtape-sqlduck.config.d.ts
-declare const flowbladeLogtapeSqlduckConfig: {
-  categories: string[];
-};
-//#endregion
 //#region src/helpers/duck-memory.d.ts
 declare const duckMemoryTags: readonly ["BASE_TABLE", "HASH_TABLE", "PARQUET_READER", "CSV_READER", "ORDER_BY", "ART_INDEX", "COLUMN_DATA", "METADATA", "OVERFLOW_STRINGS", "IN_MEMORY_TABLE", "ALLOCATOR", "EXTENSION", "TRANSACTION", "EXTERNAL_FILE_CACHE", "WINDOW", "OBJECT_CACHE"];
 type DuckMemoryTag = (typeof duckMemoryTags)[number];
@@ -56,10 +52,7 @@ declare class DuckMemory {
   getSummary: () => Promise<DuckMemorySummary>;
 }
 //#endregion
-//#region src/logger/sqlduck-default-logtape-logger.d.ts
-declare const sqlduckDefaultLogtapeLogger: _logtape_logtape0.Logger;
-//#endregion
-//#region src/table/table.d.ts
+//#region src/objects/table.d.ts
 /**
  * Fully qualified table information
  */
@@ -208,4 +201,145 @@ declare const zodCodecs: {
   readonly bigintToString: z.ZodCodec<z.ZodBigInt, z.ZodString>;
 };
 //#endregion
-export { DuckMemory, DuckMemoryTag, type OnDataAppendedCb, type OnDataAppendedStats, SqlDuck, type SqlDuckParams, Table, type ToTableParams, flowbladeLogtapeSqlduckConfig, getTableCreateFromZod, sqlduckDefaultLogtapeLogger, zodCodecs };
+//#region src/objects/database.d.ts
+type DatabaseProperties = {
+  alias: string;
+};
+declare class Database {
+  #private;
+  get alias(): string;
+  constructor(params: DatabaseProperties);
+  toJson(): {
+    type: string;
+    params: {
+      alias: string;
+    };
+  };
+  [Symbol.toStringTag](): string;
+}
+//#endregion
+//#region src/manager/database/duck-database-manager.schemas.d.ts
+declare const duckDatabaseManagerDbParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  type: z.ZodLiteral<":memory:">;
+  alias: z.ZodString;
+  options: z.ZodOptional<z.ZodObject<{
+    ACCESS_MODE: z.ZodOptional<z.ZodEnum<{
+      READ_ONLY: "READ_ONLY";
+      READ_WRITE: "READ_WRITE";
+      AUTOMATIC: "AUTOMATIC";
+    }>>;
+    COMPRESS: z.ZodOptional<z.ZodEnum<{
+      true: "true";
+      false: "false";
+    }>>;
+    TYPE: z.ZodOptional<z.ZodEnum<{
+      DUCKDB: "DUCKDB";
+      SQLITE: "SQLITE";
+    }>>;
+    BLOCK_SIZE: z.ZodOptional<z.ZodInt32>;
+    ROW_GROUP_SIZE: z.ZodOptional<z.ZodInt32>;
+    STORAGE_VERSION: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_KEY: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_CIPHER: z.ZodOptional<z.ZodEnum<{
+      CBC: "CBC";
+      CTR: "CTR";
+      GCM: "GCM";
+    }>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+  type: z.ZodLiteral<"duckdb">;
+  path: z.ZodString;
+  alias: z.ZodString;
+  options: z.ZodOptional<z.ZodObject<{
+    ACCESS_MODE: z.ZodOptional<z.ZodEnum<{
+      READ_ONLY: "READ_ONLY";
+      READ_WRITE: "READ_WRITE";
+      AUTOMATIC: "AUTOMATIC";
+    }>>;
+    COMPRESS: z.ZodOptional<z.ZodEnum<{
+      true: "true";
+      false: "false";
+    }>>;
+    TYPE: z.ZodOptional<z.ZodEnum<{
+      DUCKDB: "DUCKDB";
+      SQLITE: "SQLITE";
+    }>>;
+    BLOCK_SIZE: z.ZodOptional<z.ZodInt32>;
+    ROW_GROUP_SIZE: z.ZodOptional<z.ZodInt32>;
+    STORAGE_VERSION: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_KEY: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_CIPHER: z.ZodOptional<z.ZodEnum<{
+      CBC: "CBC";
+      CTR: "CTR";
+      GCM: "GCM";
+    }>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>], "type">;
+type DuckDatabaseManagerDbParams = z.infer<typeof duckDatabaseManagerDbParamsSchema>;
+//#endregion
+//#region src/manager/database/commands/duck-database-attach-command.d.ts
+type Behaviour = 'OR REPLACE' | 'IF NOT EXISTS';
+type DuckDatabaseAttachCommandOptions = {
+  behaviour?: Behaviour;
+};
+//#endregion
+//#region src/manager/database/duck-database-manager.d.ts
+declare class DuckDatabaseManager {
+  #private;
+  constructor(conn: DuckDBConnection, params?: {
+    logger?: Logger;
+  });
+  /**
+   * Attach a database to the current connection
+   *
+   * @example
+   * ```typescript
+   * const dbManager = new DuckDatabaseManager(conn);
+   * const database = dbManager.attach({
+   *   type: ':memory:', // can be 'duckdb', 's3'...
+   *   alias: 'mydb',
+   *   options: { COMPRESS: 'true' }
+   * });
+   *
+   * console.log(database.alias); // 'mydb'
+   * ```
+   */
+  attach: (dbParams: DuckDatabaseManagerDbParams, options?: DuckDatabaseAttachCommandOptions) => Promise<Database>;
+  attachOrReplace: (dbParams: DuckDatabaseManagerDbParams) => Promise<Database>;
+  attachIfNotExists: (dbParams: DuckDatabaseManagerDbParams) => Promise<Database>;
+  showDatabases: () => Promise<Record<string, _duckdb_node_api0.JS>[]>;
+  detach: (dbAlias: string) => Promise<boolean>;
+  detachIfExists: (dbAlias: string) => Promise<boolean>;
+  /**
+   * The statistics recomputed by the ANALYZE statement are only used for join order optimization.
+   *
+   * It is therefore recommended to recompute these statistics for improved join orders,
+   * especially after performing large updates (inserts and/or deletes).
+   *
+   * @link https://duckdb.org/docs/stable/sql/statements/analyze
+   */
+  analyze: () => Promise<boolean>;
+  checkpoint: (dbAlias: string) => Promise<boolean>;
+}
+//#endregion
+//#region src/validation/core/duckdb-reserved-keywords.d.ts
+/**
+ * DuckDB reserved keywords that cannot be used as unquoted identifiers.
+ * @see https://duckdb.org/docs/sql/keywords-and-identifiers.html
+ */
+declare const duckdbReservedKeywords: readonly ["ALL", "ANALYSE", "ANALYZE", "AND", "ANY", "ARRAY", "AS", "ASC", "ASYMMETRIC", "BOTH", "CASE", "CAST", "CHECK", "COLLATE", "COLUMN", "CONSTRAINT", "CREATE", "CROSS", "CURRENT_CATALOG", "CURRENT_DATE", "CURRENT_ROLE", "CURRENT_SCHEMA", "CURRENT_TIME", "CURRENT_TIMESTAMP", "CURRENT_USER", "DEFAULT", "DEFERRABLE", "DESC", "DISTINCT", "DO", "ELSE", "END", "EXCEPT", "EXISTS", "EXTRACT", "FALSE", "FETCH", "FOR", "FOREIGN", "FROM", "GRANT", "GROUP", "HAVING", "IF", "ILIKE", "IN", "INITIALLY", "INNER", "INTERSECT", "INTO", "IS", "ISNULL", "JOIN", "LATERAL", "LEADING", "LEFT", "LIKE", "LIMIT", "LOCALTIME", "LOCALTIMESTAMP", "NATURAL", "NOT", "NOTNULL", "NULL", "OFFSET", "ON", "ONLY", "OR", "ORDER", "OUTER", "OVERLAPS", "PLACING", "PRIMARY", "REFERENCES", "RETURNING", "RIGHT", "ROW", "SELECT", "SESSION_USER", "SIMILAR", "SOME", "SYMMETRIC", "TABLE", "THEN", "TO", "TRAILING", "TRUE", "UNION", "UNIQUE", "USING", "VARIADIC", "VERBOSE", "WHEN", "WHERE", "WINDOW", "WITH"];
+type DuckdbReservedKeywords = (typeof duckdbReservedKeywords)[number];
+//#endregion
+//#region src/validation/zod/duckdb-valid-names.schemas.d.ts
+declare const duckTableNameSchema: z.ZodString;
+declare const duckTableAliasSchema: z.ZodString;
+//#endregion
+//#region src/config/flowblade-logtape-sqlduck.config.d.ts
+declare const flowbladeLogtapeSqlduckConfig: {
+  categories: string[];
+};
+//#endregion
+//#region src/logger/sqlduck-default-logtape-logger.d.ts
+declare const sqlduckDefaultLogtapeLogger: _logtape_logtape0.Logger;
+//#endregion
+export { Database, DuckDatabaseManager, type DuckDatabaseManagerDbParams, DuckMemory, DuckMemoryTag, type DuckdbReservedKeywords, type OnDataAppendedCb, type OnDataAppendedStats, SqlDuck, type SqlDuckParams, Table, type ToTableParams, duckDatabaseManagerDbParamsSchema, duckTableAliasSchema, duckTableNameSchema, duckdbReservedKeywords, flowbladeLogtapeSqlduckConfig, getTableCreateFromZod, sqlduckDefaultLogtapeLogger, zodCodecs };

package/dist/index.d.mts

@@ -1,6 +1,7 @@
+import * as _duckdb_node_api0 from "@duckdb/node-api";
+import { DuckDBConnection, DuckDBType } from "@duckdb/node-api";
 import * as _logtape_logtape0 from "@logtape/logtape";
 import { Logger } from "@logtape/logtape";
-import { DuckDBConnection, DuckDBType } from "@duckdb/node-api";
 import * as z from "zod";
 import { ZodObject } from "zod";
 
@@ -23,11 +24,6 @@ type OnDataAppendedSyncCb = (stats: OnDataAppendedStats) => void;
 type OnDataAppendedAsyncCb = (stats: OnDataAppendedStats) => Promise<void>;
 type OnDataAppendedCb = OnDataAppendedSyncCb | OnDataAppendedAsyncCb;
 //#endregion
-//#region src/config/flowblade-logtape-sqlduck.config.d.ts
-declare const flowbladeLogtapeSqlduckConfig: {
-  categories: string[];
-};
-//#endregion
 //#region src/helpers/duck-memory.d.ts
 declare const duckMemoryTags: readonly ["BASE_TABLE", "HASH_TABLE", "PARQUET_READER", "CSV_READER", "ORDER_BY", "ART_INDEX", "COLUMN_DATA", "METADATA", "OVERFLOW_STRINGS", "IN_MEMORY_TABLE", "ALLOCATOR", "EXTENSION", "TRANSACTION", "EXTERNAL_FILE_CACHE", "WINDOW", "OBJECT_CACHE"];
 type DuckMemoryTag = (typeof duckMemoryTags)[number];
@@ -56,10 +52,7 @@ declare class DuckMemory {
   getSummary: () => Promise<DuckMemorySummary>;
 }
 //#endregion
-//#region src/logger/sqlduck-default-logtape-logger.d.ts
-declare const sqlduckDefaultLogtapeLogger: _logtape_logtape0.Logger;
-//#endregion
-//#region src/table/table.d.ts
+//#region src/objects/table.d.ts
 /**
  * Fully qualified table information
  */
@@ -208,4 +201,145 @@ declare const zodCodecs: {
   readonly bigintToString: z.ZodCodec<z.ZodBigInt, z.ZodString>;
 };
 //#endregion
-export { DuckMemory, type DuckMemoryTag, type OnDataAppendedCb, type OnDataAppendedStats, SqlDuck, type SqlDuckParams, Table, type ToTableParams, flowbladeLogtapeSqlduckConfig, getTableCreateFromZod, sqlduckDefaultLogtapeLogger, zodCodecs };
+//#region src/objects/database.d.ts
+type DatabaseProperties = {
+  alias: string;
+};
+declare class Database {
+  #private;
+  get alias(): string;
+  constructor(params: DatabaseProperties);
+  toJson(): {
+    type: string;
+    params: {
+      alias: string;
+    };
+  };
+  [Symbol.toStringTag](): string;
+}
+//#endregion
+//#region src/manager/database/duck-database-manager.schemas.d.ts
+declare const duckDatabaseManagerDbParamsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  type: z.ZodLiteral<":memory:">;
+  alias: z.ZodString;
+  options: z.ZodOptional<z.ZodObject<{
+    ACCESS_MODE: z.ZodOptional<z.ZodEnum<{
+      READ_ONLY: "READ_ONLY";
+      READ_WRITE: "READ_WRITE";
+      AUTOMATIC: "AUTOMATIC";
+    }>>;
+    COMPRESS: z.ZodOptional<z.ZodEnum<{
+      true: "true";
+      false: "false";
+    }>>;
+    TYPE: z.ZodOptional<z.ZodEnum<{
+      DUCKDB: "DUCKDB";
+      SQLITE: "SQLITE";
+    }>>;
+    BLOCK_SIZE: z.ZodOptional<z.ZodInt32>;
+    ROW_GROUP_SIZE: z.ZodOptional<z.ZodInt32>;
+    STORAGE_VERSION: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_KEY: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_CIPHER: z.ZodOptional<z.ZodEnum<{
+      CBC: "CBC";
+      CTR: "CTR";
+      GCM: "GCM";
+    }>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+  type: z.ZodLiteral<"duckdb">;
+  path: z.ZodString;
+  alias: z.ZodString;
+  options: z.ZodOptional<z.ZodObject<{
+    ACCESS_MODE: z.ZodOptional<z.ZodEnum<{
+      READ_ONLY: "READ_ONLY";
+      READ_WRITE: "READ_WRITE";
+      AUTOMATIC: "AUTOMATIC";
+    }>>;
+    COMPRESS: z.ZodOptional<z.ZodEnum<{
+      true: "true";
+      false: "false";
+    }>>;
+    TYPE: z.ZodOptional<z.ZodEnum<{
+      DUCKDB: "DUCKDB";
+      SQLITE: "SQLITE";
+    }>>;
+    BLOCK_SIZE: z.ZodOptional<z.ZodInt32>;
+    ROW_GROUP_SIZE: z.ZodOptional<z.ZodInt32>;
+    STORAGE_VERSION: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_KEY: z.ZodOptional<z.ZodString>;
+    ENCRYPTION_CIPHER: z.ZodOptional<z.ZodEnum<{
+      CBC: "CBC";
+      CTR: "CTR";
+      GCM: "GCM";
+    }>>;
+  }, z.core.$strict>>;
+}, z.core.$strict>], "type">;
+type DuckDatabaseManagerDbParams = z.infer<typeof duckDatabaseManagerDbParamsSchema>;
+//#endregion
+//#region src/manager/database/commands/duck-database-attach-command.d.ts
+type Behaviour = 'OR REPLACE' | 'IF NOT EXISTS';
+type DuckDatabaseAttachCommandOptions = {
+  behaviour?: Behaviour;
+};
+//#endregion
+//#region src/manager/database/duck-database-manager.d.ts
+declare class DuckDatabaseManager {
+  #private;
+  constructor(conn: DuckDBConnection, params?: {
+    logger?: Logger;
+  });
+  /**
+   * Attach a database to the current connection
+   *
+   * @example
+   * ```typescript
+   * const dbManager = new DuckDatabaseManager(conn);
+   * const database = dbManager.attach({
+   *   type: ':memory:', // can be 'duckdb', 's3'...
+   *   alias: 'mydb',
+   *   options: { COMPRESS: 'true' }
+   * });
+   *
+   * console.log(database.alias); // 'mydb'
+   * ```
+   */
+  attach: (dbParams: DuckDatabaseManagerDbParams, options?: DuckDatabaseAttachCommandOptions) => Promise<Database>;
+  attachOrReplace: (dbParams: DuckDatabaseManagerDbParams) => Promise<Database>;
+  attachIfNotExists: (dbParams: DuckDatabaseManagerDbParams) => Promise<Database>;
+  showDatabases: () => Promise<Record<string, _duckdb_node_api0.JS>[]>;
+  detach: (dbAlias: string) => Promise<boolean>;
+  detachIfExists: (dbAlias: string) => Promise<boolean>;
+  /**
+   * The statistics recomputed by the ANALYZE statement are only used for join order optimization.
+   *
+   * It is therefore recommended to recompute these statistics for improved join orders,
+   * especially after performing large updates (inserts and/or deletes).
+   *
+   * @link https://duckdb.org/docs/stable/sql/statements/analyze
+   */
+  analyze: () => Promise<boolean>;
+  checkpoint: (dbAlias: string) => Promise<boolean>;
+}
+//#endregion
+//#region src/validation/core/duckdb-reserved-keywords.d.ts
+/**
+ * DuckDB reserved keywords that cannot be used as unquoted identifiers.
+ * @see https://duckdb.org/docs/sql/keywords-and-identifiers.html
+ */
+declare const duckdbReservedKeywords: readonly ["ALL", "ANALYSE", "ANALYZE", "AND", "ANY", "ARRAY", "AS", "ASC", "ASYMMETRIC", "BOTH", "CASE", "CAST", "CHECK", "COLLATE", "COLUMN", "CONSTRAINT", "CREATE", "CROSS", "CURRENT_CATALOG", "CURRENT_DATE", "CURRENT_ROLE", "CURRENT_SCHEMA", "CURRENT_TIME", "CURRENT_TIMESTAMP", "CURRENT_USER", "DEFAULT", "DEFERRABLE", "DESC", "DISTINCT", "DO", "ELSE", "END", "EXCEPT", "EXISTS", "EXTRACT", "FALSE", "FETCH", "FOR", "FOREIGN", "FROM", "GRANT", "GROUP", "HAVING", "IF", "ILIKE", "IN", "INITIALLY", "INNER", "INTERSECT", "INTO", "IS", "ISNULL", "JOIN", "LATERAL", "LEADING", "LEFT", "LIKE", "LIMIT", "LOCALTIME", "LOCALTIMESTAMP", "NATURAL", "NOT", "NOTNULL", "NULL", "OFFSET", "ON", "ONLY", "OR", "ORDER", "OUTER", "OVERLAPS", "PLACING", "PRIMARY", "REFERENCES", "RETURNING", "RIGHT", "ROW", "SELECT", "SESSION_USER", "SIMILAR", "SOME", "SYMMETRIC", "TABLE", "THEN", "TO", "TRAILING", "TRUE", "UNION", "UNIQUE", "USING", "VARIADIC", "VERBOSE", "WHEN", "WHERE", "WINDOW", "WITH"];
+type DuckdbReservedKeywords = (typeof duckdbReservedKeywords)[number];
+//#endregion
+//#region src/validation/zod/duckdb-valid-names.schemas.d.ts
+declare const duckTableNameSchema: z.ZodString;
+declare const duckTableAliasSchema: z.ZodString;
+//#endregion
+//#region src/config/flowblade-logtape-sqlduck.config.d.ts
+declare const flowbladeLogtapeSqlduckConfig: {
+  categories: string[];
+};
+//#endregion
+//#region src/logger/sqlduck-default-logtape-logger.d.ts
+declare const sqlduckDefaultLogtapeLogger: _logtape_logtape0.Logger;
+//#endregion
+export { Database, DuckDatabaseManager, type DuckDatabaseManagerDbParams, DuckMemory, type DuckMemoryTag, type DuckdbReservedKeywords, type OnDataAppendedCb, type OnDataAppendedStats, SqlDuck, type SqlDuckParams, Table, type ToTableParams, duckDatabaseManagerDbParamsSchema, duckTableAliasSchema, duckTableNameSchema, duckdbReservedKeywords, flowbladeLogtapeSqlduckConfig, getTableCreateFromZod, sqlduckDefaultLogtapeLogger, zodCodecs };

package/dist/index.mjs

@@ -1,9 +1,8 @@
-import { getLogger } from "@logtape/logtape";
 import { BIGINT, BOOLEAN, DOUBLE, DuckDBDataChunk, DuckDBTimestampValue, FLOAT, HUGEINT, INTEGER, SMALLINT, TIMESTAMP, TINYINT, UBIGINT, UHUGEINT, UINTEGER, USMALLINT, UTINYINT, UUID, VARCHAR } from "@duckdb/node-api";
+import { getLogger } from "@logtape/logtape";
 import * as z from "zod";
-//#region src/config/flowblade-logtape-sqlduck.config.ts
-const flowbladeLogtapeSqlduckConfig = { categories: ["flowblade", "sqlduck"] };
-//#endregion
+import { assertNever } from "@httpx/assert";
+import { isPlainObject } from "@httpx/plain-object";
 //#region src/helpers/duck-exec.ts
 var DuckExec = class {
 	#conn;
@@ -100,9 +99,6 @@ var DuckMemory = class {
 	};
 };
 //#endregion
-//#region src/logger/sqlduck-default-logtape-logger.ts
-const sqlduckDefaultLogtapeLogger = getLogger(flowbladeLogtapeSqlduckConfig.categories);
-//#endregion
 //#region src/appender/data-appender-callback.ts
 const isOnDataAppendedAsyncCb = (v) => {
 	return v.constructor.name === "AsyncFunction";
@@ -124,6 +120,12 @@ const createOnDataAppendedCollector = () => {
 	};
 };
 //#endregion
+//#region src/config/flowblade-logtape-sqlduck.config.ts
+const flowbladeLogtapeSqlduckConfig = { categories: ["flowblade", "sqlduck"] };
+//#endregion
+//#region src/logger/sqlduck-default-logtape-logger.ts
+const sqlduckDefaultLogtapeLogger = getLogger(flowbladeLogtapeSqlduckConfig.categories);
+//#endregion
 //#region src/table/get-duckdb-number-column-type.ts
 const isFloatValue = (value) => {
 	if (!Number.isFinite(value)) return true;
@@ -157,7 +159,7 @@ const createOptions = {
 	CREATE_OR_REPLACE: "CREATE OR REPLACE TABLE",
 	IF_NOT_EXISTS: "CREATE TABLE IF NOT EXISTS"
 };
-const duckDbTypes = [
+const duckDbTypesMap = new Map([
 	["VARCHAR", VARCHAR],
 	["BIGINT", BIGINT],
 	["TIMESTAMP", TIMESTAMP],
@@ -166,8 +168,7 @@ const duckDbTypes = [
 	["INTEGER", INTEGER],
 	["DOUBLE", DOUBLE],
 	["FLOAT", FLOAT]
-];
-const duckDbTypesMap = new Map(duckDbTypes);
+]);
 const getTableCreateFromZod = (params) => {
 	const { table, schema, options } = params;
 	const { create = "CREATE" } = options ?? {};
@@ -303,10 +304,10 @@ async function* rowsToColumnsChunks(params) {
 //#endregion
 //#region src/sql-duck.ts
 var SqlDuck = class {
-	#duck;
+	#conn;
 	#logger;
 	constructor(params) {
-		this.#duck = params.conn;
+		this.#conn = params.conn;
 		this.#logger = params.logger ?? sqlduckDefaultLogtapeLogger;
 	}
 	/**
@@ -351,12 +352,12 @@ var SqlDuck = class {
 		if (!Number.isSafeInteger(chunkSize) || chunkSize < 1 || chunkSize > 2048) throw new Error("chunkSize must be a number between 1 and 2048");
 		const timeStart = Date.now();
 		const { columnTypes, ddl } = await createTableFromZod({
-			conn: this.#duck,
+			conn: this.#conn,
 			schema,
 			table,
 			options: createOptions
 		});
-		const appender = await this.#duck.createAppender(table.tableName, table.schemaName, table.databaseName);
+		const appender = await this.#conn.createAppender(table.tableName, table.schemaName, table.databaseName);
 		const chunkTypes = Array.from(columnTypes.values());
 		let totalRows = 0;
 		const dataAppendedCollector = createOnDataAppendedCollector();
@@ -399,7 +400,39 @@ var SqlDuck = class {
 	};
 };
 //#endregion
-//#region src/table/table.ts
+//#region src/utils/zod-codecs.ts
+const zodCodecs = {
+	dateToString: z.codec(z.date(), z.iso.datetime(), {
+		decode: (date) => date.toISOString(),
+		encode: (isoString) => new Date(isoString)
+	}),
+	bigintToString: z.codec(z.bigint(), z.string().meta({ format: "int64" }), {
+		decode: (bigint) => bigint.toString(),
+		encode: BigInt
+	})
+};
+//#endregion
+//#region src/objects/database.ts
+var Database = class {
+	#params;
+	get alias() {
+		return this.#params.alias;
+	}
+	constructor(params) {
+		this.#params = params;
+	}
+	toJson() {
+		return {
+			type: "database",
+			params: { alias: this.#params.alias }
+		};
+	}
+	[Symbol.toStringTag]() {
+		return this.alias;
+	}
+};
+//#endregion
+//#region src/objects/table.ts
 var Table = class Table {
 	#fqTable;
 	get tableName() {
@@ -441,16 +474,261 @@ var Table = class Table {
 	};
 };
 //#endregion
-//#region src/utils/zod-codecs.ts
-const zodCodecs = {
-	dateToString: z.codec(z.date(), z.iso.datetime(), {
-		decode: (date) => date.toISOString(),
-		encode: (isoString) => new Date(isoString)
-	}),
-	bigintToString: z.codec(z.bigint(), z.string().meta({ format: "int64" }), {
-		decode: (bigint) => bigint.toString(),
-		encode: BigInt
-	})
+//#region src/validation/core/duckdb-reserved-keywords.ts
+/**
+* DuckDB reserved keywords that cannot be used as unquoted identifiers.
+* @see https://duckdb.org/docs/sql/keywords-and-identifiers.html
+*/
+const duckdbReservedKeywords = [
+	"ALL",
+	"ANALYSE",
+	"ANALYZE",
+	"AND",
+	"ANY",
+	"ARRAY",
+	"AS",
+	"ASC",
+	"ASYMMETRIC",
+	"BOTH",
+	"CASE",
+	"CAST",
+	"CHECK",
+	"COLLATE",
+	"COLUMN",
+	"CONSTRAINT",
+	"CREATE",
+	"CROSS",
+	"CURRENT_CATALOG",
+	"CURRENT_DATE",
+	"CURRENT_ROLE",
+	"CURRENT_SCHEMA",
+	"CURRENT_TIME",
+	"CURRENT_TIMESTAMP",
+	"CURRENT_USER",
+	"DEFAULT",
+	"DEFERRABLE",
+	"DESC",
+	"DISTINCT",
+	"DO",
+	"ELSE",
+	"END",
+	"EXCEPT",
+	"EXISTS",
+	"EXTRACT",
+	"FALSE",
+	"FETCH",
+	"FOR",
+	"FOREIGN",
+	"FROM",
+	"GRANT",
+	"GROUP",
+	"HAVING",
+	"IF",
+	"ILIKE",
+	"IN",
+	"INITIALLY",
+	"INNER",
+	"INTERSECT",
+	"INTO",
+	"IS",
+	"ISNULL",
+	"JOIN",
+	"LATERAL",
+	"LEADING",
+	"LEFT",
+	"LIKE",
+	"LIMIT",
+	"LOCALTIME",
+	"LOCALTIMESTAMP",
+	"NATURAL",
+	"NOT",
+	"NOTNULL",
+	"NULL",
+	"OFFSET",
+	"ON",
+	"ONLY",
+	"OR",
+	"ORDER",
+	"OUTER",
+	"OVERLAPS",
+	"PLACING",
+	"PRIMARY",
+	"REFERENCES",
+	"RETURNING",
+	"RIGHT",
+	"ROW",
+	"SELECT",
+	"SESSION_USER",
+	"SIMILAR",
+	"SOME",
+	"SYMMETRIC",
+	"TABLE",
+	"THEN",
+	"TO",
+	"TRAILING",
+	"TRUE",
+	"UNION",
+	"UNIQUE",
+	"USING",
+	"VARIADIC",
+	"VERBOSE",
+	"WHEN",
+	"WHERE",
+	"WINDOW",
+	"WITH"
+];
+//#endregion
+//#region src/validation/zod/duckdb-valid-names.schemas.ts
+const duckdbMaximumObjectNameLength = 120;
+const duckDbObjectNameRegex = /^[a-z_]\w*$/i;
+const duckdbReservedKeywordsSet = new Set(duckdbReservedKeywords.map((k) => k.toUpperCase()));
+const duckTableNameSchema = z.string().min(1).max(duckdbMaximumObjectNameLength).regex(duckDbObjectNameRegex, "Table name must start with a letter or underscore, and contain only letters, numbers and underscores").refine((value) => !duckdbReservedKeywordsSet.has(value.toUpperCase()), { error: `Value is a DuckDB reserved keyword and cannot be used as a table name` });
+const duckTableAliasSchema = duckTableNameSchema;
+//#endregion
+//#region src/manager/database/duck-database-manager.schemas.ts
+const duckdbAttachOptionsSchema = z.strictObject({
+	ACCESS_MODE: z.optional(z.enum([
+		"READ_ONLY",
+		"READ_WRITE",
+		"AUTOMATIC"
+	])),
+	COMPRESS: z.optional(z.enum(["true", "false"])),
+	TYPE: z.optional(z.enum(["DUCKDB", "SQLITE"])),
+	BLOCK_SIZE: z.optional(z.int32().min(16384).max(262144)),
+	ROW_GROUP_SIZE: z.optional(z.int32().positive()),
+	STORAGE_VERSION: z.optional(z.string().startsWith("v").regex(/^v?\d{1,4}\.\d{1,4}\.\d{1,4}$/)),
+	ENCRYPTION_KEY: z.optional(z.string().min(8)),
+	ENCRYPTION_CIPHER: z.optional(z.enum([
+		"CBC",
+		"CTR",
+		"GCM"
+	]))
+});
+const duckDatabaseManagerDbParamsSchema = z.discriminatedUnion("type", [z.strictObject({
+	type: z.literal(":memory:"),
+	alias: duckTableAliasSchema,
+	options: z.optional(duckdbAttachOptionsSchema)
+}), z.strictObject({
+	type: z.literal("duckdb"),
+	path: z.string().min(4).endsWith(".db"),
+	alias: duckTableAliasSchema,
+	options: z.optional(duckdbAttachOptionsSchema)
+})]);
+//#endregion
+//#region src/manager/database/commands/duck-database-attach-command.ts
+var DuckDatabaseAttachCommand = class {
+	options;
+	dbParams;
+	constructor(dbParams, options) {
+		this.dbParams = dbParams;
+		this.options = options ?? {};
+	}
+	getRawSql = () => {
+		const dbParams = this.dbParams;
+		const parts = ["ATTACH", this.options.behaviour].filter(Boolean);
+		const { type, alias } = dbParams;
+		switch (type) {
+			case ":memory:":
+				parts.push("':memory:'");
+				break;
+			case "duckdb":
+				parts.push(`'${dbParams.path}'`);
+				break;
+			default: assertNever(type);
+		}
+		if (alias !== null) parts.push("AS", `${alias}`);
+		const options = isPlainObject(dbParams.options) ? Object.entries(dbParams.options).map(([key, value]) => {
+			return key === "ACCESS_MODE" ? value : `${key} '${value}'`;
+		}) : [];
+		if (options.length > 0) parts.push(`(${options.join(", ")})`);
+		return parts.filter(Boolean).join(" ");
+	};
+};
+//#endregion
+//#region src/manager/database/duck-database-manager.ts
+var DuckDatabaseManager = class {
+	#conn;
+	#logger;
+	constructor(conn, params) {
+		this.#conn = conn;
+		this.#logger = params?.logger ?? sqlduckDefaultLogtapeLogger.with({ source: "DuckDatabaseManager" });
+	}
+	/**
+	* Attach a database to the current connection
+	*
+	* @example
+	* ```typescript
+	* const dbManager = new DuckDatabaseManager(conn);
+	* const database = dbManager.attach({
+	*   type: ':memory:', // can be 'duckdb', 's3'...
+	*   alias: 'mydb',
+	*   options: { COMPRESS: 'true' }
+	* });
+	*
+	* console.log(database.alias); // 'mydb'
+	* ```
+	*/
+	attach = async (dbParams, options) => {
+		const params = z.parse(duckDatabaseManagerDbParamsSchema, dbParams);
+		const rawSql = new DuckDatabaseAttachCommand(params, options).getRawSql();
+		await this.#executeRawSqlCommand(`attach(${params.alias})`, rawSql);
+		return new Database({ alias: params.alias });
+	};
+	attachOrReplace = async (dbParams) => {
+		return this.attach(dbParams, { behaviour: "OR REPLACE" });
+	};
+	attachIfNotExists = async (dbParams) => {
+		return this.attach(dbParams, { behaviour: "IF NOT EXISTS" });
+	};
+	showDatabases = async () => {
+		return await this.#executeRawSqlCommand("showDatabases()", `SHOW DATABASES`);
+	};
+	detach = async (dbAlias) => {
+		const safeAlias = z.parse(duckTableAliasSchema, dbAlias);
+		await this.#executeRawSqlCommand(`detach(${safeAlias})`, `DETACH ${safeAlias}`);
+		return true;
+	};
+	detachIfExists = async (dbAlias) => {
+		const safeAlias = z.parse(duckTableAliasSchema, dbAlias);
+		await this.#executeRawSqlCommand(`detachIfExists(${safeAlias})`, `DETACH IF EXISTS ${safeAlias}`);
+		return true;
+	};
+	/**
+	* The statistics recomputed by the ANALYZE statement are only used for join order optimization.
+	*
+	* It is therefore recommended to recompute these statistics for improved join orders,
+	* especially after performing large updates (inserts and/or deletes).
+	*
+	* @link https://duckdb.org/docs/stable/sql/statements/analyze
+	*/
+	analyze = async () => {
+		await this.#executeRawSqlCommand("analyze()", "ANALYZE");
+		return true;
+	};
+	checkpoint = async (dbAlias) => {
+		const safeAlias = z.parse(duckTableAliasSchema, dbAlias);
+		await this.#executeRawSqlCommand(`checkpoint(${safeAlias})`, `CHECKPOINT ${safeAlias}`);
+		return true;
+	};
+	#executeRawSqlCommand = async (name, rawSql) => {
+		const startTime = Date.now();
+		try {
+			const result = await this.#conn.runAndReadAll(rawSql);
+			const timeMs = Math.round(Date.now() - startTime);
+			const data = result.getRowObjectsJS();
+			this.#logger.info(`DuckDatabaseManager.${name} in ${timeMs}ms`, { timeMs });
+			return data;
+		} catch (e) {
+			const msg = `DuckDatabaseManager: failed to run "${name}" - ${e?.message ?? ""}`;
+			const timeMs = Math.round(Date.now() - startTime);
+			this.#logger.error(msg, {
+				name,
+				sql: rawSql,
+				timeMs
+			});
+			throw new Error(msg, { cause: e });
+		}
+	};
 };
 //#endregion
-export { DuckMemory, SqlDuck, Table, flowbladeLogtapeSqlduckConfig, getTableCreateFromZod, sqlduckDefaultLogtapeLogger, zodCodecs };
+export { Database, DuckDatabaseManager, DuckMemory, SqlDuck, Table, duckDatabaseManagerDbParamsSchema, duckTableAliasSchema, duckTableNameSchema, duckdbReservedKeywords, flowbladeLogtapeSqlduckConfig, getTableCreateFromZod, sqlduckDefaultLogtapeLogger, zodCodecs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowblade/sqlduck",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -57,9 +57,11 @@
     "@flowblade/core": "^0.2.26",
     "@flowblade/source-duckdb": "^0.20.1",
     "@flowblade/sql-tag": "^0.3.2",
-    "@logtape/logtape": "2.0.4",
+    "@httpx/assert": "^0.16.8",
+    "@httpx/plain-object": "^2.1.8",
+    "@logtape/logtape": "^2.0.5",
     "@standard-schema/spec": "^1.1.0",
-    "p-mutex": "^1.0.0",
+    "p-queue": "9.1.0",
     "valibot": "^1.3.1",
     "zod": "^4.3.6"
   },
@@ -82,7 +84,7 @@
     "@types/node": "25.5.0",
     "@typescript-eslint/eslint-plugin": "8.57.2",
     "@typescript-eslint/parser": "8.57.2",
-    "@typescript/native-preview": "7.0.0-dev.20260316.1",
+    "@typescript/native-preview": "7.0.0-dev.20260324.1",
     "@vitest/coverage-v8": "4.1.1",
     "@vitest/ui": "4.1.1",
     "ansis": "4.2.0",
@@ -90,6 +92,7 @@
     "core-js": "3.49.0",
     "cross-env": "10.1.0",
     "es-check": "9.6.3",
+    "es-toolkit": "1.45.1",
     "esbuild": "0.27.4",
     "eslint": "8.57.1",
     "execa": "9.6.1",
@@ -106,11 +109,11 @@
     "tarn": "3.0.2",
     "tedious": "19.2.1",
     "testcontainers": "11.13.0",
-    "tsdown": "0.21.4",
+    "tsdown": "0.21.5",
     "tsx": "4.21.0",
-    "typedoc": "0.28.17",
+    "typedoc": "0.28.18",
     "typedoc-plugin-markdown": "4.11.0",
-    "typescript": "5.9.3",
+    "typescript": "6.0.2",
     "vitest": "4.1.1"
   },
   "files": [