@leonardovida-md/drizzle-neo-duckdb 1.0.1 → 1.0.3

package/src/columns.ts

@@ -1,6 +1,18 @@
 import { sql, type SQL } from 'drizzle-orm';
 import type { SQLWrapper } from 'drizzle-orm/sql/sql';
 import { customType } from 'drizzle-orm/pg-core';
+import {
+  wrapList,
+  wrapArray,
+  wrapMap,
+  wrapBlob,
+  wrapJson,
+  type ListValueWrapper,
+  type ArrayValueWrapper,
+  type MapValueWrapper,
+  type BlobValueWrapper,
+  type JsonValueWrapper,
+} from './value-wrappers.ts';
 
 type IntColType =
   | 'SMALLINT'
@@ -93,7 +105,9 @@ function formatLiteral(value: unknown, typeHint?: string): string {
   }
 
   const str =
-    typeof value === 'string' ? value : JSON.stringify(value) ?? String(value);
+    typeof value === 'string'
+      ? value
+      : (JSON.stringify(value) ?? String(value));
 
   const escaped = str.replace(/'/g, "''");
   // Simple quoting based on hint.
@@ -140,7 +154,10 @@ function buildStructLiteral(
   return sql`struct_pack(${sql.join(parts, sql.raw(', '))})`;
 }
 
-function buildMapLiteral(value: Record<string, unknown>, valueType?: string): SQL {
+function buildMapLiteral(
+  value: Record<string, unknown>,
+  valueType?: string
+): SQL {
   const keys = Object.keys(value);
   const vals = Object.values(value);
   const keyList = buildListLiteral(keys, 'TEXT');
@@ -155,14 +172,17 @@ export const duckDbList = <TData = unknown>(
   name: string,
   elementType: AnyColType
 ) =>
-  customType<{ data: TData[]; driverData: SQL | unknown[] | string }>({
+  customType<{
+    data: TData[];
+    driverData: ListValueWrapper | unknown[] | string;
+  }>({
     dataType() {
       return `${elementType}[]`;
     },
-    toDriver(value: TData[]) {
-      return buildListLiteral(value, elementType);
+    toDriver(value: TData[]): ListValueWrapper {
+      return wrapList(value, elementType);
     },
-    fromDriver(value: unknown[] | string | SQL): TData[] {
+    fromDriver(value: unknown[] | string | ListValueWrapper): TData[] {
       if (Array.isArray(value)) {
         return value as TData[];
       }
@@ -181,16 +201,19 @@ export const duckDbArray = <TData = unknown>(
   elementType: AnyColType,
   fixedLength?: number
 ) =>
-  customType<{ data: TData[]; driverData: SQL | unknown[] | string }>({
+  customType<{
+    data: TData[];
+    driverData: ArrayValueWrapper | unknown[] | string;
+  }>({
     dataType() {
       return fixedLength
         ? `${elementType}[${fixedLength}]`
         : `${elementType}[]`;
     },
-    toDriver(value: TData[]) {
-      return buildListLiteral(value, elementType);
+    toDriver(value: TData[]): ArrayValueWrapper {
+      return wrapArray(value, elementType, fixedLength);
     },
-    fromDriver(value: unknown[] | string | SQL): TData[] {
+    fromDriver(value: unknown[] | string | ArrayValueWrapper): TData[] {
       if (Array.isArray(value)) {
         return value as TData[];
       }
@@ -208,15 +231,15 @@ export const duckDbMap = <TData extends Record<string, any>>(
   name: string,
   valueType: AnyColType | ListColType | ArrayColType
 ) =>
-  customType<{ data: TData; driverData: TData }>({
-  dataType() {
+  customType<{ data: TData; driverData: MapValueWrapper | TData }>({
+    dataType() {
       return `MAP (STRING, ${valueType})`;
     },
-    toDriver(value: TData) {
-      return buildMapLiteral(value, valueType);
+    toDriver(value: TData): MapValueWrapper {
+      return wrapMap(value, valueType);
     },
-    fromDriver(value: TData): TData {
-      return value;
+    fromDriver(value: TData | MapValueWrapper): TData {
+      return value as TData;
     },
   })(name);
 
@@ -233,6 +256,8 @@ export const duckDbStruct = <TData extends Record<string, any>>(
       return `STRUCT (${fields.join(', ')})`;
     },
     toDriver(value: TData) {
+      // Use SQL literals for structs due to DuckDB type inference issues
+      // with nested empty lists
       return buildStructLiteral(value, schema);
     },
     fromDriver(value: TData | string): TData {
@@ -247,15 +272,24 @@ export const duckDbStruct = <TData extends Record<string, any>>(
     },
   })(name);
 
+/**
+ * JSON column type that wraps values and delays JSON.stringify() to binding time.
+ * This ensures consistent handling with other wrapped types.
+ *
+ * Note: DuckDB stores JSON as VARCHAR internally, so the final binding
+ * is always a stringified JSON value.
+ */
 export const duckDbJson = <TData = unknown>(name: string) =>
-  customType<{ data: TData; driverData: SQL | string }>({
+  customType<{ data: TData; driverData: JsonValueWrapper | SQL | string }>({
     dataType() {
       return 'JSON';
     },
-    toDriver(value: TData) {
+    toDriver(value: TData): JsonValueWrapper | SQL | string {
+      // Pass through strings directly
       if (typeof value === 'string') {
         return value;
       }
+      // Pass through SQL objects (for raw SQL expressions)
       if (
         value !== null &&
         typeof value === 'object' &&
@@ -263,9 +297,10 @@ export const duckDbJson = <TData = unknown>(name: string) =>
       ) {
         return value as unknown as SQL;
       }
-      return JSON.stringify(value ?? null);
+      // Wrap non-string values for delayed stringify at binding time
+      return wrapJson(value);
     },
-    fromDriver(value: SQL | string) {
+    fromDriver(value: SQL | string | JsonValueWrapper) {
       if (typeof value !== 'string') {
         return value as unknown as TData;
       }
@@ -283,14 +318,14 @@ export const duckDbJson = <TData = unknown>(name: string) =>
 
 export const duckDbBlob = customType<{
   data: Buffer;
+  driverData: BlobValueWrapper;
   default: false;
 }>({
   dataType() {
     return 'BLOB';
   },
-  toDriver(value: Buffer) {
-    const hexString = value.toString('hex');
-    return sql`from_hex(${hexString})`;
+  toDriver(value: Buffer): BlobValueWrapper {
+    return wrapBlob(value);
   },
 });
 
@@ -322,10 +357,7 @@ interface TimestampOptions {
   precision?: number;
 }
 
-export const duckDbTimestamp = (
-  name: string,
-  options: TimestampOptions = {}
-) =>
+export const duckDbTimestamp = (name: string, options: TimestampOptions = {}) =>
   customType<{
     data: Date | string;
     driverData: SQL | string | Date;
@@ -338,6 +370,7 @@ export const duckDbTimestamp = (
       return `TIMESTAMP${precision}`;
     },
     toDriver(value: Date | string) {
+      // Use SQL literals for timestamps due to Bun/DuckDB bigint binding issues
       const iso = value instanceof Date ? value.toISOString() : value;
       const normalized = iso.replace('T', ' ').replace('Z', '+00');
       const typeKeyword = options.withTimezone ? 'TIMESTAMPTZ' : 'TIMESTAMP';
@@ -353,11 +386,9 @@ export const duckDbTimestamp = (
       if (value instanceof Date) {
         return value;
       }
-      const stringValue =
-        typeof value === 'string' ? value : value.toString();
+      const stringValue = typeof value === 'string' ? value : value.toString();
       const hasOffset =
-        stringValue.endsWith('Z') ||
-        /[+-]\d{2}:?\d{2}$/.test(stringValue);
+        stringValue.endsWith('Z') || /[+-]\d{2}:?\d{2}$/.test(stringValue);
       const normalized = hasOffset
         ? stringValue.replace(' ', 'T')
         : `${stringValue.replace(' ', 'T')}Z`;
@@ -374,11 +405,9 @@ export const duckDbDate = (name: string) =>
       return value;
     },
     fromDriver(value: string | Date) {
-        const str =
-          value instanceof Date
-            ? value.toISOString().slice(0, 10)
-            : value;
-        return str;
+      const str =
+        value instanceof Date ? value.toISOString().slice(0, 10) : value;
+      return str;
     },
   })(name);
 

package/src/dialect.ts

@@ -52,8 +52,8 @@ export class DuckDBDialect extends PgDialect {
 
     const migrationTableCreate = sql`
       CREATE TABLE IF NOT EXISTS ${sql.identifier(migrationsSchema)}.${sql.identifier(
-      migrationsTable
-    )} (
+        migrationsTable
+      )} (
         id integer PRIMARY KEY default nextval('${sql.raw(sequenceLiteral)}'),
         hash text NOT NULL,
         created_at bigint

package/src/driver.ts

@@ -12,6 +12,7 @@ import {
   type TablesRelationalConfig,
 } from 'drizzle-orm/relations';
 import { type DrizzleConfig } from 'drizzle-orm/utils';
+import type { SQL } from 'drizzle-orm/sql/sql';
 import type {
   DuckDBClientLike,
   DuckDBQueryResultHKT,
@@ -21,6 +22,7 @@ import { DuckDBSession } from './session.ts';
 import { DuckDBDialect } from './dialect.ts';
 import { DuckDBSelectBuilder } from './select-builder.ts';
 import { aliasFields } from './sql/selection.ts';
+import type { ExecuteInBatchesOptions, RowData } from './client.ts';
 
 export interface PgDriverOptions {
   logger?: Logger;
@@ -49,14 +51,14 @@ export class DuckDBDriver {
 }
 
 export interface DuckDBDrizzleConfig<
-  TSchema extends Record<string, unknown> = Record<string, never>
+  TSchema extends Record<string, unknown> = Record<string, never>,
 > extends DrizzleConfig<TSchema> {
   rewriteArrays?: boolean;
   rejectStringArrayLiterals?: boolean;
 }
 
 export function drizzle<
-  TSchema extends Record<string, unknown> = Record<string, never>
+  TSchema extends Record<string, unknown> = Record<string, never>,
 >(
   client: DuckDBClientLike,
   config: DuckDBDrizzleConfig<TSchema> = {}
@@ -95,7 +97,8 @@ export function drizzle<
 
 export class DuckDBDatabase<
   TFullSchema extends Record<string, unknown> = Record<string, never>,
-  TSchema extends TablesRelationalConfig = ExtractTablesWithRelations<TFullSchema>
+  TSchema extends
+    TablesRelationalConfig = ExtractTablesWithRelations<TFullSchema>,
 > extends PgDatabase<DuckDBQueryResultHKT, TFullSchema, TSchema> {
   static readonly [entityKind]: string = 'DuckDBDatabase';
 
@@ -111,9 +114,9 @@ export class DuckDBDatabase<
   select<TSelection extends SelectedFields>(
     fields: TSelection
   ): DuckDBSelectBuilder<TSelection>;
-  select(fields?: SelectedFields): DuckDBSelectBuilder<
-    SelectedFields | undefined
-  > {
+  select(
+    fields?: SelectedFields
+  ): DuckDBSelectBuilder<SelectedFields | undefined> {
     const selectedFields = fields ? aliasFields(fields) : undefined;
 
     return new DuckDBSelectBuilder({
@@ -123,6 +126,17 @@ export class DuckDBDatabase<
     });
   }
 
+  executeBatches<T extends RowData = RowData>(
+    query: SQL,
+    options: ExecuteInBatchesOptions = {}
+  ): AsyncGenerator<T[], void, void> {
+    return this.session.executeBatches<T>(query, options);
+  }
+
+  executeArrow(query: SQL): Promise<unknown> {
+    return this.session.executeArrow(query);
+  }
+
   override async transaction<T>(
     transaction: (tx: DuckDBTransaction<TFullSchema, TSchema>) => Promise<T>
   ): Promise<T> {

package/src/index.ts

@@ -3,3 +3,6 @@ export * from './session.ts';
 export * from './columns.ts';
 export * from './migrator.ts';
 export * from './introspect.ts';
+export * from './client.ts';
+export * from './olap.ts';
+export * from './value-wrappers.ts';

package/src/introspect.ts

@@ -5,6 +5,18 @@ import type { DuckDBDatabase } from './driver.ts';
 const SYSTEM_SCHEMAS = new Set(['information_schema', 'pg_catalog']);
 
 export interface IntrospectOptions {
+  /**
+   * Database/catalog to introspect. If not specified, uses the current database
+   * (via `SELECT current_database()`). This prevents returning tables from all
+   * attached databases in MotherDuck workspaces.
+   */
+  database?: string;
+  /**
+   * When true, introspects all attached databases instead of just the current one.
+   * Ignored if `database` is explicitly set.
+   * @default false
+   */
+  allDatabases?: boolean;
   schemas?: string[];
   includeViews?: boolean;
   useCustomTimeTypes?: boolean;
@@ -102,13 +114,14 @@ export async function introspect(
   db: DuckDBDatabase,
   opts: IntrospectOptions = {}
 ): Promise<IntrospectResult> {
-  const schemas = await resolveSchemas(db, opts.schemas);
+  const database = await resolveDatabase(db, opts.database, opts.allDatabases);
+  const schemas = await resolveSchemas(db, database, opts.schemas);
   const includeViews = opts.includeViews ?? false;
 
-  const tables = await loadTables(db, schemas, includeViews);
-  const columns = await loadColumns(db, schemas);
-  const constraints = await loadConstraints(db, schemas);
-  const indexes = await loadIndexes(db, schemas);
+  const tables = await loadTables(db, database, schemas, includeViews);
+  const columns = await loadColumns(db, database, schemas);
+  const constraints = await loadConstraints(db, database, schemas);
+  const indexes = await loadIndexes(db, database, schemas);
 
   const grouped = buildTables(tables, columns, constraints, indexes);
 
@@ -126,16 +139,39 @@ export async function introspect(
   };
 }
 
+async function resolveDatabase(
+  db: DuckDBDatabase,
+  targetDatabase?: string,
+  allDatabases?: boolean
+): Promise<string | null> {
+  if (allDatabases) {
+    return null;
+  }
+  if (targetDatabase) {
+    return targetDatabase;
+  }
+
+  const rows = await db.execute<{ current_database: string }>(
+    sql`SELECT current_database() as current_database`
+  );
+  return rows[0]?.current_database ?? null;
+}
+
 async function resolveSchemas(
   db: DuckDBDatabase,
+  database: string | null,
   targetSchemas?: string[]
 ): Promise<string[]> {
   if (targetSchemas?.length) {
     return targetSchemas;
   }
 
+  const databaseFilter = database
+    ? sql`catalog_name = ${database}`
+    : sql`1 = 1`;
+
   const rows = await db.execute<{ schema_name: string }>(
-    sql`select schema_name from information_schema.schemata`
+    sql`SELECT schema_name FROM information_schema.schemata WHERE ${databaseFilter}`
   );
 
   return rows
@@ -145,30 +181,40 @@ async function resolveSchemas(
 
 async function loadTables(
   db: DuckDBDatabase,
+  database: string | null,
   schemas: string[],
   includeViews: boolean
 ): Promise<DuckDbTableRow[]> {
   const schemaFragments = schemas.map((schema) => sql`${schema}`);
+  const databaseFilter = database
+    ? sql`table_catalog = ${database}`
+    : sql`1 = 1`;
 
   return await db.execute<DuckDbTableRow>(
     sql`
-      select table_schema as schema_name, table_name, table_type
-      from information_schema.tables
-      where table_schema in (${sql.join(schemaFragments, sql.raw(', '))})
-      and ${includeViews ? sql`1 = 1` : sql`table_type = 'BASE TABLE'`}
-      order by table_schema, table_name
+      SELECT table_schema as schema_name, table_name, table_type
+      FROM information_schema.tables
+      WHERE ${databaseFilter}
+      AND table_schema IN (${sql.join(schemaFragments, sql.raw(', '))})
+      AND ${includeViews ? sql`1 = 1` : sql`table_type = 'BASE TABLE'`}
+      ORDER BY table_schema, table_name
     `
   );
 }
 
 async function loadColumns(
   db: DuckDBDatabase,
+  database: string | null,
   schemas: string[]
 ): Promise<DuckDbColumnRow[]> {
   const schemaFragments = schemas.map((schema) => sql`${schema}`);
+  const databaseFilter = database
+    ? sql`database_name = ${database}`
+    : sql`1 = 1`;
+
   return await db.execute<DuckDbColumnRow>(
     sql`
-      select
+      SELECT
         schema_name,
         table_name,
         column_name,
@@ -180,21 +226,27 @@ async function loadColumns(
         numeric_precision,
         numeric_scale,
         internal
-      from duckdb_columns()
-      where schema_name in (${sql.join(schemaFragments, sql.raw(', '))})
-      order by schema_name, table_name, column_index
+      FROM duckdb_columns()
+      WHERE ${databaseFilter}
+      AND schema_name IN (${sql.join(schemaFragments, sql.raw(', '))})
+      ORDER BY schema_name, table_name, column_index
     `
   );
 }
 
 async function loadConstraints(
   db: DuckDBDatabase,
+  database: string | null,
   schemas: string[]
 ): Promise<DuckDbConstraintRow[]> {
   const schemaFragments = schemas.map((schema) => sql`${schema}`);
+  const databaseFilter = database
+    ? sql`database_name = ${database}`
+    : sql`1 = 1`;
+
   return await db.execute<DuckDbConstraintRow>(
     sql`
-      select
+      SELECT
         schema_name,
         table_name,
         constraint_name,
@@ -203,29 +255,36 @@ async function loadConstraints(
         constraint_column_names,
         referenced_table,
         referenced_column_names
-      from duckdb_constraints()
-      where schema_name in (${sql.join(schemaFragments, sql.raw(', '))})
-      order by schema_name, table_name, constraint_index
+      FROM duckdb_constraints()
+      WHERE ${databaseFilter}
+      AND schema_name IN (${sql.join(schemaFragments, sql.raw(', '))})
+      ORDER BY schema_name, table_name, constraint_index
     `
   );
 }
 
 async function loadIndexes(
   db: DuckDBDatabase,
+  database: string | null,
   schemas: string[]
 ): Promise<DuckDbIndexRow[]> {
   const schemaFragments = schemas.map((schema) => sql`${schema}`);
+  const databaseFilter = database
+    ? sql`database_name = ${database}`
+    : sql`1 = 1`;
+
   return await db.execute<DuckDbIndexRow>(
     sql`
-      select
+      SELECT
         schema_name,
         table_name,
         index_name,
         is_unique,
         expressions
-      from duckdb_indexes()
-      where schema_name in (${sql.join(schemaFragments, sql.raw(', '))})
-      order by schema_name, table_name, index_name
+      FROM duckdb_indexes()
+      WHERE ${databaseFilter}
+      AND schema_name IN (${sql.join(schemaFragments, sql.raw(', '))})
+      ORDER BY schema_name, table_name, index_name
     `
   );
 }
@@ -407,17 +466,17 @@ function emitConstraints(
           .map((col) => `t.${toIdentifier(col)}`)
           .join(', ')}], name: ${JSON.stringify(constraint.name)} })`
       );
-    } else if (
-      constraint.type === 'UNIQUE' &&
-      constraint.columns.length > 1
-    ) {
+    } else if (constraint.type === 'UNIQUE' && constraint.columns.length > 1) {
       imports.pgCore.add('unique');
       entries.push(
         `${key}: unique(${JSON.stringify(constraint.name)}).on(${constraint.columns
           .map((col) => `t.${toIdentifier(col)}`)
           .join(', ')})`
       );
-    } else if (constraint.type === 'FOREIGN KEY' && constraint.referencedTable) {
+    } else if (
+      constraint.type === 'FOREIGN KEY' &&
+      constraint.referencedTable
+    ) {
       imports.pgCore.add('foreignKey');
       const targetTable = toIdentifier(constraint.referencedTable.name);
       entries.push(
@@ -487,7 +546,10 @@ function buildDefault(defaultValue: string | null): string {
   if (/^nextval\(/i.test(trimmed)) {
     return `.default(sql\`${trimmed}\`)`;
   }
-  if (/^current_timestamp(?:\(\))?$/i.test(trimmed) || /^now\(\)$/i.test(trimmed)) {
+  if (
+    /^current_timestamp(?:\(\))?$/i.test(trimmed) ||
+    /^now\(\)$/i.test(trimmed)
+  ) {
     return `.defaultNow()`;
   }
   if (trimmed === 'true' || trimmed === 'false') {
@@ -545,7 +607,11 @@ function mapDuckDbType(
 
   if (upper === 'BIGINT' || upper === 'INT8' || upper === 'UBIGINT') {
     imports.pgCore.add('bigint');
-    return { builder: `bigint(${columnName(column.name)})` };
+    // Drizzle's bigint helper requires an explicit mode. Default to 'number'
+    // to mirror DuckDB's typical 64-bit integer behavior in JS.
+    return {
+      builder: `bigint(${columnName(column.name)}, { mode: 'number' })`,
+    };
   }
 
   const decimalMatch = /^DECIMAL\((\d+),(\d+)\)/i.exec(upper);
@@ -835,9 +901,7 @@ function renderImports(imports: ImportBuckets, importBasePath: string): string {
   const pgCore = [...imports.pgCore];
   if (pgCore.length) {
     lines.push(
-      `import { ${pgCore
-        .sort()
-        .join(', ')} } from 'drizzle-orm/pg-core';`
+      `import { ${pgCore.sort().join(', ')} } from 'drizzle-orm/pg-core';`
     );
   }
 

package/src/migrator.ts

@@ -10,9 +10,7 @@ export async function migrate<TSchema extends Record<string, unknown>>(
   config: DuckDbMigrationConfig
 ) {
   const migrationConfig: MigrationConfig =
-    typeof config === 'string'
-      ? { migrationsFolder: config }
-      : config;
+    typeof config === 'string' ? { migrationsFolder: config } : config;
 
   const migrations = readMigrationFiles(migrationConfig);