@leonardovida-md/drizzle-neo-duckdb 1.0.0

package/dist/introspect.d.ts

@@ -0,0 +1,53 @@
+import type { RowData } from './client.ts';
+import type { DuckDBDatabase } from './driver.ts';
+export interface IntrospectOptions {
+    schemas?: string[];
+    includeViews?: boolean;
+    useCustomTimeTypes?: boolean;
+    mapJsonAsDuckDbJson?: boolean;
+    importBasePath?: string;
+}
+interface DuckDbIndexRow extends RowData {
+    schema_name: string;
+    table_name: string;
+    index_name: string;
+    is_unique: boolean | null;
+    expressions: string | null;
+}
+export interface IntrospectedColumn {
+    name: string;
+    dataType: string;
+    columnDefault: string | null;
+    nullable: boolean;
+    characterLength: number | null;
+    numericPrecision: number | null;
+    numericScale: number | null;
+}
+export interface IntrospectedConstraint {
+    name: string;
+    type: string;
+    columns: string[];
+    referencedTable?: {
+        name: string;
+        schema: string;
+        columns: string[];
+    };
+    rawExpression?: string | null;
+}
+export interface IntrospectedTable {
+    schema: string;
+    name: string;
+    kind: 'table' | 'view';
+    columns: IntrospectedColumn[];
+    constraints: IntrospectedConstraint[];
+    indexes: DuckDbIndexRow[];
+}
+export interface IntrospectResult {
+    files: {
+        schemaTs: string;
+        metaJson: IntrospectedTable[];
+        relationsTs?: string;
+    };
+}
+export declare function introspect(db: DuckDBDatabase, opts?: IntrospectOptions): Promise<IntrospectResult>;
+export {};

package/dist/migrator.d.ts

@@ -0,0 +1,4 @@
+import type { MigrationConfig } from 'drizzle-orm/migrator';
+import type { DuckDBDatabase } from './driver.ts';
+export type DuckDbMigrationConfig = MigrationConfig | string;
+export declare function migrate<TSchema extends Record<string, unknown>>(db: DuckDBDatabase<TSchema>, config: DuckDbMigrationConfig): Promise<void>;

package/dist/select-builder.d.ts

@@ -0,0 +1,31 @@
+import { PgSelectBuilder, type CreatePgSelectFromBuilderMode, type SelectedFields, type TableLikeHasEmptySelection } from 'drizzle-orm/pg-core/query-builders';
+import { PgColumn, PgTable, type PgSession } from 'drizzle-orm/pg-core';
+import { Subquery, ViewBaseConfig, type SQLWrapper } from 'drizzle-orm';
+import { PgViewBase } from 'drizzle-orm/pg-core/view-base';
+import type { GetSelectTableName, GetSelectTableSelection } from 'drizzle-orm/query-builders/select.types';
+import { SQL, type ColumnsSelection } from 'drizzle-orm/sql/sql';
+import type { DuckDBDialect } from './dialect.ts';
+import { type DrizzleTypeError } from 'drizzle-orm/utils';
+interface PgViewBaseInternal<TName extends string = string, TExisting extends boolean = boolean, TSelectedFields extends ColumnsSelection = ColumnsSelection> extends PgViewBase<TName, TExisting, TSelectedFields> {
+    [ViewBaseConfig]?: {
+        selectedFields: SelectedFields;
+    };
+}
+export declare class DuckDBSelectBuilder<TSelection extends SelectedFields | undefined, TBuilderMode extends 'db' | 'qb' = 'db'> extends PgSelectBuilder<TSelection, TBuilderMode> {
+    private _fields;
+    private _session;
+    private _dialect;
+    private _withList;
+    private _distinct;
+    constructor(config: {
+        fields: TSelection;
+        session: PgSession | undefined;
+        dialect: DuckDBDialect;
+        withList?: Subquery[];
+        distinct?: boolean | {
+            on: (PgColumn | SQLWrapper)[];
+        };
+    });
+    from<TFrom extends PgTable | Subquery | PgViewBaseInternal | SQL>(source: TableLikeHasEmptySelection<TFrom> extends true ? DrizzleTypeError<"Cannot reference a data-modifying statement subquery if it doesn't contain a `returning` clause"> : TFrom): CreatePgSelectFromBuilderMode<TBuilderMode, GetSelectTableName<TFrom>, TSelection extends undefined ? GetSelectTableSelection<TFrom> : TSelection, TSelection extends undefined ? 'single' : 'partial'>;
+}
+export {};

package/dist/session.d.ts

