@leonardovida-md/drizzle-neo-duckdb 1.1.1 → 1.1.2

package/README.md

@@ -13,7 +13,7 @@
 
 <br>
 
-**Drizzle DuckDB** brings [Drizzle ORM](https://orm.drizzle.team/) to [DuckDB](https://duckdb.org/) — the fast in-process analytical database. Get Drizzle's type-safe query builder, automatic migrations, and full TypeScript inference while working with DuckDB's powerful analytics engine.
+**Drizzle DuckDB** brings [Drizzle ORM](https://orm.drizzle.team/) to [DuckDB](https://duckdb.org/), an in-process analytical database. You get Drizzle's type-safe query builder, automatic migrations, and full TypeScript inference while working with DuckDB's analytics engine.
 
 Works with local DuckDB files, in-memory databases, and [MotherDuck](https://motherduck.com/) cloud.
 
@@ -115,95 +115,48 @@ const db = drizzle(connection, {
 });
 ```
 
-## Schema Declaration
+> Tip: With connection strings (recommended), just pass the path: `const db = await drizzle(':memory:')`. Pooling is automatic.
 
-Drizzle DuckDB uses `drizzle-orm/pg-core` for schema definitions since DuckDB's SQL is largely Postgres-compatible:
+## Connection Pooling
 
-```typescript
-import { sql } from 'drizzle-orm';
-import {
-  integer,
-  text,
-  boolean,
-  timestamp,
-  pgTable,
-  pgSchema,
-} from 'drizzle-orm/pg-core';
-
-// Tables in default schema
-const posts = pgTable('posts', {
-  id: integer('id').primaryKey(),
-  title: text('title').notNull(),
-  published: boolean('published').default(false),
-  createdAt: timestamp('created_at').defaultNow(),
-});
+DuckDB executes one query per connection. The async `drizzle()` entrypoints create a pool automatically (default size: 4). Options:
 
-// Tables in custom schema
-const analytics = pgSchema('analytics');
-
-const events = analytics.table('events', {
-  id: integer('id').primaryKey(),
-  name: text('name').notNull(),
-  timestamp: timestamp('timestamp').defaultNow(),
-});
-```
-
-## DuckDB-Specific Column Types
-
-For DuckDB-specific types like `STRUCT`, `MAP`, `LIST`, and proper timestamp handling, use the custom column helpers:
+- Set pool size or MotherDuck preset: `drizzle('md:', { pool: { size: 8 } })` or `pool: 'jumbo'` / `pool: 'giga'`.
+- Disable pooling for single-connection workloads: `pool: false`.
+- Transactions pin one pooled connection for their entire lifetime; non-transactional queries still use the pool.
+- For tuning (acquire timeout, queue limits, idle/lifetime recycling), create the pool manually:
 
 ```typescript
+import { DuckDBInstance } from '@duckdb/node-api';
 import {
-  duckDbList,
-  duckDbArray,
-  duckDbStruct,
-  duckDbMap,
-  duckDbJson,
-  duckDbTimestamp,
-  duckDbDate,
-  duckDbTime,
+  createDuckDBConnectionPool,
+  drizzle,
 } from '@leonardovida-md/drizzle-neo-duckdb';
 
-const products = pgTable('products', {
-  id: integer('id').primaryKey(),
-
-  // LIST type (variable length)
-  tags: duckDbList('tags', 'TEXT'),
-
-  // ARRAY type (fixed length)
-  coordinates: duckDbArray('coordinates', 'DOUBLE', 3),
-
-  // STRUCT type
-  metadata: duckDbStruct('metadata', {
-    version: 'INTEGER',
-    author: 'TEXT',
-  }),
-
-  // MAP type
-  attributes: duckDbMap('attributes', 'TEXT'),
-
-  // JSON type (use this instead of pg json/jsonb)
-  config: duckDbJson('config'),
-
-  // Timestamp with proper DuckDB handling
-  createdAt: duckDbTimestamp('created_at', { withTimezone: true }),
+const instance = await DuckDBInstance.create('md:', {
+  motherduck_token: process.env.MOTHERDUCK_TOKEN,
+});
+const pool = createDuckDBConnectionPool(instance, {
+  size: 8,
+  acquireTimeout: 20_000,
+  maxWaitingRequests: 200,
+  maxLifetimeMs: 10 * 60_000,
+  idleTimeoutMs: 60_000,
 });
+const db = drizzle(pool);
 ```
 
-See [Column Types Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/api/columns) for complete reference.
+## Schema & Types
 
-### Client-Safe Imports (schemas, drizzle-zod, trpc)
+- Use `drizzle-orm/pg-core` for schemas; DuckDB SQL is largely Postgres-compatible.
+- DuckDB-specific helpers: `duckDbList`, `duckDbArray`, `duckDbStruct`, `duckDbMap`, `duckDbJson`, `duckDbTimestamp`, `duckDbDate`, `duckDbTime`.
+- Browser-safe imports live under `@leonardovida-md/drizzle-neo-duckdb/helpers` (introspection emits this path).
 
-When generated schemas are consumed in client bundles, import the helpers from the browser-safe subpath to avoid pulling the native DuckDB bindings:
+See the [column types](https://leonardovida.github.io/drizzle-neo-duckdb/api/columns) docs for full API.
 
-```typescript
-import {
-  duckDbJson,
-  duckDbList,
-} from '@leonardovida-md/drizzle-neo-duckdb/helpers';
-```
+## Postgres Schema Compatibility
 
-The introspection CLI now emits this import path by default. You can still override `importBasePath` if you need the old root import.
+Use `pgTable`, `pgSchema`, and other `drizzle-orm/pg-core` builders as you do with Postgres. The dialect keeps table definitions and relations intact while adapting queries to DuckDB.
 
 ## Querying
 
@@ -324,6 +277,9 @@ const db = drizzle(connection, {
   // Enable query logging
   logger: new DefaultLogger(),
 
+  // Pool size/preset when using connection strings (default: 4). Set false to disable.
+  pool: { size: 8 },
+
   // Rewrite Postgres array operators to DuckDB functions (default: true)
   rewriteArrays: true,
 
@@ -339,25 +295,28 @@ 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     | Materialized by default; use `executeBatches()` for chunks |
+| 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     | Chunked reads via `executeBatches()` / `executeArrow()`; no cursor streaming |
+| Concurrent queries    | One query per connection; use pooling for parallelism                        |
 
-See [Limitations Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/guide/limitations) for details.
+See [Limitations Documentation](https://leonardovida.github.io/drizzle-neo-duckdb/reference/limitations) for details.
 
 ## Examples
 
-- **[MotherDuck NYC Taxi](./example/motherduck-nyc.ts)** — Query the built-in NYC taxi dataset from MotherDuck cloud
+- **[MotherDuck NYC Taxi](./example/motherduck-nyc.ts)**: Query the built-in NYC taxi dataset from MotherDuck cloud
+- **[Analytics Dashboard](./example/analytics-dashboard.ts)**: Local in-memory analytics with DuckDB types and Parquet loading
 
 Run examples:
 
 ```bash
 MOTHERDUCK_TOKEN=your_token bun example/motherduck-nyc.ts
+bun example/analytics-dashboard.ts
 ```
 
 ## Contributing

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import { type DuckDBConnection } from '@duckdb/node-api';
+import type { PreparedStatementCacheConfig } from './options.ts';
 export type DuckDBClientLike = DuckDBConnection | DuckDBConnectionPool;
 export type RowData = Record<string, unknown>;
 export interface DuckDBConnectionPool {
@@ -7,20 +8,33 @@ export interface DuckDBConnectionPool {
     close?(): Promise<void> | void;
 }
 export declare function isPool(client: DuckDBClientLike): client is DuckDBConnectionPool;
+export interface ExecuteClientOptions {
+    prepareCache?: PreparedStatementCacheConfig;
+}
+export type ExecuteArraysResult = {
+    columns: string[];
+    rows: unknown[][];
+};
 export interface PrepareParamsOptions {
     rejectStringArrayLiterals?: boolean;
     warnOnStringArrayLiteral?: () => void;
 }
 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 declare function executeOnClient(client: DuckDBClientLike, query: string, params: unknown[], options?: ExecuteClientOptions): Promise<RowData[]>;
+export declare function executeArraysOnClient(client: DuckDBClientLike, query: string, params: unknown[], options?: ExecuteClientOptions): Promise<ExecuteArraysResult>;
 export interface ExecuteInBatchesOptions {
     rowsPerChunk?: number;
 }
+export interface ExecuteBatchesRawChunk {
+    columns: string[];
+    rows: unknown[][];
+}
 /**
  * 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>;
+export declare function executeInBatchesRaw(client: DuckDBClientLike, query: string, params: unknown[], options?: ExecuteInBatchesOptions): AsyncGenerator<ExecuteBatchesRawChunk, 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.

package/dist/columns.d.ts

@@ -1,6 +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';
+import { type ListValueWrapper, type ArrayValueWrapper, type MapValueWrapper, type BlobValueWrapper, type JsonValueWrapper, type TimestampValueWrapper } 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';
@@ -111,13 +111,14 @@ interface TimestampOptions {
     withTimezone?: boolean;
     mode?: TimestampMode;
     precision?: number;
+    bindMode?: 'auto' | 'bind' | 'literal';
 }
 export declare const duckDbTimestamp: (name: string, options?: TimestampOptions) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
     name: string;
     dataType: "custom";
     columnType: "PgCustomColumn";
     data: string | Date;
-    driverParam: string | Date | SQL<unknown>;
+    driverParam: string | TimestampValueWrapper | Date | SQL<unknown>;
     enumValues: undefined;
 }>;
 export declare const duckDbDate: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{

package/dist/driver.d.ts

@@ -10,12 +10,14 @@ import type { DuckDBClientLike, DuckDBQueryResultHKT, DuckDBTransaction } from '
 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 { ExecuteBatchesRawChunk, ExecuteInBatchesOptions, RowData } from './client.ts';
 import { type DuckDBPoolConfig, type PoolPreset } from './pool.ts';
+import { type PreparedStatementCacheConfig, type PrepareCacheOption, type RewriteArraysMode, type RewriteArraysOption } from './options.ts';
 export interface PgDriverOptions {
     logger?: Logger;
-    rewriteArrays?: boolean;
+    rewriteArrays?: RewriteArraysMode;
     rejectStringArrayLiterals?: boolean;
+    prepareCache?: PreparedStatementCacheConfig;
 }
 export declare class DuckDBDriver {
     private client;
@@ -33,8 +35,9 @@ export interface DuckDBConnectionConfig {
     options?: Record<string, string>;
 }
 export interface DuckDBDrizzleConfig<TSchema extends Record<string, unknown> = Record<string, never>> extends DrizzleConfig<TSchema> {
-    rewriteArrays?: boolean;
+    rewriteArrays?: RewriteArraysOption;
     rejectStringArrayLiterals?: boolean;
+    prepareCache?: PrepareCacheOption;
     /** Pool configuration. Use preset name, size config, or false to disable. */
     pool?: DuckDBPoolConfig | PoolPreset | false;
 }
@@ -68,6 +71,7 @@ export declare class DuckDBDatabase<TFullSchema extends Record<string, unknown>
     select(): DuckDBSelectBuilder<undefined>;
     select<TSelection extends SelectedFields>(fields: TSelection): DuckDBSelectBuilder<TSelection>;
     executeBatches<T extends RowData = RowData>(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<T[], void, void>;
+    executeBatchesRaw(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<ExecuteBatchesRawChunk, void, void>;
     executeArrow(query: SQL): Promise<unknown>;
     transaction<T>(transaction: (tx: DuckDBTransaction<TFullSchema, TSchema>) => Promise<T>): Promise<T>;
 }