@leonardovida-md/drizzle-neo-duckdb 2.3.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 +6 -5
- package/dist/client.d.ts +29 -1
- package/dist/columns.d.ts +32 -32
- package/dist/driver.d.ts +27 -2
- package/dist/duckdb-introspect.mjs +276 -197
- package/dist/helpers.mjs +16 -16
- package/dist/index.mjs +415 -339
- package/dist/motherduck.d.ts +8 -3
- package/dist/prepared-statement-cache.d.ts +4 -1
- package/dist/session.d.ts +12 -3
- package/package.json +21 -8
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.
|
|
33
|
-
| Runtime | Node.js 18.17 or newer (22 or
|
|
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
|
-
//
|
|
166
|
-
|
|
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 |
|
|
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:
|
|
36
|
-
columnType:
|
|
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:
|
|
44
|
-
columnType:
|
|
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:
|
|
52
|
-
columnType:
|
|
51
|
+
dataType: 'custom';
|
|
52
|
+
columnType: 'PgCustomColumn';
|
|
53
53
|
data: TData;
|
|
54
|
-
driverParam:
|
|
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:
|
|
60
|
-
columnType:
|
|
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:
|
|
78
|
-
columnType:
|
|
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:
|
|
93
|
-
columnType:
|
|
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:
|
|
102
|
-
columnType:
|
|
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
|
|
107
|
+
<TConfig extends Record<string, any> & unknown>(fieldConfig?: TConfig | undefined): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
108
108
|
name: "";
|
|
109
|
-
dataType:
|
|
110
|
-
columnType:
|
|
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:
|
|
118
|
-
columnType:
|
|
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:
|
|
127
|
-
columnType:
|
|
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:
|
|
140
|
-
columnType:
|
|
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 =
|
|
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:
|
|
164
|
-
columnType:
|
|
163
|
+
dataType: 'custom';
|
|
164
|
+
columnType: 'PgCustomColumn';
|
|
165
165
|
data: string | Date;
|
|
166
|
-
driverParam: string |
|
|
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:
|
|
172
|
-
columnType:
|
|
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:
|
|
180
|
-
columnType:
|
|
179
|
+
dataType: 'custom';
|
|
180
|
+
columnType: 'PgCustomColumn';
|
|
181
181
|
data: string;
|
|
182
182
|
driverParam: string | bigint;
|
|
183
183
|
enumValues: undefined;
|
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.
|