@@ -0,0 +1,62 @@
+import { entityKind } from 'drizzle-orm/entity';
+import type { Logger } from 'drizzle-orm/logger';
+import { PgTransaction } from 'drizzle-orm/pg-core';
+import type { SelectedFieldsOrdered } from 'drizzle-orm/pg-core/query-builders/select.types';
+import type { PgTransactionConfig, PreparedQueryConfig, PgQueryResultHKT } from 'drizzle-orm/pg-core/session';
+import { PgPreparedQuery, PgSession } from 'drizzle-orm/pg-core/session';
+import type { RelationalSchemaConfig, TablesRelationalConfig } from 'drizzle-orm/relations';
+import { type Query, SQL } from 'drizzle-orm/sql/sql';
+import type { Assume } from 'drizzle-orm/utils';
+import type { DuckDBDialect } from './dialect.ts';
+import type { DuckDBClientLike, RowData } from './client.ts';
+export type { DuckDBClientLike, RowData } from './client.ts';
+export declare class DuckDBPreparedQuery<T extends PreparedQueryConfig> extends PgPreparedQuery<T> {
+    private client;
+    private dialect;
+    private queryString;
+    private params;
+    private logger;
+    private fields;
+    private _isResponseInArrayMode;
+    private customResultMapper;
+    private rewriteArrays;
+    private rejectStringArrayLiterals;
+    private warnOnStringArrayLiteral?;
+    static readonly [entityKind]: string;
+    constructor(client: DuckDBClientLike, dialect: DuckDBDialect, queryString: string, params: unknown[], logger: Logger, fields: SelectedFieldsOrdered | undefined, _isResponseInArrayMode: boolean, customResultMapper: ((rows: unknown[][]) => T['execute']) | undefined, rewriteArrays: boolean, rejectStringArrayLiterals: boolean, warnOnStringArrayLiteral?: ((sql: string) => void) | undefined);
+    execute(placeholderValues?: Record<string, unknown> | undefined): Promise<T['execute']>;
+    all(placeholderValues?: Record<string, unknown> | undefined): Promise<T['all']>;
+    isResponseInArrayMode(): boolean;
+}
+export interface DuckDBSessionOptions {
+    logger?: Logger;
+    rewriteArrays?: boolean;
+    rejectStringArrayLiterals?: boolean;
+}
+export declare class DuckDBSession<TFullSchema extends Record<string, unknown> = Record<string, never>, TSchema extends TablesRelationalConfig = Record<string, never>> extends PgSession<DuckDBQueryResultHKT, TFullSchema, TSchema> {
+    private client;
+    private schema;
+    private options;
+    static readonly [entityKind]: string;
+    protected dialect: DuckDBDialect;
+    private logger;
+    private rewriteArrays;
+    private rejectStringArrayLiterals;
+    private hasWarnedArrayLiteral;
+    constructor(client: DuckDBClientLike, dialect: DuckDBDialect, schema: RelationalSchemaConfig<TSchema> | undefined, options?: DuckDBSessionOptions);
+    prepareQuery<T extends PreparedQueryConfig = PreparedQueryConfig>(query: Query, fields: SelectedFieldsOrdered | undefined, name: string | undefined, isResponseInArrayMode: boolean, customResultMapper?: (rows: unknown[][]) => T['execute']): PgPreparedQuery<T>;
+    transaction<T>(transaction: (tx: DuckDBTransaction<TFullSchema, TSchema>) => Promise<T>): Promise<T>;
+    private warnOnStringArrayLiteral;
+}
+export declare class DuckDBTransaction<TFullSchema extends Record<string, unknown>, TSchema extends TablesRelationalConfig> extends PgTransaction<DuckDBQueryResultHKT, TFullSchema, TSchema> {
+    static readonly [entityKind]: string;
+    rollback(): never;
+    getTransactionConfigSQL(config: PgTransactionConfig): SQL;
+    setTransaction(config: PgTransactionConfig): Promise<void>;
+    transaction<T>(transaction: (tx: DuckDBTransaction<TFullSchema, TSchema>) => Promise<T>): Promise<T>;
+}
+export type GenericRowData<T extends RowData = RowData> = T;
+export type GenericTableData<T = RowData> = T[];
+export interface DuckDBQueryResultHKT extends PgQueryResultHKT {
+    type: GenericTableData<Assume<this['row'], RowData>>;
+}

package/dist/sql/query-rewriters.d.ts

@@ -0,0 +1,2 @@
+export declare function adaptArrayOperators(query: string): string;
+export declare function queryAdapter(query: string): string;

package/dist/sql/result-mapper.d.ts

