@leonardovida-md/drizzle-neo-duckdb 1.0.2 → 1.1.0

package/README.md

@@ -7,7 +7,7 @@
 [![npm version](https://img.shields.io/npm/v/@leonardovida-md/drizzle-neo-duckdb)](https://www.npmjs.com/package/@leonardovida-md/drizzle-neo-duckdb)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-[Documentation](./docs) • [Examples](./example) • [Contributing](#contributing)
+[Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/) • [LLM Context](https://leonardovida.github.io/drizzle-neo-duckdb/llms.txt) • [Examples](./example) • [Contributing](#contributing)
 
 </div>
 
@@ -19,6 +19,8 @@ Works with local DuckDB files, in-memory databases, and [MotherDuck](https://mot
 
 > **Status:** Experimental. Core query building, migrations, and type inference work well. Some DuckDB-specific types and edge cases are still being refined.
 
+Docs tip: every docs page has a **Markdown (raw)** button for LLM-friendly source.
+
 ## Installation
 
 ```bash
@@ -119,7 +121,14 @@ Drizzle DuckDB uses `drizzle-orm/pg-core` for schema definitions since DuckDB's
 
 ```typescript
 import { sql } from 'drizzle-orm';
-import { integer, text, boolean, timestamp, pgTable, pgSchema } from 'drizzle-orm/pg-core';
+import {
+  integer,
+  text,
+  boolean,
+  timestamp,
+  pgTable,
+  pgSchema,
+} from 'drizzle-orm/pg-core';
 
 // Tables in default schema
 const posts = pgTable('posts', {
@@ -181,7 +190,20 @@ const products = pgTable('products', {
 });
 ```
 
-See [Column Types Documentation](./docs/columns.md) for complete reference.
+See [Column Types Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/api/columns) for complete reference.
+
+### Client-Safe Imports (schemas, drizzle-zod, trpc)
+
+When generated schemas are consumed in client bundles, import the helpers from the browser-safe subpath to avoid pulling the native DuckDB bindings:
+
+```typescript
+import {
+  duckDbJson,
+  duckDbList,
+} from '@leonardovida-md/drizzle-neo-duckdb/helpers';
+```
+
+The introspection CLI now emits this import path by default. You can still override `importBasePath` if you need the old root import.
 
 ## Querying
 
@@ -189,10 +211,15 @@ All standard Drizzle query methods work:
 
 ```typescript
 // Select
-const users = await db.select().from(usersTable).where(eq(usersTable.active, true));
+const users = await db
+  .select()
+  .from(usersTable)
+  .where(eq(usersTable.active, true));
 
 // Insert
-await db.insert(usersTable).values({ name: 'Alice', email: 'alice@example.com' });
+await db
+  .insert(usersTable)
+  .values({ name: 'Alice', email: 'alice@example.com' });
 
 // Insert with returning
 const inserted = await db
@@ -201,7 +228,10 @@ const inserted = await db
   .returning({ id: usersTable.id });
 
 // Update
-await db.update(usersTable).set({ name: 'Updated' }).where(eq(usersTable.id, 1));
+await db
+  .update(usersTable)
+  .set({ name: 'Updated' })
+  .where(eq(usersTable.id, 1));
 
 // Delete
 await db.delete(usersTable).where(eq(usersTable.id, 1));
@@ -228,7 +258,9 @@ const results = await db
 const results = await db
   .select()
   .from(products)
-  .where(duckDbArrayContained(products.tags, ['electronics', 'sale', 'featured']));
+  .where(
+    duckDbArrayContained(products.tags, ['electronics', 'sale', 'featured'])
+  );
 
 // Check if arrays overlap
 const results = await db
@@ -258,7 +290,7 @@ import { migrate } from '@leonardovida-md/drizzle-neo-duckdb';
 await migrate(db, { migrationsFolder: './drizzle' });
 ```
 
-Migration metadata is stored in `drizzle.__drizzle_migrations` by default. See [Migrations Documentation](./docs/migrations.md) for configuration options.
+Migration metadata is stored in `drizzle.__drizzle_migrations` by default. See [Migrations Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/guide/migrations) for configuration options.
 
 ## Schema Introspection
 
@@ -283,7 +315,7 @@ const result = await introspect(db, {
 console.log(result.files.schemaTs);
 ```
 
-See [Introspection Documentation](./docs/introspection.md) for all options.
+See [Introspection Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/guide/introspection) for all options.
 
 ## Configuration Options
 
@@ -307,22 +339,23 @@ const db = drizzle(connection, {
 
 This connector aims for compatibility with Drizzle's Postgres driver but has some differences:
 
-| Feature | Status |
-|---------|--------|
-| Basic CRUD operations | Full support |
-| Joins and subqueries | Full support |
-| Transactions | No savepoints (nested transactions reuse outer) |
-| JSON/JSONB columns | Use `duckDbJson()` instead |
-| Prepared statements | No statement caching |
-| Streaming results | Results are materialized |
+| Feature               | Status                                                     |
+| --------------------- | ---------------------------------------------------------- |
+| Basic CRUD operations | Full support                                               |
+| Joins and subqueries  | Full support                                               |
+| Transactions          | No savepoints (nested transactions reuse outer)            |
+| JSON/JSONB columns    | Use `duckDbJson()` instead                                 |
+| Prepared statements   | No statement caching                                       |
+| Streaming results     | Materialized by default; use `executeBatches()` for chunks |
 
-See [Limitations Documentation](./docs/limitations.md) for details.
+See [Limitations Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/guide/limitations) for details.
 
 ## Examples
 
 - **[MotherDuck NYC Taxi](./example/motherduck-nyc.ts)** — Query the built-in NYC taxi dataset from MotherDuck cloud
 
 Run examples:
+
 ```bash
 MOTHERDUCK_TOKEN=your_token bun example/motherduck-nyc.ts
 ```

package/dist/client.d.ts

@@ -1,6 +1,12 @@
 import { type DuckDBConnection } from '@duckdb/node-api';
-export type DuckDBClientLike = DuckDBConnection;
+export type DuckDBClientLike = DuckDBConnection | DuckDBConnectionPool;
 export type RowData = Record<string, unknown>;
+export interface DuckDBConnectionPool {
+    acquire(): Promise<DuckDBConnection>;
+    release(connection: DuckDBConnection): void | Promise<void>;
+    close?(): Promise<void> | void;
+}
+export declare function isPool(client: DuckDBClientLike): client is DuckDBConnectionPool;
 export interface PrepareParamsOptions {
     rejectStringArrayLiterals?: boolean;
     warnOnStringArrayLiteral?: () => void;
@@ -8,3 +14,15 @@ export interface PrepareParamsOptions {
 export declare function prepareParams(params: unknown[], options?: PrepareParamsOptions): unknown[];
 export declare function closeClientConnection(connection: DuckDBConnection): Promise<void>;
 export declare function executeOnClient(client: DuckDBClientLike, query: string, params: unknown[]): Promise<RowData[]>;
+export interface ExecuteInBatchesOptions {
+    rowsPerChunk?: number;
+}
+/**
+ * Stream results from DuckDB in batches to avoid fully materializing rows in JS.
+ */
+export declare function executeInBatches(client: DuckDBClientLike, query: string, params: unknown[], options?: ExecuteInBatchesOptions): AsyncGenerator<RowData[], void, void>;
+/**
+ * Return columnar results when the underlying node-api exposes an Arrow/columnar API.
+ * Falls back to column-major JS arrays when Arrow is unavailable.
+ */
+export declare function executeArrowOnClient(client: DuckDBClientLike, query: string, params: unknown[]): Promise<unknown>;

package/dist/columns.d.ts

@@ -1,5 +1,6 @@
 import { type SQL } from 'drizzle-orm';
 import type { SQLWrapper } from 'drizzle-orm/sql/sql';
+import { type ListValueWrapper, type ArrayValueWrapper, type MapValueWrapper, type BlobValueWrapper, type JsonValueWrapper } from './value-wrappers-core.ts';
 type IntColType = 'SMALLINT' | 'INTEGER' | 'BIGINT' | 'HUGEINT' | 'USMALLINT' | 'UINTEGER' | 'UBIGINT' | 'UHUGEINT' | 'INT' | 'INT16' | 'INT32' | 'INT64' | 'INT128' | 'LONG' | 'VARINT';
 type FloatColType = 'FLOAT' | 'DOUBLE';
 type StringColType = 'STRING' | 'VARCHAR' | 'TEXT';
@@ -16,7 +17,7 @@ export declare const duckDbList: <TData = unknown>(name: string, elementType: An
     dataType: "custom";
     columnType: "PgCustomColumn";
     data: TData[];
-    driverParam: string | unknown[] | SQL<unknown>;
+    driverParam: string | ListValueWrapper | unknown[];
     enumValues: undefined;
 }>;
 export declare const duckDbArray: <TData = unknown>(name: string, elementType: AnyColType, fixedLength?: number) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
@@ -24,7 +25,7 @@ export declare const duckDbArray: <TData = unknown>(name: string, elementType: A
     dataType: "custom";
     columnType: "PgCustomColumn";
     data: TData[];
-    driverParam: string | unknown[] | SQL<unknown>;
+    driverParam: string | unknown[] | ArrayValueWrapper;
     enumValues: undefined;
 }>;
 export declare const duckDbMap: <TData extends Record<string, any>>(name: string, valueType: AnyColType | ListColType | ArrayColType) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
@@ -32,7 +33,7 @@ export declare const duckDbMap: <TData extends Record<string, any>>(name: string
     dataType: "custom";
     columnType: "PgCustomColumn";
     data: TData;
-    driverParam: TData;
+    driverParam: MapValueWrapper | TData;
     enumValues: undefined;
 }>;
 export declare const duckDbStruct: <TData extends Record<string, any>>(name: string, schema: Record<string, Primitive>) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
@@ -43,12 +44,19 @@ export declare const duckDbStruct: <TData extends Record<string, any>>(name: str
     driverParam: TData;
     enumValues: undefined;
 }>;
+/**
+ * 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 declare const duckDbJson: <TData = unknown>(name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
     name: string;
     dataType: "custom";
     columnType: "PgCustomColumn";
     data: TData;
-    driverParam: string | SQL<unknown>;
+    driverParam: string | JsonValueWrapper | SQL<unknown>;
     enumValues: undefined;
 }>;
 export declare const duckDbBlob: {
@@ -56,24 +64,24 @@ export declare const duckDbBlob: {
         name: "";
         dataType: "custom";
         columnType: "PgCustomColumn";
-        data: Buffer;
-        driverParam: unknown;
+        data: Buffer<ArrayBufferLike>;
+        driverParam: BlobValueWrapper;
         enumValues: undefined;
     }>;
     <TConfig extends Record<string, any>>(fieldConfig?: TConfig | undefined): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
         name: "";
         dataType: "custom";
         columnType: "PgCustomColumn";
-        data: Buffer;
-        driverParam: unknown;
+        data: Buffer<ArrayBufferLike>;
+        driverParam: BlobValueWrapper;
         enumValues: undefined;
     }>;
     <TName extends string>(dbName: TName, fieldConfig?: unknown): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
         name: TName;
         dataType: "custom";
         columnType: "PgCustomColumn";
-        data: Buffer;
-        driverParam: unknown;
+        data: Buffer<ArrayBufferLike>;
+        driverParam: BlobValueWrapper;
         enumValues: undefined;
     }>;
 };

package/dist/driver.d.ts

@@ -1,13 +1,17 @@
+import { DuckDBInstance } from '@duckdb/node-api';
 import { entityKind } from 'drizzle-orm/entity';
 import type { Logger } from 'drizzle-orm/logger';
 import { PgDatabase } from 'drizzle-orm/pg-core/db';
 import type { SelectedFields } from 'drizzle-orm/pg-core/query-builders';
 import { type ExtractTablesWithRelations, type RelationalSchemaConfig, 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, DuckDBTransaction } from './session.ts';
 import { DuckDBSession } from './session.ts';
 import { DuckDBDialect } from './dialect.ts';
 import { DuckDBSelectBuilder } from './select-builder.ts';
+import type { ExecuteInBatchesOptions, RowData } from './client.ts';
+import { type DuckDBPoolConfig, type PoolPreset } from './pool.ts';
 export interface PgDriverOptions {
     logger?: Logger;
     rewriteArrays?: boolean;
@@ -21,17 +25,49 @@ export declare class DuckDBDriver {
     constructor(client: DuckDBClientLike, dialect: DuckDBDialect, options?: PgDriverOptions);
     createSession(schema: RelationalSchemaConfig<TablesRelationalConfig> | undefined): DuckDBSession<Record<string, unknown>, TablesRelationalConfig>;
 }
+/** Connection configuration when using path-based connection */
+export interface DuckDBConnectionConfig {
+    /** Database path: ':memory:', './file.duckdb', 'md:', 'md:database' */
+    path: string;
+    /** DuckDB instance options (e.g., motherduck_token) */
+    options?: Record<string, string>;
+}
 export interface DuckDBDrizzleConfig<TSchema extends Record<string, unknown> = Record<string, never>> extends DrizzleConfig<TSchema> {
     rewriteArrays?: boolean;
     rejectStringArrayLiterals?: boolean;
+    /** Pool configuration. Use preset name, size config, or false to disable. */
+    pool?: DuckDBPoolConfig | PoolPreset | false;
+}
+export interface DuckDBDrizzleConfigWithConnection<TSchema extends Record<string, unknown> = Record<string, never>> extends DuckDBDrizzleConfig<TSchema> {
+    /** Connection string or config object */
+    connection: string | DuckDBConnectionConfig;
+}
+export interface DuckDBDrizzleConfigWithClient<TSchema extends Record<string, unknown> = Record<string, never>> extends DuckDBDrizzleConfig<TSchema> {
+    /** Explicit client (connection or pool) */
+    client: DuckDBClientLike;
 }
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(connectionString: string): Promise<DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(connectionString: string, config: DuckDBDrizzleConfig<TSchema>): Promise<DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(config: DuckDBDrizzleConfigWithConnection<TSchema>): Promise<DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
+export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(config: DuckDBDrizzleConfigWithClient<TSchema>): DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>;
 export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(client: DuckDBClientLike, config?: DuckDBDrizzleConfig<TSchema>): DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>;
 export declare class DuckDBDatabase<TFullSchema extends Record<string, unknown> = Record<string, never>, TSchema extends TablesRelationalConfig = ExtractTablesWithRelations<TFullSchema>> extends PgDatabase<DuckDBQueryResultHKT, TFullSchema, TSchema> {
     readonly dialect: DuckDBDialect;
     readonly session: DuckDBSession<TFullSchema, TSchema>;
     static readonly [entityKind]: string;
-    constructor(dialect: DuckDBDialect, session: DuckDBSession<TFullSchema, TSchema>, schema: RelationalSchemaConfig<TSchema> | undefined);
+    /** The underlying connection or pool */
+    readonly $client: DuckDBClientLike;
+    /** The DuckDB instance (when created from connection string) */
+    readonly $instance?: DuckDBInstance;
+    constructor(dialect: DuckDBDialect, session: DuckDBSession<TFullSchema, TSchema>, schema: RelationalSchemaConfig<TSchema> | undefined, client: DuckDBClientLike, instance?: DuckDBInstance);
+    /**
+     * Close the database connection pool and instance.
+     * Should be called when shutting down the application.
+     */
+    close(): Promise<void>;
     select(): DuckDBSelectBuilder<undefined>;
     select<TSelection extends SelectedFields>(fields: TSelection): DuckDBSelectBuilder<TSelection>;
+    executeBatches<T extends RowData = RowData>(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<T[], void, void>;
+    executeArrow(query: SQL): Promise<unknown>;
     transaction<T>(transaction: (tx: DuckDBTransaction<TFullSchema, TSchema>) => Promise<T>): Promise<T>;
 }