@leonardovida-md/drizzle-neo-duckdb 2.2.0 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -29,8 +29,8 @@ bun add @leonardovida-md/drizzle-neo-duckdb drizzle-orm @duckdb/node-api
29
29
  | Requirement | Supported versions |
30
30
  | ------------------ | ----------------------------------------------------------------------------------- |
31
31
  | `drizzle-orm` | 0.40.1 or newer, below 0.46.0 |
32
- | `@duckdb/node-api` | 1.4.4 or newer, below 1.6.0, including `-r.N` builds such as `1.5.6-r.1` |
33
- | Runtime | Node.js 18.17 or newer (22 or 24 recommended), or Bun |
32
+ | `@duckdb/node-api` | 1.4.4 or newer, below 1.6.0, including `-r.N` builds such as `1.5.6-r.2` |
33
+ | Runtime | Node.js 18.17 or newer (22, 24 or 26 recommended), or Bun |
34
34
 
35
35
  ## Quick Start
36
36
 
@@ -162,8 +162,8 @@ const db = await drizzle(':memory:', {
162
162
  // Pool size, preset, or timeout and recycling options
163
163
  pool: { size: 8, idleTimeoutMs: 60_000 },
164
164
 
165
- // Per-connection prepared statement cache (default: disabled)
166
- prepareCache: { size: 32 },
165
+ // Bind a bare Date in sql`...` as TIMESTAMPTZ instead of a naive TIMESTAMP
166
+ dateParams: 'timestamptz', // Default: 'timestamp'
167
167
 
168
168
  // Preserve DECIMAL values as strings in raw, streaming and nested reads
169
169
  decimalMode: 'string', // Default: 'number'
@@ -276,6 +276,7 @@ The package ships composable SQL helpers for analytical work:
276
276
  - Typed MotherDuck AI builders: `mdPromptJev()` classifies text or images and `mdPrompt()` generates text or structured output.
277
277
  - `duckLakeMergeAdjacentFiles()` for DuckLake compaction.
278
278
  - Batch and Arrow reads through `db.executeBatches()`, `db.executeBatchesRaw()` and `db.executeArrow()`.
279
+ - Fast bulk loads through `db.appendRows()`, which uses DuckDB's appender instead of an INSERT statement.
279
280
 
280
281
  ```typescript
281
282
  import { sql } from 'drizzle-orm';
@@ -314,7 +315,7 @@ The older `mdJobs()` and `mdFlights()` helper names remain as deprecated aliases
314
315
  | Joins and subqueries | Full support |
315
316
  | Transactions | No savepoints (nested transactions reuse the outer one). Config is ignored |
316
317
  | JSON/JSONB columns | Use `duckDbJson()` instead |
317
- | Prepared statements | Optional per-connection cache via `prepareCache`, no named statements |
318
+ | Prepared statements | Prepared on every run. No statement cache and no named statements |
318
319
  | Streaming results | Chunked reads via `executeBatches()`, no cursor streaming |
319
320
  | Concurrent queries | One query per connection. Use pooling for parallelism |
320
321
 
package/dist/client.d.ts CHANGED
@@ -18,13 +18,27 @@ export declare function isPool(client: DuckDBClientLike): client is DuckDBConnec
18
18
  export interface ExecuteClientOptions {
19
19
  /** Return DECIMAL values as exact strings, including nested values. */
20
20
  decimalMode?: 'number' | 'string';
21
+ /**
22
+ * @deprecated Ignored. DuckDB plans a prepared statement from the table
23
+ * statistics at prepare time, so running it again after the data changed
24
+ * can return wrong results. Every query is prepared for one run.
25
+ */
21
26
  prepareCache?: PreparedStatementCacheConfig;
22
27
  /**
23
28
  * Read top-level DECIMAL columns as exact strings instead of doubles. The
24
29
  * result lists those columns in `exactDecimalColumns`.
25
30
  */
26
31
  exactDecimals?: boolean;
32
+ /** How a bare Date parameter binds. Defaults to a naive UTC TIMESTAMP. */
33
+ dateParams?: DateParamType;
27
34
  }
35
+ /**
36
+ * The DuckDB type of a bare `Date` parameter, one that reaches the driver
37
+ * without a column type, as in sql`${new Date()}`. 'timestamp' binds its UTC
38
+ * wall time as a naive TIMESTAMP. 'timestamptz' binds the instant, which
39
+ * compares correctly with TIMESTAMPTZ values in any session TimeZone.
40
+ */
41
+ export type DateParamType = 'timestamp' | 'timestamptz';
28
42
  export type ExecuteArraysResult = {
29
43
  columns: string[];
30
44
  rows: unknown[][];
@@ -50,6 +64,8 @@ export declare function executeArraysOnClient(client: DuckDBClientLike, query: s
50
64
  export interface ExecuteInBatchesOptions {
51
65
  rowsPerChunk?: number;
52
66
  decimalMode?: 'number' | 'string';
67
+ /** How a bare Date parameter binds. See `dateParams` on drizzle(). */
68
+ dateParams?: DateParamType;
53
69
  }
54
70
  export interface ExecuteBatchesRawChunk {
55
71
  columns: string[];
@@ -64,4 +80,16 @@ export declare function executeInBatchesRaw(client: DuckDBClientLike, query: str
64
80
  * Return columnar results when the underlying node-api exposes an Arrow/columnar API.
65
81
  * Falls back to column-major JS arrays when Arrow is unavailable.
66
82
  */
67
- export declare function executeArrowOnClient(client: DuckDBClientLike, query: string, params: unknown[], options?: Pick<ExecuteClientOptions, 'decimalMode'>): Promise<unknown>;
83
+ export declare function executeArrowOnClient(client: DuckDBClientLike, query: string, params: unknown[], options?: Pick<ExecuteClientOptions, 'decimalMode' | 'dateParams'>): Promise<unknown>;
84
+ /** Return this for a cell to append the column's DEFAULT. */
85
+ export declare const APPEND_DEFAULT: unique symbol;
86
+ export interface AppendTarget {
87
+ table: string;
88
+ schema?: string;
89
+ }
90
+ /**
91
+ * Append rows through node-api's appender, which skips SQL parsing and
92
+ * parameter binding. `bindRows` receives the table's column names in catalog
93
+ * order and returns the value of each cell.
94
+ */
95
+ export declare function appendRowsOnClient(client: DuckDBClientLike, target: AppendTarget, rowCount: number, bindRows: (columnNames: string[]) => (rowIndex: number, columnIndex: number) => unknown): Promise<number>;
package/dist/columns.d.ts CHANGED
@@ -32,32 +32,32 @@ export declare function buildStructLiteral(value: Record<string, unknown>, schem
32
32
  export declare function buildMapLiteral(value: Record<string, unknown>, valueType?: string, keyType?: string): SQL;
33
33
  export declare const duckDbList: <TData = unknown>(name: string, elementType: DuckDbTypeName<AnyColType>) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
34
34
  name: string;
35
- dataType: "custom";
36
- columnType: "PgCustomColumn";
35
+ dataType: 'custom';
36
+ columnType: 'PgCustomColumn';
37
37
  data: TData[];
38
38
  driverParam: string | unknown[] | ListValueWrapper;
39
39
  enumValues: undefined;
40
40
  }>;
41
41
  export declare const duckDbArray: <TData = unknown>(name: string, elementType: DuckDbTypeName<AnyColType>, fixedLength?: number) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
42
42
  name: string;
43
- dataType: "custom";
44
- columnType: "PgCustomColumn";
43
+ dataType: 'custom';
44
+ columnType: 'PgCustomColumn';
45
45
  data: TData[];
46
46
  driverParam: string | unknown[] | ArrayValueWrapper;
47
47
  enumValues: undefined;
48
48
  }>;
49
49
  export declare const duckDbMap: <TData extends Record<string, any>>(name: string, valueType: DuckDbTypeName<AnyColType | ListColType | ArrayColType>, options?: MapOptions) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
50
50
  name: string;
51
- dataType: "custom";
52
- columnType: "PgCustomColumn";
51
+ dataType: 'custom';
52
+ columnType: 'PgCustomColumn';
53
53
  data: TData;
54
- driverParam: MapValueWrapper | TData;
54
+ driverParam: TData | MapValueWrapper;
55
55
  enumValues: undefined;
56
56
  }>;
57
57
  export declare const duckDbStruct: <TData extends Record<string, any>>(name: string, schema: Record<string, DuckDbTypeName<Primitive>>) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
58
58
  name: string;
59
- dataType: "custom";
60
- columnType: "PgCustomColumn";
59
+ dataType: 'custom';
60
+ columnType: 'PgCustomColumn';
61
61
  data: TData;
62
62
  driverParam: TData;
63
63
  enumValues: undefined;
@@ -74,8 +74,8 @@ export interface DuckDbUnionValue<TTag extends string = string> {
74
74
  */
75
75
  export declare const duckDbUnion: <TData extends DuckDbUnionValue = DuckDbUnionValue>(name: string, members: Record<string, DuckDbTypeName<Primitive>>) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
76
76
  name: string;
77
- dataType: "custom";
78
- columnType: "PgCustomColumn";
77
+ dataType: 'custom';
78
+ columnType: 'PgCustomColumn';
79
79
  data: TData;
80
80
  driverParam: TData;
81
81
  enumValues: undefined;
@@ -89,8 +89,8 @@ export declare const duckDbUnion: <TData extends DuckDbUnionValue = DuckDbUnionV
89
89
  */
90
90
  export declare const duckDbJson: <TData = unknown>(name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
91
91
  name: string;
92
- dataType: "custom";
93
- columnType: "PgCustomColumn";
92
+ dataType: 'custom';
93
+ columnType: 'PgCustomColumn';
94
94
  data: TData;
95
95
  driverParam: string | JsonValueWrapper | SQL<unknown>;
96
96
  enumValues: undefined;
@@ -98,24 +98,24 @@ export declare const duckDbJson: <TData = unknown>(name: string) => import("driz
98
98
  export declare const duckDbBlob: {
99
99
  (): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
100
100
  name: "";
101
- dataType: "custom";
102
- columnType: "PgCustomColumn";
101
+ dataType: 'custom';
102
+ columnType: 'PgCustomColumn';
103
103
  data: Buffer<ArrayBufferLike>;
104
104
  driverParam: string | BlobValueWrapper | Uint8Array<ArrayBufferLike>;
105
105
  enumValues: undefined;
106
106
  }>;
107
- <TConfig extends Record<string, any>>(fieldConfig?: TConfig | undefined): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
107
+ <TConfig extends Record<string, any> & unknown>(fieldConfig?: TConfig | undefined): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
108
108
  name: "";
109
- dataType: "custom";
110
- columnType: "PgCustomColumn";
109
+ dataType: 'custom';
110
+ columnType: 'PgCustomColumn';
111
111
  data: Buffer<ArrayBufferLike>;
112
112
  driverParam: string | BlobValueWrapper | Uint8Array<ArrayBufferLike>;
113
113
  enumValues: undefined;
114
114
  }>;
115
115
  <TName extends string>(dbName: TName, fieldConfig?: unknown): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
116
116
  name: TName;
117
- dataType: "custom";
118
- columnType: "PgCustomColumn";
117
+ dataType: 'custom';
118
+ columnType: 'PgCustomColumn';
119
119
  data: Buffer<ArrayBufferLike>;
120
120
  driverParam: string | BlobValueWrapper | Uint8Array<ArrayBufferLike>;
121
121
  enumValues: undefined;
@@ -123,8 +123,8 @@ export declare const duckDbBlob: {
123
123
  };
124
124
  export declare const duckDbInet: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
125
125
  name: string;
126
- dataType: "custom";
127
- columnType: "PgCustomColumn";
126
+ dataType: 'custom';
127
+ columnType: 'PgCustomColumn';
128
128
  data: string;
129
129
  driverParam: string;
130
130
  enumValues: undefined;
@@ -136,8 +136,8 @@ interface IntervalParts {
136
136
  }
137
137
  export declare const duckDbInterval: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
138
138
  name: string;
139
- dataType: "custom";
140
- columnType: "PgCustomColumn";
139
+ dataType: 'custom';
140
+ columnType: 'PgCustomColumn';
141
141
  data: string;
142
142
  driverParam: string | IntervalParts;
143
143
  enumValues: undefined;
@@ -156,28 +156,28 @@ interface TimeOptions {
156
156
  withTimezone?: boolean;
157
157
  duckDbType?: DuckDbTimeType;
158
158
  }
159
- export declare const duckDbTimestamp: <TMode extends TimestampMode = "date">(name: string, options?: TimestampOptions & {
159
+ export declare const duckDbTimestamp: <TMode extends TimestampMode = 'date'>(name: string, options?: TimestampOptions & {
160
160
  mode?: TMode;
161
161
  }) => import("drizzle-orm").$Type<import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
162
162
  name: string;
163
- dataType: "custom";
164
- columnType: "PgCustomColumn";
163
+ dataType: 'custom';
164
+ columnType: 'PgCustomColumn';
165
165
  data: string | Date;
166
- driverParam: string | TimestampValueWrapper | Date | SQL<unknown>;
166
+ driverParam: string | Date | SQL<unknown> | TimestampValueWrapper;
167
167
  enumValues: undefined;
168
168
  }>, TMode extends "string" ? string : string | Date>;
169
169
  export declare const duckDbDate: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
170
170
  name: string;
171
- dataType: "custom";
172
- columnType: "PgCustomColumn";
171
+ dataType: 'custom';
172
+ columnType: 'PgCustomColumn';
173
173
  data: string | Date;
174
174
  driverParam: string | Date;
175
175
  enumValues: undefined;
176
176
  }>;
177
177
  export declare const duckDbTime: (name: string, options?: TimeOptions) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
178
178
  name: string;
179
- dataType: "custom";
180
- columnType: "PgCustomColumn";
179
+ dataType: 'custom';
180
+ columnType: 'PgCustomColumn';
181
181
  data: string;
182
182
  driverParam: string | bigint;
183
183
  enumValues: undefined;
package/dist/dialect.d.ts CHANGED
@@ -4,12 +4,15 @@ import { PgDialect, type PgColumn, type PgTable } from 'drizzle-orm/pg-core';
4
4
  import { SQL, type DriverValueEncoder, type QueryTypingsValue } from 'drizzle-orm';
5
5
  import type { BuildRelationalQueryResult } from 'drizzle-orm/relations';
6
6
  import { type QueryWithTypings } from 'drizzle-orm/sql/sql';
7
+ import type { RelationalSelectionItem } from './sql/result-mapper.ts';
7
8
  /**
8
9
  * Query typing for params bound to a non-array column. DuckDB sessions never
9
10
  * coerce these params from Postgres array literal strings.
10
11
  * @internal
11
12
  */
12
13
  export declare const DUCKDB_SCALAR_COLUMN_TYPING: QueryTypingsValue;
14
+ /** @internal */
15
+ export declare function relationalSelectionOf(query: object): readonly RelationalSelectionItem[] | undefined;
13
16
  /**
14
17
  * Query typing for params bound to a pg-core array column, so sessions can
15
18
  * bind its empty array as an empty list.
package/dist/driver.d.ts CHANGED
@@ -3,7 +3,7 @@ import { entityKind } from 'drizzle-orm/entity';
3
3
  import type { Logger } from 'drizzle-orm/logger';
4
4
  import { PgDatabase } from 'drizzle-orm/pg-core/db';
5
5
  import type { PgSelectBuilder, SelectedFields } from 'drizzle-orm/pg-core/query-builders';
6
- import type { PgColumn, PgTransactionConfig } from 'drizzle-orm/pg-core';
6
+ import type { PgColumn, PgTable, PgTransactionConfig } from 'drizzle-orm/pg-core';
7
7
  import { type ExtractTablesWithRelations, type RelationalSchemaConfig, type TablesRelationalConfig } from 'drizzle-orm/relations';
8
8
  import { type DrizzleConfig } from 'drizzle-orm/utils';
9
9
  import type { SQL, SQLWrapper } from 'drizzle-orm/sql/sql';
@@ -12,12 +12,13 @@ import type { DuckDBClientLike, DuckDBQueryResultHKT, DuckDBTransaction } from '
12
12
  import { DuckDBSession } from './session.ts';
13
13
  import { DuckDBDialect } from './dialect.ts';
14
14
  import { type DuckDBSelectBuilder } from './select-builder.ts';
15
- import type { ExecuteBatchesRawChunk, ExecuteInBatchesOptions, RowData } from './client.ts';
15
+ import type { DateParamType, ExecuteBatchesRawChunk, ExecuteInBatchesOptions, RowData } from './client.ts';
16
16
  import { type DuckDBPoolConfig, type PoolPreset } from './pool.ts';
17
17
  import { type PreparedStatementCacheConfig, type PrepareCacheOption } from './options.ts';
18
18
  import { type DuckLakeConfig } from './ducklake.ts';
19
19
  export interface PgDriverOptions {
20
20
  decimalMode?: 'number' | 'string';
21
+ dateParams?: DateParamType;
21
22
  logger?: Logger;
22
23
  rejectStringArrayLiterals?: boolean;
23
24
  arrayLiteralWarning?: (query: string) => void;
@@ -41,11 +42,23 @@ export interface DuckDBConnectionConfig {
41
42
  export interface DuckDBDrizzleConfig<TSchema extends Record<string, unknown> = Record<string, never>> extends DrizzleConfig<TSchema> {
42
43
  rejectStringArrayLiterals?: boolean;
43
44
  arrayLiteralWarning?: (query: string) => void;
45
+ /**
46
+ * @deprecated Ignored, with a one-time warning. DuckDB can return wrong
47
+ * results when a prepared statement runs again after the data changed, so
48
+ * statements are no longer cached.
49
+ */
44
50
  prepareCache?: PrepareCacheOption;
45
51
  /** Opt into legacy heuristic qualification of raw SQL join operands. */
46
52
  qualifyRawJoinColumns?: boolean;
47
53
  /** Opt into exact DECIMAL strings across execution paths. */
48
54
  decimalMode?: 'number' | 'string';
55
+ /**
56
+ * How a bare `Date` parameter binds, as in sql`${new Date()}`. The default
57
+ * 'timestamp' binds its UTC wall time as a naive TIMESTAMP, which DuckDB
58
+ * reads in the session TimeZone when it compares it with a TIMESTAMPTZ.
59
+ * 'timestamptz' binds the instant instead. Typed columns are not affected.
60
+ */
61
+ dateParams?: DateParamType;
49
62
  /** Pool configuration. Use preset name, size config, or false to disable. */
50
63
  pool?: DuckDBPoolConfig | PoolPreset | false;
51
64
  /** Optional DuckLake configuration */
@@ -89,6 +102,18 @@ export declare class DuckDBDatabase<TFullSchema extends Record<string, unknown>
89
102
  executeBatches<T extends RowData = RowData>(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<T[], void, void>;
90
103
  executeBatchesRaw(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<ExecuteBatchesRawChunk, void, void>;
91
104
  executeArrow(query: SQL): Promise<unknown>;
105
+ /**
106
+ * Append rows with DuckDB's appender instead of an INSERT statement. It
107
+ * skips SQL building and parameter binding, so large batches load far
108
+ * faster than `db.insert().values()`. Missing columns take their default.
109
+ * Returns the number of rows appended.
110
+ *
111
+ * The appender has no RETURNING or ON CONFLICT, and it cannot take values
112
+ * that a column encodes as SQL, such as structs. Outside a transaction a
113
+ * failure can leave earlier rows of the batch in the table. Use
114
+ * `db.transaction((tx) => tx.appendRows(...))` for all or nothing.
115
+ */
116
+ appendRows<TTable extends PgTable>(table: TTable, rows: readonly TTable['$inferInsert'][]): Promise<number>;
92
117
  /**
93
118
  * Run a transaction. The `config` argument is deprecated: DuckDB has no
94
119
  * SET TRANSACTION statement, so it is ignored with a one-time warning.