@@ -0,0 +1,2 @@
+import { type AnyColumn, type SelectedFieldsOrdered } from 'drizzle-orm';
+export declare function mapResultRow<TResult>(columns: SelectedFieldsOrdered<AnyColumn>, row: unknown[], joinsNotNullableMap: Record<string, boolean> | undefined): TResult;

package/dist/sql/selection.d.ts

@@ -0,0 +1,2 @@
+import type { SelectedFields } from 'drizzle-orm/pg-core';
+export declare function aliasFields(fields: SelectedFields, fullJoin?: boolean): SelectedFields;

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+export { aliasFields } from './sql/selection.ts';
+export { adaptArrayOperators, queryAdapter } from './sql/query-rewriters.ts';
+export { mapResultRow } from './sql/result-mapper.ts';

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@leonardovida-md/drizzle-neo-duckdb",
+  "module": "./dist/index.mjs",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "version": "1.0.0",
+  "description": "A drizzle ORM client for use with DuckDB. Based on drizzle's Postgres client.",
+  "type": "module",
+  "scripts": {
+    "build": "bun build --target=node ./src/index.ts --outfile=./dist/index.mjs --packages=external && bun build --target=node ./src/bin/duckdb-introspect.ts --outfile=./dist/duckdb-introspect.mjs --packages=external && bun run build:declarations",
+    "build:declarations": "tsc --emitDeclarationOnly --project tsconfig.types.json",
+    "test": "vitest",
+    "t": "vitest --watch --ui"
+  },
+  "bin": {
+    "duckdb-introspect": "dist/duckdb-introspect.mjs"
+  },
+  "peerDependencies": {
+    "@duckdb/node-api": "1.4.2-r.1",
+    "drizzle-orm": "^0.40.0"
+  },
+  "peerDependenciesMeta": {
+    "@duckdb/node-api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@duckdb/node-api": "1.4.2-r.1",
+    "@types/bun": "^1.2.5",
+    "@types/uuid": "^10.0.0",
+    "@vitest/ui": "^1.6.0",
+    "drizzle-orm": "0.40.0",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.2",
+    "uuid": "^10.0.0",
+    "vitest": "^1.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leonardovida-md/drizzle-neo-duckdb.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "packageManager": "bun@1.2.2",
+  "keywords": [
+    "drizzle",
+    "duckdb"
+  ],
+  "author": "M L",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/leonardovida-md/drizzle-neo-duckdb/issues"
+  },
+  "homepage": "https://github.com/leonardovida-md/drizzle-neo-duckdb#readme",
+  "files": [
+    "src/**/*.ts",
+    "dist/*.mjs",
+    "dist/**/*.d.ts"
+  ]
+}

