@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 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.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 |
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
- // Per-connection prepared statement cache (default: disabled)
166
- prepareCache: { size: 32 },
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
- // Map camelCase keys to snake_case column names
178
- casing: 'snake_case',
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
- - The `config` argument (`isolationLevel`, `accessMode`, `deferrable`) is deprecated and ignored with a one-time warning, because DuckDB has no `SET TRANSACTION`.
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()` helper names remain as deprecated aliases. See [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.
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 is ignored |
315
+ | Transactions | No savepoints (nested transactions reuse the outer one). Config rejects |
316
316
  | JSON/JSONB columns | Use `duckDbJson()` instead |
317
- | Prepared statements | Optional per-connection cache via `prepareCache`, no named 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>;
@@ -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
- name: string;
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
- name: string;
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
- name: string;
51
- dataType: "custom";
52
- columnType: "PgCustomColumn";
44
+ dataType: 'custom';
53
45
  data: TData;
54
- driverParam: MapValueWrapper | TData;
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
- name: string;
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
- name: string;
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
- name: string;
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
- name: "";
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
- <TConfig extends Record<string, any>>(fieldConfig?: TConfig | undefined): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
108
- name: "";
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
- name: string;
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
- name: string;
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 = "date">(name: string, options?: TimestampOptions & {
121
+ export declare const duckDbTimestamp: <TMode extends TimestampMode = 'date'>(name: string, options?: TimestampOptions & {
160
122
  mode?: TMode;
161
- }) => import("drizzle-orm").$Type<import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
162
- name: string;
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 | TimestampValueWrapper | Date | SQL<unknown>;
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
- name: string;
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
- name: string;
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, type PgColumn, type PgTable } from 'drizzle-orm/pg-core';
4
- import { SQL, type DriverValueEncoder, type QueryTypingsValue } from 'drizzle-orm';
5
- import type { BuildRelationalQueryResult } from 'drizzle-orm/relations';
6
- import { type QueryWithTypings } from 'drizzle-orm/sql/sql';
7
- import type { RelationalSelectionItem } from './sql/result-mapper.ts';
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 relationalSelectionOf(query: object): readonly RelationalSelectionItem[] | undefined;
16
- /**
17
- * Query typing for params bound to a pg-core array column, so sessions can
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
- all<T>(query: SQL): PromiseLike<T[]>;
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?: ConstructorParameters<typeof PgDialect>[0] & {
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
- prepareTyping(encoder: DriverValueEncoder<unknown, unknown>): QueryTypingsValue;
72
- buildRelationalQueryWithoutPK(config: Parameters<PgDialect['buildRelationalQueryWithoutPK']>[0]): BuildRelationalQueryResult<PgTable, PgColumn>;
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 { PgDatabase } from 'drizzle-orm/pg-core/db';
5
- import type { PgSelectBuilder, SelectedFields } from 'drizzle-orm/pg-core/query-builders';
6
- import type { PgColumn, PgTransactionConfig } from 'drizzle-orm/pg-core';
7
- import { type ExtractTablesWithRelations, type RelationalSchemaConfig, type TablesRelationalConfig } from 'drizzle-orm/relations';
8
- import { type DrizzleConfig } from 'drizzle-orm/utils';
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(schema: RelationalSchemaConfig<TablesRelationalConfig> | undefined): DuckDBSession<Record<string, unknown>, TablesRelationalConfig>;
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<TSchema extends Record<string, unknown> = Record<string, never>> extends DrizzleConfig<TSchema> {
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<TSchema extends Record<string, unknown> = Record<string, never>> extends DuckDBDrizzleConfig<TSchema> {
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<TSchema extends Record<string, unknown> = Record<string, never>> extends DuckDBDrizzleConfig<TSchema> {
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<TSchema extends Record<string, unknown> = Record<string, never>>(connectionString: string): Promise<DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
63
- export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(connectionString: string, config: DuckDBDrizzleConfig<TSchema>): Promise<DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
64
- export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(config: DuckDBDrizzleConfigWithConnection<TSchema>): Promise<DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>>;
65
- export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(config: DuckDBDrizzleConfigWithClient<TSchema>): DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>;
66
- export declare function drizzle<TSchema extends Record<string, unknown> = Record<string, never>>(client: DuckDBClientLike, config?: DuckDBDrizzleConfig<TSchema>): DuckDBDatabase<TSchema, ExtractTablesWithRelations<TSchema>>;
67
- export declare class DuckDBDatabase<TFullSchema extends Record<string, unknown> = Record<string, never>, TSchema extends TablesRelationalConfig = ExtractTablesWithRelations<TFullSchema>> extends PgDatabase<DuckDBQueryResultHKT, TFullSchema, TSchema> {
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<TFullSchema, TSchema>;
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<TFullSchema, TSchema>, schema: RelationalSchemaConfig<TSchema> | undefined, client: DuckDBClientLike, instance?: DuckDBInstance);
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<PgDatabase<DuckDBQueryResultHKT, TFullSchema, TSchema>['with']>;
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(): PgSelectBuilder<undefined>;
86
- selectDistinct<TSelection extends SelectedFields>(fields: TSelection): PgSelectBuilder<TSelection>;
87
- selectDistinctOn(on: (PgColumn | SQLWrapper)[]): PgSelectBuilder<undefined>;
88
- selectDistinctOn<TSelection extends SelectedFields>(on: (PgColumn | SQLWrapper)[], fields: TSelection): PgSelectBuilder<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
- * Run a transaction. The `config` argument is deprecated: DuckDB has no
94
- * SET TRANSACTION statement, so it is ignored with a one-time warning.
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<TFullSchema, TSchema>) => Promise<T>, config?: PgTransactionConfig): Promise<T>;
115
+ transaction<T>(transaction: (tx: DuckDBTransaction<TRelations>) => Promise<T>, config?: PgTransactionConfig): Promise<T>;
97
116
  }