@leonardovida-md/drizzle-neo-duckdb 2.3.0 → 3.0.0-rc.2
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 +15 -15
- package/dist/client.d.ts +24 -3
- package/dist/codecs.d.ts +33 -0
- package/dist/columns.d.ts +19 -66
- package/dist/dialect.d.ts +12 -38
- package/dist/driver.d.ts +48 -29
- package/dist/duckdb-introspect.mjs +851 -677
- package/dist/ducklake.d.ts +0 -5
- package/dist/helpers.mjs +16 -16
- package/dist/index.d.ts +3 -5
- package/dist/index.mjs +1087 -1093
- package/dist/introspect.d.ts +0 -2
- package/dist/migrator.d.ts +2 -1
- package/dist/motherduck.d.ts +8 -120
- package/dist/select-builder.d.ts +53 -36
- package/dist/session.d.ts +56 -65
- package/dist/sql/result-mapper.d.ts +42 -13
- package/dist/sql/selection.d.ts +1 -11
- package/package.json +27 -14
- package/dist/options.d.ts +0 -8
- package/dist/prepared-statement-cache.d.ts +0 -37
package/README.md
CHANGED
|
@@ -17,20 +17,22 @@
|
|
|
17
17
|
|
|
18
18
|
> **Status:** Experimental. Query building, migrations and type inference are stable. Some DuckDB-specific types and edge cases are still being refined.
|
|
19
19
|
|
|
20
|
+
> **Version 3 is a release candidate.** It requires drizzle-orm 1.0, which is itself a release candidate, and is published under the `next` tag. Version 2.6 remains the `latest` release and works with drizzle-orm 0.40.1 to 0.45. Its source and documentation are on the [`2.x` branch](https://github.com/leonardovida/drizzle-duckdb/tree/2.x). See [Upgrading to v3](https://leonardovida.github.io/drizzle-duckdb/reference/upgrading-to-v3).
|
|
21
|
+
|
|
20
22
|
Every docs page has a **Markdown (raw)** button with LLM-friendly source.
|
|
21
23
|
|
|
22
24
|
## Installation
|
|
23
25
|
|
|
24
26
|
```bash
|
|
25
|
-
bun add @leonardovida-md/drizzle-neo-duckdb drizzle-orm @duckdb/node-api
|
|
27
|
+
bun add @leonardovida-md/drizzle-neo-duckdb@next drizzle-orm@rc @duckdb/node-api
|
|
26
28
|
# or: npm install / pnpm add with the same packages
|
|
27
29
|
```
|
|
28
30
|
|
|
29
31
|
| Requirement | Supported versions |
|
|
30
32
|
| ------------------ | ----------------------------------------------------------------------------------- |
|
|
31
|
-
| `drizzle-orm` | 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
|
|
33
|
+
| `drizzle-orm` | 1.0.0-rc.5 to 1.0.0-rc.99, or 1.x from 1.0.0. npm snapshot builds do not match |
|
|
34
|
+
| `@duckdb/node-api` | 1.4.4 or newer, below 1.6.0, including `-r.N` builds such as `1.5.6-r.2` |
|
|
35
|
+
| Runtime | Node.js 22 or newer, or Bun |
|
|
34
36
|
|
|
35
37
|
## Quick Start
|
|
36
38
|
|
|
@@ -162,8 +164,8 @@ const db = await drizzle(':memory:', {
|
|
|
162
164
|
// Pool size, preset, or timeout and recycling options
|
|
163
165
|
pool: { size: 8, idleTimeoutMs: 60_000 },
|
|
164
166
|
|
|
165
|
-
//
|
|
166
|
-
|
|
167
|
+
// Bind a bare Date in sql`...` as TIMESTAMPTZ instead of a naive TIMESTAMP
|
|
168
|
+
dateParams: 'timestamptz', // Default: 'timestamp'
|
|
167
169
|
|
|
168
170
|
// Preserve DECIMAL values as strings in raw, streaming and nested reads
|
|
169
171
|
decimalMode: 'string', // Default: 'number'
|
|
@@ -174,11 +176,8 @@ const db = await drizzle(':memory:', {
|
|
|
174
176
|
// Throw on Postgres-style array literals like '{1,2,3}' (default: false)
|
|
175
177
|
rejectStringArrayLiterals: false,
|
|
176
178
|
|
|
177
|
-
//
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
// Schema for relational queries
|
|
181
|
-
schema: mySchema,
|
|
179
|
+
// Relations from defineRelations() for relational queries
|
|
180
|
+
relations,
|
|
182
181
|
});
|
|
183
182
|
```
|
|
184
183
|
|
|
@@ -231,7 +230,7 @@ DuckDB differs from Postgres here:
|
|
|
231
230
|
- There is no `SAVEPOINT`. Nested transactions reuse the outer one, so an inner rollback aborts everything.
|
|
232
231
|
- Without a pool, other `db` queries wait while a transaction is open on the shared connection, instead of joining it.
|
|
233
232
|
- Any failed statement aborts the whole transaction. Catching the error inside the callback does not keep earlier writes. `db.transaction()` rolls back and rejects.
|
|
234
|
-
-
|
|
233
|
+
- DuckDB has no `SET TRANSACTION`, so `db.transaction()` rejects when it receives a `config` argument (`isolationLevel`, `accessMode`, `deferrable`).
|
|
235
234
|
|
|
236
235
|
## Migrations
|
|
237
236
|
|
|
@@ -276,6 +275,7 @@ The package ships composable SQL helpers for analytical work:
|
|
|
276
275
|
- Typed MotherDuck AI builders: `mdPromptJev()` classifies text or images and `mdPrompt()` generates text or structured output.
|
|
277
276
|
- `duckLakeMergeAdjacentFiles()` for DuckLake compaction.
|
|
278
277
|
- Batch and Arrow reads through `db.executeBatches()`, `db.executeBatchesRaw()` and `db.executeArrow()`.
|
|
278
|
+
- Fast bulk loads through `db.appendRows()`, which uses DuckDB's appender instead of an INSERT statement.
|
|
279
279
|
|
|
280
280
|
```typescript
|
|
281
281
|
import { sql } from 'drizzle-orm';
|
|
@@ -304,7 +304,7 @@ await db.execute(sql`
|
|
|
304
304
|
`);
|
|
305
305
|
```
|
|
306
306
|
|
|
307
|
-
The older `mdJobs()` and `mdFlights()`
|
|
307
|
+
The Job helpers and older Flight aliases such as `mdJobs()` and `mdFlights()` were removed in 3.0. See [Upgrading to v3](https://leonardovida.github.io/drizzle-duckdb/reference/upgrading-to-v3) for their replacements, [OLAP Helpers](https://leonardovida.github.io/drizzle-duckdb/api/olap-helpers) for the full list, Flight options and log pagination, and [MotherDuck](https://leonardovida.github.io/drizzle-duckdb/integrations/motherduck) for the AI builders.
|
|
308
308
|
|
|
309
309
|
## Known Limitations
|
|
310
310
|
|
|
@@ -312,9 +312,9 @@ The older `mdJobs()` and `mdFlights()` helper names remain as deprecated aliases
|
|
|
312
312
|
| --------------------- | ----------------------------------------------------------------------------- |
|
|
313
313
|
| Basic CRUD operations | Full support |
|
|
314
314
|
| Joins and subqueries | Full support |
|
|
315
|
-
| Transactions | No savepoints (nested transactions reuse the outer one). Config
|
|
315
|
+
| Transactions | No savepoints (nested transactions reuse the outer one). Config rejects |
|
|
316
316
|
| JSON/JSONB columns | Use `duckDbJson()` instead |
|
|
317
|
-
| Prepared statements |
|
|
317
|
+
| Prepared statements | Prepared on every run. No statement cache and no named statements |
|
|
318
318
|
| Streaming results | Chunked reads via `executeBatches()`, no cursor streaming |
|
|
319
319
|
| Concurrent queries | One query per connection. Use pooling for parallelism |
|
|
320
320
|
|
package/dist/client.d.ts
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import { type DuckDBConnection, type DuckDBInstance } from '@duckdb/node-api';
|
|
2
|
-
import { type PreparedStatementCacheConfig } from './options.ts';
|
|
3
2
|
import type { PgDuckClient } from './pgduck.ts';
|
|
4
3
|
export type DuckDBExecutionClient = DuckDBConnection | PgDuckClient;
|
|
5
4
|
export type DuckDBClientLike = DuckDBExecutionClient | DuckDBConnectionPool;
|
|
@@ -18,13 +17,21 @@ export declare function isPool(client: DuckDBClientLike): client is DuckDBConnec
|
|
|
18
17
|
export interface ExecuteClientOptions {
|
|
19
18
|
/** Return DECIMAL values as exact strings, including nested values. */
|
|
20
19
|
decimalMode?: 'number' | 'string';
|
|
21
|
-
prepareCache?: PreparedStatementCacheConfig;
|
|
22
20
|
/**
|
|
23
21
|
* Read top-level DECIMAL columns as exact strings instead of doubles. The
|
|
24
22
|
* result lists those columns in `exactDecimalColumns`.
|
|
25
23
|
*/
|
|
26
24
|
exactDecimals?: boolean;
|
|
25
|
+
/** How a bare Date parameter binds. Defaults to a naive UTC TIMESTAMP. */
|
|
26
|
+
dateParams?: DateParamType;
|
|
27
27
|
}
|
|
28
|
+
/**
|
|
29
|
+
* The DuckDB type of a bare `Date` parameter, one that reaches the driver
|
|
30
|
+
* without a column type, as in sql`${new Date()}`. 'timestamp' binds its UTC
|
|
31
|
+
* wall time as a naive TIMESTAMP. 'timestamptz' binds the instant, which
|
|
32
|
+
* compares correctly with TIMESTAMPTZ values in any session TimeZone.
|
|
33
|
+
*/
|
|
34
|
+
export type DateParamType = 'timestamp' | 'timestamptz';
|
|
28
35
|
export type ExecuteArraysResult = {
|
|
29
36
|
columns: string[];
|
|
30
37
|
rows: unknown[][];
|
|
@@ -50,6 +57,8 @@ export declare function executeArraysOnClient(client: DuckDBClientLike, query: s
|
|
|
50
57
|
export interface ExecuteInBatchesOptions {
|
|
51
58
|
rowsPerChunk?: number;
|
|
52
59
|
decimalMode?: 'number' | 'string';
|
|
60
|
+
/** How a bare Date parameter binds. See `dateParams` on drizzle(). */
|
|
61
|
+
dateParams?: DateParamType;
|
|
53
62
|
}
|
|
54
63
|
export interface ExecuteBatchesRawChunk {
|
|
55
64
|
columns: string[];
|
|
@@ -64,4 +73,16 @@ export declare function executeInBatchesRaw(client: DuckDBClientLike, query: str
|
|
|
64
73
|
* Return columnar results when the underlying node-api exposes an Arrow/columnar API.
|
|
65
74
|
* Falls back to column-major JS arrays when Arrow is unavailable.
|
|
66
75
|
*/
|
|
67
|
-
export declare function executeArrowOnClient(client: DuckDBClientLike, query: string, params: unknown[], options?: Pick<ExecuteClientOptions, 'decimalMode'>): Promise<unknown>;
|
|
76
|
+
export declare function executeArrowOnClient(client: DuckDBClientLike, query: string, params: unknown[], options?: Pick<ExecuteClientOptions, 'decimalMode' | 'dateParams'>): Promise<unknown>;
|
|
77
|
+
/** Return this for a cell to append the column's DEFAULT. */
|
|
78
|
+
export declare const APPEND_DEFAULT: unique symbol;
|
|
79
|
+
export interface AppendTarget {
|
|
80
|
+
table: string;
|
|
81
|
+
schema?: string;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Append rows through node-api's appender, which skips SQL parsing and
|
|
85
|
+
* parameter binding. `bindRows` receives the table's column names in catalog
|
|
86
|
+
* order and returns the value of each cell.
|
|
87
|
+
*/
|
|
88
|
+
export declare function appendRowsOnClient(client: DuckDBClientLike, target: AppendTarget, rowCount: number, bindRows: (columnNames: string[]) => (rowIndex: number, columnIndex: number) => unknown): Promise<number>;
|
package/dist/codecs.d.ts
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { entityKind } from 'drizzle-orm/entity';
|
|
2
|
+
import { Column } from 'drizzle-orm/column';
|
|
3
|
+
import { CodecsCollection, type Codecs, type ResolvedCodecs } from 'drizzle-orm/codecs';
|
|
4
|
+
export declare const PG_JSON_UNSUPPORTED_MESSAGE = "Pg JSON/JSONB columns are not supported in DuckDB. Replace them with duckDbJson() to use DuckDB's native JSON type.";
|
|
5
|
+
/** Codecs of the pg-core column types, keyed by their codec name. */
|
|
6
|
+
export declare const duckDbCodecs: Codecs;
|
|
7
|
+
/** How a bound parameter relates to a column. */
|
|
8
|
+
export type ParamKind = 'scalar' | 'array';
|
|
9
|
+
/**
|
|
10
|
+
* Run `build`, which renders a query, and collect the kind of every param
|
|
11
|
+
* bound to a column: 'array' for a pg-core array column, 'scalar' for any
|
|
12
|
+
* other column. Params without a column are not listed. drizzle-orm 1.0 no
|
|
13
|
+
* longer reports query typings, so the codecs record this while rendering.
|
|
14
|
+
*/
|
|
15
|
+
export declare function recordParamKinds<T>(build: () => T): {
|
|
16
|
+
result: T;
|
|
17
|
+
kinds: Map<number, ParamKind>;
|
|
18
|
+
};
|
|
19
|
+
/**
|
|
20
|
+
* Codecs for the DuckDB dialect. Every column gets a `castParam` codec, even
|
|
21
|
+
* a custom column without a codec name, so that the session learns which
|
|
22
|
+
* params are bound to a column and which of those to an array column. Pg
|
|
23
|
+
* JSON and JSONB params throw, since DuckDB has its own JSON type.
|
|
24
|
+
* `numeric()` values of relations are read as text, so they keep every digit.
|
|
25
|
+
*/
|
|
26
|
+
export declare class DuckDBCodecsCollection extends CodecsCollection {
|
|
27
|
+
static readonly [entityKind]: string;
|
|
28
|
+
private readonly resolved;
|
|
29
|
+
constructor();
|
|
30
|
+
/** @internal */
|
|
31
|
+
codecsOf(column: Column, override?: string): ResolvedCodecs;
|
|
32
|
+
private extend;
|
|
33
|
+
}
|
package/dist/columns.d.ts
CHANGED
|
@@ -31,36 +31,24 @@ export declare function normalizeArrayPredicateValue<T>(values: ArrayPredicateVa
|
|
|
31
31
|
export declare function buildStructLiteral(value: Record<string, unknown>, schema?: Record<string, DuckDbTypeName<Primitive>>): SQL;
|
|
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
|
-
|
|
35
|
-
dataType: "custom";
|
|
36
|
-
columnType: "PgCustomColumn";
|
|
34
|
+
dataType: 'custom';
|
|
37
35
|
data: TData[];
|
|
38
36
|
driverParam: string | unknown[] | ListValueWrapper;
|
|
39
|
-
enumValues: undefined;
|
|
40
37
|
}>;
|
|
41
38
|
export declare const duckDbArray: <TData = unknown>(name: string, elementType: DuckDbTypeName<AnyColType>, fixedLength?: number) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
42
|
-
|
|
43
|
-
dataType: "custom";
|
|
44
|
-
columnType: "PgCustomColumn";
|
|
39
|
+
dataType: 'custom';
|
|
45
40
|
data: TData[];
|
|
46
41
|
driverParam: string | unknown[] | ArrayValueWrapper;
|
|
47
|
-
enumValues: undefined;
|
|
48
42
|
}>;
|
|
49
43
|
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
|
-
|
|
51
|
-
dataType: "custom";
|
|
52
|
-
columnType: "PgCustomColumn";
|
|
44
|
+
dataType: 'custom';
|
|
53
45
|
data: TData;
|
|
54
|
-
driverParam:
|
|
55
|
-
enumValues: undefined;
|
|
46
|
+
driverParam: TData | MapValueWrapper;
|
|
56
47
|
}>;
|
|
57
48
|
export declare const duckDbStruct: <TData extends Record<string, any>>(name: string, schema: Record<string, DuckDbTypeName<Primitive>>) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
58
|
-
|
|
59
|
-
dataType: "custom";
|
|
60
|
-
columnType: "PgCustomColumn";
|
|
49
|
+
dataType: 'custom';
|
|
61
50
|
data: TData;
|
|
62
51
|
driverParam: TData;
|
|
63
|
-
enumValues: undefined;
|
|
64
52
|
}>;
|
|
65
53
|
/** A UNION value as DuckDB returns it: the member name and its value. */
|
|
66
54
|
export interface DuckDbUnionValue<TTag extends string = string> {
|
|
@@ -73,12 +61,9 @@ export interface DuckDbUnionValue<TTag extends string = string> {
|
|
|
73
61
|
* type.
|
|
74
62
|
*/
|
|
75
63
|
export declare const duckDbUnion: <TData extends DuckDbUnionValue = DuckDbUnionValue>(name: string, members: Record<string, DuckDbTypeName<Primitive>>) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
76
|
-
|
|
77
|
-
dataType: "custom";
|
|
78
|
-
columnType: "PgCustomColumn";
|
|
64
|
+
dataType: 'custom';
|
|
79
65
|
data: TData;
|
|
80
66
|
driverParam: TData;
|
|
81
|
-
enumValues: undefined;
|
|
82
67
|
}>;
|
|
83
68
|
/**
|
|
84
69
|
* JSON column type that wraps values and delays JSON.stringify() to binding time.
|
|
@@ -88,46 +73,26 @@ export declare const duckDbUnion: <TData extends DuckDbUnionValue = DuckDbUnionV
|
|
|
88
73
|
* is always a stringified JSON value.
|
|
89
74
|
*/
|
|
90
75
|
export declare const duckDbJson: <TData = unknown>(name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
91
|
-
|
|
92
|
-
dataType: "custom";
|
|
93
|
-
columnType: "PgCustomColumn";
|
|
76
|
+
dataType: 'custom';
|
|
94
77
|
data: TData;
|
|
95
78
|
driverParam: string | JsonValueWrapper | SQL<unknown>;
|
|
96
|
-
enumValues: undefined;
|
|
97
79
|
}>;
|
|
98
80
|
export declare const duckDbBlob: {
|
|
99
|
-
(): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
100
|
-
|
|
101
|
-
dataType: "custom";
|
|
102
|
-
columnType: "PgCustomColumn";
|
|
81
|
+
<TConfig extends Record<string, any> & unknown>(fieldConfig?: TConfig | undefined): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
82
|
+
dataType: 'custom';
|
|
103
83
|
data: Buffer<ArrayBufferLike>;
|
|
104
84
|
driverParam: string | BlobValueWrapper | Uint8Array<ArrayBufferLike>;
|
|
105
|
-
enumValues: undefined;
|
|
106
85
|
}>;
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
dataType: "custom";
|
|
110
|
-
columnType: "PgCustomColumn";
|
|
86
|
+
(dbName: string, fieldConfig?: unknown): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
87
|
+
dataType: 'custom';
|
|
111
88
|
data: Buffer<ArrayBufferLike>;
|
|
112
89
|
driverParam: string | BlobValueWrapper | Uint8Array<ArrayBufferLike>;
|
|
113
|
-
enumValues: undefined;
|
|
114
|
-
}>;
|
|
115
|
-
<TName extends string>(dbName: TName, fieldConfig?: unknown): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
116
|
-
name: TName;
|
|
117
|
-
dataType: "custom";
|
|
118
|
-
columnType: "PgCustomColumn";
|
|
119
|
-
data: Buffer<ArrayBufferLike>;
|
|
120
|
-
driverParam: string | BlobValueWrapper | Uint8Array<ArrayBufferLike>;
|
|
121
|
-
enumValues: undefined;
|
|
122
90
|
}>;
|
|
123
91
|
};
|
|
124
92
|
export declare const duckDbInet: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
125
|
-
|
|
126
|
-
dataType: "custom";
|
|
127
|
-
columnType: "PgCustomColumn";
|
|
93
|
+
dataType: 'custom';
|
|
128
94
|
data: string;
|
|
129
95
|
driverParam: string;
|
|
130
|
-
enumValues: undefined;
|
|
131
96
|
}>;
|
|
132
97
|
interface IntervalParts {
|
|
133
98
|
months: number | string;
|
|
@@ -135,12 +100,9 @@ interface IntervalParts {
|
|
|
135
100
|
micros: bigint | number | string;
|
|
136
101
|
}
|
|
137
102
|
export declare const duckDbInterval: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
138
|
-
|
|
139
|
-
dataType: "custom";
|
|
140
|
-
columnType: "PgCustomColumn";
|
|
103
|
+
dataType: 'custom';
|
|
141
104
|
data: string;
|
|
142
105
|
driverParam: string | IntervalParts;
|
|
143
|
-
enumValues: undefined;
|
|
144
106
|
}>;
|
|
145
107
|
type TimestampMode = 'date' | 'string';
|
|
146
108
|
type DuckDbTimestampType = 'TIMESTAMP' | 'TIMESTAMPTZ' | 'TIMESTAMP_S' | 'TIMESTAMP_MS' | 'TIMESTAMP_NS';
|
|
@@ -156,31 +118,22 @@ interface TimeOptions {
|
|
|
156
118
|
withTimezone?: boolean;
|
|
157
119
|
duckDbType?: DuckDbTimeType;
|
|
158
120
|
}
|
|
159
|
-
export declare const duckDbTimestamp: <TMode extends TimestampMode =
|
|
121
|
+
export declare const duckDbTimestamp: <TMode extends TimestampMode = 'date'>(name: string, options?: TimestampOptions & {
|
|
160
122
|
mode?: TMode;
|
|
161
|
-
}) => import("drizzle-orm")
|
|
162
|
-
|
|
163
|
-
dataType: "custom";
|
|
164
|
-
columnType: "PgCustomColumn";
|
|
123
|
+
}) => import("drizzle-orm/pg-core").Set$Type<import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
124
|
+
dataType: 'custom';
|
|
165
125
|
data: string | Date;
|
|
166
|
-
driverParam: string |
|
|
167
|
-
enumValues: undefined;
|
|
126
|
+
driverParam: string | Date | SQL<unknown> | TimestampValueWrapper;
|
|
168
127
|
}>, TMode extends "string" ? string : string | Date>;
|
|
169
128
|
export declare const duckDbDate: (name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
170
|
-
|
|
171
|
-
dataType: "custom";
|
|
172
|
-
columnType: "PgCustomColumn";
|
|
129
|
+
dataType: 'custom';
|
|
173
130
|
data: string | Date;
|
|
174
131
|
driverParam: string | Date;
|
|
175
|
-
enumValues: undefined;
|
|
176
132
|
}>;
|
|
177
133
|
export declare const duckDbTime: (name: string, options?: TimeOptions) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
|
|
178
|
-
|
|
179
|
-
dataType: "custom";
|
|
180
|
-
columnType: "PgCustomColumn";
|
|
134
|
+
dataType: 'custom';
|
|
181
135
|
data: string;
|
|
182
136
|
driverParam: string | bigint;
|
|
183
|
-
enumValues: undefined;
|
|
184
137
|
}>;
|
|
185
138
|
export declare function duckDbArrayContains<T>(column: SQLWrapper, values: ArrayPredicateValue<T>): SQL;
|
|
186
139
|
export declare function duckDbArrayContained<T>(column: SQLWrapper, values: ArrayPredicateValue<T>): SQL;
|
package/dist/dialect.d.ts
CHANGED
|
@@ -1,24 +1,14 @@
|
|
|
1
1
|
import { entityKind } from 'drizzle-orm/entity';
|
|
2
2
|
import type { MigrationConfig, MigrationMeta } from 'drizzle-orm/migrator';
|
|
3
|
-
import { PgDialect
|
|
4
|
-
import {
|
|
5
|
-
import type
|
|
6
|
-
import {
|
|
7
|
-
import type
|
|
8
|
-
/**
|
|
9
|
-
* Query typing for params bound to a non-array column. DuckDB sessions never
|
|
10
|
-
* coerce these params from Postgres array literal strings.
|
|
11
|
-
* @internal
|
|
12
|
-
*/
|
|
13
|
-
export declare const DUCKDB_SCALAR_COLUMN_TYPING: QueryTypingsValue;
|
|
3
|
+
import { PgDialect } from 'drizzle-orm/pg-core';
|
|
4
|
+
import { type SQL } from 'drizzle-orm';
|
|
5
|
+
import { type BuildRelationalQueryResult } from 'drizzle-orm/relations';
|
|
6
|
+
import type { Query } from 'drizzle-orm/sql/sql';
|
|
7
|
+
import { type ParamKind } from './codecs.ts';
|
|
14
8
|
/** @internal */
|
|
15
|
-
export declare function
|
|
16
|
-
/**
|
|
17
|
-
|
|
18
|
-
* bind its empty array as an empty list.
|
|
19
|
-
* @internal
|
|
20
|
-
*/
|
|
21
|
-
export declare const DUCKDB_ARRAY_COLUMN_TYPING: QueryTypingsValue;
|
|
9
|
+
export declare function paramKindsOf(query: object): ReadonlyMap<number, ParamKind> | undefined;
|
|
10
|
+
/** @internal */
|
|
11
|
+
export declare function mapperFieldsOf(mapper: object): readonly unknown[] | undefined;
|
|
22
12
|
/**
|
|
23
13
|
* DuckLake has no sequences, primary keys or indexes, so a journal in a
|
|
24
14
|
* DuckLake catalog is a plain table. pg_duckdb and other clients without
|
|
@@ -26,7 +16,7 @@ export declare const DUCKDB_ARRAY_COLUMN_TYPING: QueryTypingsValue;
|
|
|
26
16
|
*/
|
|
27
17
|
type MigrationSession = {
|
|
28
18
|
execute(query: SQL): PromiseLike<unknown>;
|
|
29
|
-
|
|
19
|
+
objects<T>(query: SQL): PromiseLike<T[]>;
|
|
30
20
|
transaction<T>(callback: (tx: {
|
|
31
21
|
execute(query: SQL): PromiseLike<unknown>;
|
|
32
22
|
}) => Promise<T>): Promise<T>;
|
|
@@ -35,25 +25,10 @@ export declare class DuckDBDialect extends PgDialect {
|
|
|
35
25
|
private options;
|
|
36
26
|
static readonly [entityKind]: string;
|
|
37
27
|
private savepointsSupported;
|
|
38
|
-
constructor(options?:
|
|
28
|
+
constructor(options?: {
|
|
39
29
|
qualifyRawJoinColumns?: boolean;
|
|
40
30
|
decimalMode?: 'number' | 'string';
|
|
41
31
|
});
|
|
42
|
-
/**
|
|
43
|
-
* @deprecated Pg JSON/JSONB params now throw while the query is built. This
|
|
44
|
-
* method is a no-op and will be removed in the next major version.
|
|
45
|
-
*/
|
|
46
|
-
resetPgJsonFlag(): void;
|
|
47
|
-
/**
|
|
48
|
-
* @deprecated Pg JSON/JSONB params now throw while the query is built. This
|
|
49
|
-
* method is a no-op and will be removed in the next major version.
|
|
50
|
-
*/
|
|
51
|
-
markPgJsonDetected(): void;
|
|
52
|
-
/**
|
|
53
|
-
* @deprecated Pg JSON/JSONB params now throw while the query is built. This
|
|
54
|
-
* method is a no-op and will be removed in the next major version.
|
|
55
|
-
*/
|
|
56
|
-
assertNoPgJsonColumns(): void;
|
|
57
32
|
escapeName(name: string): string;
|
|
58
33
|
/**
|
|
59
34
|
* Check if savepoints are known to be unsupported for this dialect instance.
|
|
@@ -68,8 +43,7 @@ export declare class DuckDBDialect extends PgDialect {
|
|
|
68
43
|
*/
|
|
69
44
|
markSavepointsUnsupported(): void;
|
|
70
45
|
migrate(migrations: MigrationMeta[], session: MigrationSession, config: MigrationConfig | string): Promise<void>;
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
sqlToQuery(sqlObj: SQL, invokeSource?: 'indexes' | undefined): QueryWithTypings;
|
|
46
|
+
buildRelationalQuery(config: Parameters<PgDialect['buildRelationalQuery']>[0]): BuildRelationalQueryResult;
|
|
47
|
+
sqlToQuery(sqlObj: SQL, invokeSource?: Parameters<PgDialect['sqlToQuery']>[1]): Query;
|
|
74
48
|
}
|
|
75
49
|
export {};
|
package/dist/driver.d.ts
CHANGED
|
@@ -1,27 +1,28 @@
|
|
|
1
1
|
import { DuckDBInstance } from '@duckdb/node-api';
|
|
2
2
|
import { entityKind } from 'drizzle-orm/entity';
|
|
3
3
|
import type { Logger } from 'drizzle-orm/logger';
|
|
4
|
-
import {
|
|
5
|
-
import type {
|
|
6
|
-
import type {
|
|
7
|
-
import {
|
|
8
|
-
import {
|
|
4
|
+
import { PgAsyncDatabase } from 'drizzle-orm/pg-core/async/db';
|
|
5
|
+
import type { PgAsyncSelectBuilder } from 'drizzle-orm/pg-core/async/select';
|
|
6
|
+
import type { SelectedFields } from 'drizzle-orm/pg-core/query-builders/select.types';
|
|
7
|
+
import type { PgColumn, PgTable, PgTransactionConfig } from 'drizzle-orm/pg-core';
|
|
8
|
+
import type { AnyRelations, EmptyRelations } from 'drizzle-orm/relations';
|
|
9
|
+
import type { DrizzleConfig } from 'drizzle-orm/utils';
|
|
9
10
|
import type { SQL, SQLWrapper } from 'drizzle-orm/sql/sql';
|
|
11
|
+
import type { InferInsertModel } from 'drizzle-orm/table';
|
|
10
12
|
import type { WithSubquery } from 'drizzle-orm/subquery';
|
|
11
13
|
import type { DuckDBClientLike, DuckDBQueryResultHKT, DuckDBTransaction } from './session.ts';
|
|
12
14
|
import { DuckDBSession } from './session.ts';
|
|
13
15
|
import { DuckDBDialect } from './dialect.ts';
|
|
14
16
|
import { type DuckDBSelectBuilder } from './select-builder.ts';
|
|
15
|
-
import type { ExecuteBatchesRawChunk, ExecuteInBatchesOptions, RowData } from './client.ts';
|
|
17
|
+
import type { DateParamType, ExecuteBatchesRawChunk, ExecuteInBatchesOptions, RowData } from './client.ts';
|
|
16
18
|
import { type DuckDBPoolConfig, type PoolPreset } from './pool.ts';
|
|
17
|
-
import { type PreparedStatementCacheConfig, type PrepareCacheOption } from './options.ts';
|
|
18
19
|
import { type DuckLakeConfig } from './ducklake.ts';
|
|
19
20
|
export interface PgDriverOptions {
|
|
20
21
|
decimalMode?: 'number' | 'string';
|
|
22
|
+
dateParams?: DateParamType;
|
|
21
23
|
logger?: Logger;
|
|
22
24
|
rejectStringArrayLiterals?: boolean;
|
|
23
25
|
arrayLiteralWarning?: (query: string) => void;
|
|
24
|
-
prepareCache?: PreparedStatementCacheConfig;
|
|
25
26
|
}
|
|
26
27
|
export declare class DuckDBDriver {
|
|
27
28
|
private client;
|
|
@@ -29,7 +30,7 @@ export declare class DuckDBDriver {
|
|
|
29
30
|
private options;
|
|
30
31
|
static readonly [entityKind]: string;
|
|
31
32
|
constructor(client: DuckDBClientLike, dialect: DuckDBDialect, options?: PgDriverOptions);
|
|
32
|
-
createSession(
|
|
33
|
+
createSession<TRelations extends AnyRelations = EmptyRelations>(relations: TRelations): DuckDBSession<TRelations>;
|
|
33
34
|
}
|
|
34
35
|
/** Connection configuration when using path-based connection */
|
|
35
36
|
export interface DuckDBConnectionConfig {
|
|
@@ -38,60 +39,78 @@ export interface DuckDBConnectionConfig {
|
|
|
38
39
|
/** DuckDB instance options (e.g., motherduck_token) */
|
|
39
40
|
options?: Record<string, string>;
|
|
40
41
|
}
|
|
41
|
-
export interface DuckDBDrizzleConfig<
|
|
42
|
+
export interface DuckDBDrizzleConfig<TRelations extends AnyRelations = EmptyRelations> extends Pick<DrizzleConfig<TRelations>, 'logger' | 'relations'> {
|
|
42
43
|
rejectStringArrayLiterals?: boolean;
|
|
43
44
|
arrayLiteralWarning?: (query: string) => void;
|
|
44
|
-
prepareCache?: PrepareCacheOption;
|
|
45
45
|
/** Opt into legacy heuristic qualification of raw SQL join operands. */
|
|
46
46
|
qualifyRawJoinColumns?: boolean;
|
|
47
47
|
/** Opt into exact DECIMAL strings across execution paths. */
|
|
48
48
|
decimalMode?: 'number' | 'string';
|
|
49
|
+
/**
|
|
50
|
+
* How a bare `Date` parameter binds, as in sql`${new Date()}`. The default
|
|
51
|
+
* 'timestamp' binds its UTC wall time as a naive TIMESTAMP, which DuckDB
|
|
52
|
+
* reads in the session TimeZone when it compares it with a TIMESTAMPTZ.
|
|
53
|
+
* 'timestamptz' binds the instant instead. Typed columns are not affected.
|
|
54
|
+
*/
|
|
55
|
+
dateParams?: DateParamType;
|
|
49
56
|
/** Pool configuration. Use preset name, size config, or false to disable. */
|
|
50
57
|
pool?: DuckDBPoolConfig | PoolPreset | false;
|
|
51
58
|
/** Optional DuckLake configuration */
|
|
52
59
|
ducklake?: DuckLakeConfig;
|
|
53
60
|
}
|
|
54
|
-
export interface DuckDBDrizzleConfigWithConnection<
|
|
61
|
+
export interface DuckDBDrizzleConfigWithConnection<TRelations extends AnyRelations = EmptyRelations> extends DuckDBDrizzleConfig<TRelations> {
|
|
55
62
|
/** Connection string or config object */
|
|
56
63
|
connection: string | DuckDBConnectionConfig;
|
|
57
64
|
}
|
|
58
|
-
export interface DuckDBDrizzleConfigWithClient<
|
|
65
|
+
export interface DuckDBDrizzleConfigWithClient<TRelations extends AnyRelations = EmptyRelations> extends DuckDBDrizzleConfig<TRelations> {
|
|
59
66
|
/** Explicit client (connection or pool) */
|
|
60
67
|
client: DuckDBClientLike;
|
|
61
68
|
}
|
|
62
|
-
export declare function drizzle<
|
|
63
|
-
export declare function drizzle<
|
|
64
|
-
export declare function drizzle<
|
|
65
|
-
export declare function drizzle<
|
|
66
|
-
export declare function drizzle<
|
|
67
|
-
export declare class DuckDBDatabase<
|
|
69
|
+
export declare function drizzle<TRelations extends AnyRelations = EmptyRelations>(connectionString: string): Promise<DuckDBDatabase<TRelations>>;
|
|
70
|
+
export declare function drizzle<TRelations extends AnyRelations = EmptyRelations>(connectionString: string, config: DuckDBDrizzleConfig<TRelations>): Promise<DuckDBDatabase<TRelations>>;
|
|
71
|
+
export declare function drizzle<TRelations extends AnyRelations = EmptyRelations>(config: DuckDBDrizzleConfigWithConnection<TRelations>): Promise<DuckDBDatabase<TRelations>>;
|
|
72
|
+
export declare function drizzle<TRelations extends AnyRelations = EmptyRelations>(config: DuckDBDrizzleConfigWithClient<TRelations>): DuckDBDatabase<TRelations>;
|
|
73
|
+
export declare function drizzle<TRelations extends AnyRelations = EmptyRelations>(client: DuckDBClientLike, config?: DuckDBDrizzleConfig<TRelations>): DuckDBDatabase<TRelations>;
|
|
74
|
+
export declare class DuckDBDatabase<TRelations extends AnyRelations = EmptyRelations> extends PgAsyncDatabase<DuckDBQueryResultHKT, TRelations> {
|
|
68
75
|
readonly dialect: DuckDBDialect;
|
|
69
|
-
readonly session: DuckDBSession<
|
|
76
|
+
readonly session: DuckDBSession<TRelations>;
|
|
70
77
|
static readonly [entityKind]: string;
|
|
71
78
|
/** The underlying connection or pool */
|
|
72
79
|
readonly $client: DuckDBClientLike;
|
|
73
80
|
/** The DuckDB instance (when created from connection string) */
|
|
74
81
|
readonly $instance?: DuckDBInstance;
|
|
75
|
-
constructor(dialect: DuckDBDialect, session: DuckDBSession<
|
|
82
|
+
constructor(dialect: DuckDBDialect, session: DuckDBSession<TRelations>, relations: TRelations, client: DuckDBClientLike, instance?: DuckDBInstance);
|
|
76
83
|
/**
|
|
77
84
|
* Close the database connection pool and instance.
|
|
78
85
|
* Should be called when shutting down the application.
|
|
79
86
|
*/
|
|
80
87
|
close(): Promise<void>;
|
|
81
88
|
private selectMethods;
|
|
82
|
-
with(...queries: WithSubquery[]): ReturnType<
|
|
89
|
+
with(...queries: WithSubquery[]): ReturnType<PgAsyncDatabase<DuckDBQueryResultHKT, TRelations>['with']>;
|
|
83
90
|
select(): DuckDBSelectBuilder<undefined>;
|
|
84
91
|
select<TSelection extends SelectedFields>(fields: TSelection): DuckDBSelectBuilder<TSelection>;
|
|
85
|
-
selectDistinct():
|
|
86
|
-
selectDistinct<TSelection extends SelectedFields>(fields: TSelection):
|
|
87
|
-
selectDistinctOn(on: (PgColumn | SQLWrapper)[]):
|
|
88
|
-
selectDistinctOn<TSelection extends SelectedFields>(on: (PgColumn | SQLWrapper)[], fields: TSelection):
|
|
92
|
+
selectDistinct(): PgAsyncSelectBuilder<undefined>;
|
|
93
|
+
selectDistinct<TSelection extends SelectedFields>(fields: TSelection): PgAsyncSelectBuilder<TSelection>;
|
|
94
|
+
selectDistinctOn(on: (PgColumn | SQLWrapper)[]): PgAsyncSelectBuilder<undefined>;
|
|
95
|
+
selectDistinctOn<TSelection extends SelectedFields>(on: (PgColumn | SQLWrapper)[], fields: TSelection): PgAsyncSelectBuilder<TSelection>;
|
|
89
96
|
executeBatches<T extends RowData = RowData>(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<T[], void, void>;
|
|
90
97
|
executeBatchesRaw(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<ExecuteBatchesRawChunk, void, void>;
|
|
91
98
|
executeArrow(query: SQL): Promise<unknown>;
|
|
92
99
|
/**
|
|
93
|
-
*
|
|
94
|
-
*
|
|
100
|
+
* Append rows with DuckDB's appender instead of an INSERT statement. It
|
|
101
|
+
* skips SQL building and parameter binding, so large batches load far
|
|
102
|
+
* faster than `db.insert().values()`. Missing columns take their default.
|
|
103
|
+
* Returns the number of rows appended.
|
|
104
|
+
*
|
|
105
|
+
* The appender has no RETURNING or ON CONFLICT, and it cannot take values
|
|
106
|
+
* that a column encodes as SQL, such as structs. Outside a transaction a
|
|
107
|
+
* failure can leave earlier rows of the batch in the table. Use
|
|
108
|
+
* `db.transaction((tx) => tx.appendRows(...))` for all or nothing.
|
|
109
|
+
*/
|
|
110
|
+
appendRows<TTable extends PgTable>(table: TTable, rows: readonly InferInsertModel<TTable>[]): Promise<number>;
|
|
111
|
+
/**
|
|
112
|
+
* Run a transaction. DuckDB has no SET TRANSACTION statement, so passing
|
|
113
|
+
* `config` rejects before the transaction begins.
|
|
95
114
|
*/
|
|
96
|
-
transaction<T>(transaction: (tx: DuckDBTransaction<
|
|
115
|
+
transaction<T>(transaction: (tx: DuckDBTransaction<TRelations>) => Promise<T>, config?: PgTransactionConfig): Promise<T>;
|
|
97
116
|
}
|