package/src/bin/duckdb-introspect.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { DuckDBInstance } from '@duckdb/node-api';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { drizzle } from '../index.ts';
+import { introspect } from '../introspect.ts';
+
+interface CliOptions {
+  url?: string;
+  schemas?: string[];
+  outFile: string;
+  includeViews: boolean;
+  useCustomTimeTypes: boolean;
+  importBasePath?: string;
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {
+    outFile: path.resolve(process.cwd(), 'drizzle/schema.ts'),
+    includeViews: false,
+    useCustomTimeTypes: true,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    switch (arg) {
+      case '--url':
+        options.url = argv[++i];
+        break;
+      case '--schema':
+      case '--schemas':
+        options.schemas = argv[++i]?.split(',').map((s) => s.trim()).filter(Boolean);
+        break;
+      case '--out':
+      case '--outFile':
+        options.outFile = path.resolve(process.cwd(), argv[++i] ?? 'drizzle/schema.ts');
+        break;
+      case '--include-views':
+      case '--includeViews':
+        options.includeViews = true;
+        break;
+      case '--use-pg-time':
+        options.useCustomTimeTypes = false;
+        break;
+      case '--import-base':
+        options.importBasePath = argv[++i];
+        break;
+      case '--help':
+      case '-h':
+        printHelp();
+        process.exit(0);
+      default:
+        if (arg.startsWith('-')) {
+          console.warn(`Unknown option ${arg}`);
+        }
+    }
+  }
+
+  return options;
+}
+
+function printHelp(): void {
+  console.log(`duckdb-introspect
+
+Usage:
+  bun x duckdb-introspect --url <duckdb path|md:> [--schema my_schema] [--out ./drizzle/schema.ts]
+
+Options:
+  --url            DuckDB database path (e.g. :memory:, ./local.duckdb, md:)
+  --schema         Comma separated schema list (defaults to all non-system schemas)
+  --out            Output file (default: ./drizzle/schema.ts)
+  --include-views  Include views in the generated schema
+  --use-pg-time    Use pg-core timestamp/date/time instead of DuckDB custom helpers
+  --import-base    Override import path for duckdb helpers (default: package name)
+`);
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (!options.url) {
+    printHelp();
+    throw new Error('Missing required --url');
+  }
+
+  const instanceOptions =
+    options.url.startsWith('md:') && process.env.MOTHERDUCK_TOKEN
+      ? { motherduck_token: process.env.MOTHERDUCK_TOKEN }
+      : undefined;
+
+  const instance = await DuckDBInstance.create(options.url, instanceOptions);
+  const connection = await instance.connect();
+  const db = drizzle(connection);
+
+  try {
+    const result = await introspect(db, {
+      schemas: options.schemas,
+      includeViews: options.includeViews,
+      useCustomTimeTypes: options.useCustomTimeTypes,
+      importBasePath: options.importBasePath,
+    });
+
+    await mkdir(path.dirname(options.outFile), { recursive: true });
+    await writeFile(options.outFile, result.files.schemaTs, 'utf8');
+
+    console.log(`Wrote schema to ${options.outFile}`);
+  } finally {
+    if ('closeSync' in connection && typeof connection.closeSync === 'function') {
+      connection.closeSync();
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/src/client.ts

@@ -0,0 +1,110 @@
+import {
+  listValue,
+  type DuckDBConnection,
+  type DuckDBValue,
+} from '@duckdb/node-api';
+
+export type DuckDBClientLike = DuckDBConnection;
+export type RowData = Record<string, unknown>;
+
+export interface PrepareParamsOptions {
+  rejectStringArrayLiterals?: boolean;
+  warnOnStringArrayLiteral?: () => void;
+}
+
+function isPgArrayLiteral(value: string): boolean {
+  return value.startsWith('{') && value.endsWith('}');
+}
+
+function parsePgArrayLiteral(value: string): unknown {
+  const json = value.replace(/{/g, '[').replace(/}/g, ']');
+
+  try {
+    return JSON.parse(json);
+  } catch {
+    return value;
+  }
+}
+
+let warnedArrayLiteral = false;
+
+export function prepareParams(
+  params: unknown[],
+  options: PrepareParamsOptions = {}
+): unknown[] {
+  return params.map((param) => {
+    if (typeof param === 'string' && isPgArrayLiteral(param)) {
+      if (options.rejectStringArrayLiterals) {
+        throw new Error(
+          'Stringified array literals are not supported. Use duckDbList()/duckDbArray() or pass native arrays.'
+        );
+      }
+
+      if (!warnedArrayLiteral && options.warnOnStringArrayLiteral) {
+        warnedArrayLiteral = true;
+        options.warnOnStringArrayLiteral();
+      }
+      return parsePgArrayLiteral(param);
+    }
+    return param;
+  });
+}
+
+function toNodeApiValue(value: unknown): DuckDBValue {
+  if (Array.isArray(value)) {
+    return listValue(value.map((inner) => toNodeApiValue(inner)));
+  }
+  return value as DuckDBValue;
+}
+
+export async function closeClientConnection(
+  connection: DuckDBConnection
+): Promise<void> {
+  if ('close' in connection && typeof connection.close === 'function') {
+    await connection.close();
+    return;
+  }
+
+  if (
+    'closeSync' in connection &&
+    typeof connection.closeSync === 'function'
+  ) {
+    connection.closeSync();
+    return;
+  }
+
+  if (
+    'disconnectSync' in connection &&
+    typeof connection.disconnectSync === 'function'
+  ) {
+    connection.disconnectSync();
+  }
+}
+
+export async function executeOnClient(
+  client: DuckDBClientLike,
+  query: string,
+  params: unknown[]
+): Promise<RowData[]> {
+  const values =
+    params.length > 0
+      ? (params.map((param) => toNodeApiValue(param)) as DuckDBValue[])
+      : undefined;
+  const result = await client.run(query, values);
+  const rows = await result.getRowsJS();
+  const columns = result.columnNames();
+  const seen: Record<string, number> = {};
+  const uniqueColumns = columns.map((col) => {
+    const count = seen[col] ?? 0;
+    seen[col] = count + 1;
+    return count === 0 ? col : `${col}_${count}`;
+  });
+
+  return (rows ?? []).map((vals) => {
+    const obj: Record<string, unknown> = {};
+    uniqueColumns.forEach((col, idx) => {
+      obj[col] = vals[idx];
+    });
+    return obj;
+  }) as RowData[];
+}