# @duckdbfan/drizzle-duckdb 中文文档

规范地址：https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/

版本：2\.5\.0
npm 元数据更新时间：2026-11-09T20:34:30.419Z
中文译文更新时间：2026-11-12T23:42:27.502Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40duckdbfan/drizzle-duckdb
原文对照：https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/?lang=original
项目主页：https://github.com/leonardovida/drizzle-duckdb#readme
源码仓库：https://github.com/leonardovida/drizzle-duckdb

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：666 kB，46 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.17
- 运行依赖：1 个
- peer 依赖：drizzle-orm \>=0\.40\.1 \<0\.46\.0，@duckdb/node-api \>=1\.4\.4 \<1\.6\.0 \|\| \>=1\.4\.4-r\.1 \<1\.4\.5 \|\| \>=1\.4\.5-r\.1 \<1\.4\.6 \|\| \>=1\.5\.0-r\.1 \<1\.5\.1 \|\| \>=1\.5\.1-r\.1 \<1\.5\.2 \|\| \>=1\.5\.2-r\.1 \<1\.5\.3 \|\| \>=1\.5\.3-r\.1 \<1\.5\.4 \|\| \>=1\.5\.4-r\.1 \<1\.5\.5 \|\| \>=1\.5\.5-r\.1 \<1\.5\.6 \|\| \>=1\.5\.6-r\.1 \<1\.5\.7
- 首次发布：2025-03-17T16:51:53.778Z
- 最新版本发布：2026-11-09T20:34:30.064Z
- 近 30 天下载量：24187（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：45（近 12 个月 38 个）

## 中文简介

用于 DuckDB 的细管ORM 客户端. 基于细雨"Postgres"客户端.

## 安装

```sh
npm install @duckdbfan/drizzle-duckdb
```

也可以使用：`pnpm add @duckdbfan/drizzle-duckdb`、`yarn add @duckdbfan/drizzle-duckdb`、`bun add @duckdbfan/drizzle-duckdb`

## README

# Drizzle DuckDB 盘点鸭

### 用于 DuckDB 方言 [滴入外科手术](https://orm.drizzle.team/)

[![npm version](https://img.shields.io/npm/v/@duckdbfan/drizzle-duckdb)](https://www.npmjs.com/package/@duckdbfan/drizzle-duckdb) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

[文档](https://leonardovida.github.io/drizzle-duckdb/) 二. 支助 [LLM 背景](https://leonardovida.github.io/drizzle-duckdb/llms.txt) 二. 支助 [实例](https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/example) 二. 支助 [捐款](https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/#readme-contributing)

  

**Drizzle DuckDB 盘点鸭** 带来 [滴入外科手术](https://orm.drizzle.team/) 改为 [DuckDB 函数](https://duckdb.org/),即进程内分析数据库。 DuckDB上方有Drizzle的型式安全查询构建器,迁移和TypeScript推论. 它与记忆数据库,本地文件, [妈妈](https://motherduck.com/) 并运行 Postgres 服务器 [`pg_duckdb`](https://github.com/duckdb/pg_duckdb)。 。 。 .

> **状态 :** 实验 查询建筑,迁移和类型推论稳定. 一些DuckDB特有的类型和边缘案例仍在完善中.

每个文件页都有 **标记下 (raw)** 按钮,带有LLM友好源.

## 安装

```bash
bun add @duckdbfan/drizzle-duckdb drizzle-orm @duckdb/node-api
# or: npm install / pnpm add with the same packages
```

| 所需经费 | 支持的版本 |
| --- | --- |
| `drizzle-orm` | 0.40.1或较新,低于0.46.0 |
| `@duckdb/node-api` | 1.4.4或较新,低于1.6.0,包括 `-r.N` 建筑物,如 `1.5.6-r.1` |
| 运行时间 | 节点18.17或较新(建议22或24),或Bun |

## 快速启动

```typescript
import { drizzle } from '@duckdbfan/drizzle-duckdb';
import { sql } from 'drizzle-orm';
import { integer, pgTable, text } from 'drizzle-orm/pg-core';

const users = pgTable('users', {
  id: integer('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull(),
});

const db = await drizzle(':memory:');

await db.execute(sql`
  CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT NOT NULL
  )
`);

await db.insert(users).values([
  { id: 1, name: 'Alice', email: 'alice@example.com' },
  { id: 2, name: 'Bob', email: 'bob@example.com' },
]);

const allUsers = await db.select().from(users);
//    ^? { id: number; name: string; email: string }[]

await db.close();
```

Schemas 使用常规 `drizzle-orm/pg-core` 建造者(`pgTable`, (中文(简体) ), `pgSchema` 所有标准的 Drizzle 查询方法都有效。 DuckDB SQL基本上是Postgres相容的,而方言则在不兼容的地方调整了查询.

## 连接中

通过一个路径, 驱动程序为您创建一个连接池 . `await db.close()` 关闭它.

```typescript
import { drizzle } from '@duckdbfan/drizzle-duckdb';

// In-memory
const db = await drizzle(':memory:');

// Local file (created if missing)
const db = await drizzle('./my-database.duckdb');

// MotherDuck
const db = await drizzle({
  connection: {
    path: 'md:my_database',
    options: { motherduck_token: process.env.MOTHERDUCK_TOKEN },
  },
});

// DuckLake catalog
const db = await drizzle(':memory:', {
  ducklake: {
    catalog: './ducklake.duckdb',
    attachOptions: { dataPath: './ducklake-data' },
  },
});
```

使用同一文件路径的呼叫在一个过程中共享一个 DuckDB 实例,所以它们可以互相看到对方的写作. `:memory:` 永远不能共享.

你可以通过自己的连接,游泳池或 `pg_duckdb` 客户端。 这些电话是同步的:

```typescript
import { DuckDBInstance } from '@duckdb/node-api';
import pg from 'pg';

// Existing DuckDB connection
const instance = await DuckDBInstance.create(':memory:');
const db = drizzle(await instance.connect());

// Postgres server with pg_duckdb. A pg.Client works too.
const db = drizzle(new pg.Pool({ connectionString: process.env.DATABASE_URL }));
```

A 类 `pg.Pool` 包裹着 `createPgDuckConnectionPool()`,所以每笔交易运行在一个集合客户端和 `await db.close()` 结束游泳池.

见 [数据库连接](https://leonardovida.github.io/drizzle-duckdb/core/connection) 用于单子和无服务器模式.

## 连接集合

DuckDB每个连接运行一个查询,因此上面的路径表会创建一个池(默认大小为4).

-   设定大小或 MotherDuck 预设 : `pool: { size: 8 }`, (中文(简体) ), `pool: 'jumbo'` 或者说 `pool: 'giga'`。 。 。 .
-   电桶回收: `pool: { size: 8, idleTimeoutMs: 60_000, maxLifetimeMs: 10 * 60_000 }`。 。 。 .
-   禁用集合 : `pool: false`。 。 。 .
-   交易在他们整个一生中 都连接在一起.
-   `pool` 当您通过连接或池实例时被忽略.

需要时自己创建游泳池 `setup` 钩子或想要分享它 `drizzle()` 实例 :

```typescript
import { DuckDBInstance } from '@duckdb/node-api';
import { createDuckDBConnectionPool, drizzle } from '@duckdbfan/drizzle-duckdb';

const instance = await DuckDBInstance.create('md:', {
  motherduck_token: process.env.MOTHERDUCK_TOKEN,
});
const pool = createDuckDBConnectionPool(instance, {
  size: 8,
  acquireTimeout: 20_000,
  maxWaitingRequests: 200,
  maxLifetimeMs: 10 * 60_000,
  idleTimeoutMs: 60_000,
});
const db = drizzle(pool);
console.log(pool.stats()); // Leases, queue depth, waits, recycling and timeouts
```

`acquireTimeout` 限制游泳池队列中的时间。 连接创建和设置在此之后运行, 而此选项没有最后期限 。 检查 `pool.stats()` 由于更多的连接可以与 DuckDB 本身的查询线索相竞争,所以在增加池大小之前.

## 配置

```typescript
import { DefaultLogger } from 'drizzle-orm';

const db = await drizzle(':memory:', {
  // Log every query
  logger: new DefaultLogger(),

  // Pool size, preset, or timeout and recycling options
  pool: { size: 8, idleTimeoutMs: 60_000 },

  // Bind a bare Date in sql`...` as TIMESTAMPTZ instead of a naive TIMESTAMP
  dateParams: 'timestamptz', // Default: 'timestamp'

  // Preserve DECIMAL values as strings in raw, streaming and nested reads
  decimalMode: 'string', // Default: 'number'

  // Legacy raw SQL join qualification heuristic, opt in only if needed
  qualifyRawJoinColumns: false,

  // Throw on Postgres-style array literals like '{1,2,3}' (default: false)
  rejectStringArrayLiterals: false,

  // Map camelCase keys to snake_case column names
  casing: 'snake_case',

  // Schema for relational queries
  schema: mySchema,
});
```

`pool` 财务报告和审定财务报表 `ducklake` 仅适用于路径和 `{ connection }` 表单。 其他备选方案也与 `drizzle(connection, { ... })`。见 [配置](https://leonardovida.github.io/drizzle-duckdb/reference/configuration) 完整名单.

## DuckDB 类型

DuckDB 专列助手 : `duckDbList`, (中文(简体) ), `duckDbArray`, (中文(简体) ), `duckDbStruct`, (中文(简体) ), `duckDbUnion`, (中文(简体) ), `duckDbMap`, (中文(简体) ), `duckDbJson`, (中文(简体) ), `duckDbBlob`, (中文(简体) ), `duckDbInet`, (中文(简体) ), `duckDbInterval`, (中文(简体) ), `duckDbTimestamp`, (中文(简体) ), `duckDbDate` 财务报告和审定财务报表 `duckDbTime`。 。 。 .

-   `duckDbTimestamp` 财务报告和审定财务报表 `duckDbTime` 可以保存存储变体, 如 `TIMESTAMP_NS`, (中文(简体) ), `TIMESTAMP_MS`, (中文(简体) ), `TIMESTAMP_S`, (中文(简体) ), `TIME_NS` 财务报告和审定财务报表 `TIME WITH TIME ZONE` 通过 `duckDbType` 财务报告和审定财务报表 `withTimezone` 选项.
-   邮资 `json` 财务报告和审定财务报表 `jsonb` 栏被拒绝。 使用 `duckDbJson()`。 。 。 .
-   浏览器安全导入在 `@duckdbfan/drizzle-duckdb/helpers`. 内观出此道.

见 [列类型](https://leonardovida.github.io/drizzle-duckdb/api/columns) 为全API.

### 阵列

DuckDB 支持 `@>`, (中文(简体) ), `<@` 财务报告和审定财务报表 `&&` 列表和固定大小数组,所以 Drizzle 的 `arrayContains`, (中文(简体) ), `arrayContained` 财务报告和审定财务报表 `arrayOverlaps` 工作不变。 DuckDB 帮助者会发射 `array_has_all` 财务报告和审定财务报表 `array_has_any`数字 :

```typescript
import {
  duckDbArrayContained,
  duckDbArrayContains,
  duckDbArrayOverlaps,
} from '@duckdbfan/drizzle-duckdb';

// Tags include every value
db.select().from(products).where(duckDbArrayContains(products.tags, ['electronics', 'sale']));

// Tags are a subset of the values
db.select().from(products).where(duckDbArrayContained(products.tags, ['electronics', 'sale', 'featured']));

// Tags share at least one value
db.select().from(products).where(duckDbArrayOverlaps(products.tags, ['electronics', 'books']));
```

首选 `array_lower(a, 1)` 财务报告和审定财务报表 `array_upper(a, 1)` 电话重写为 `array_length` 表达式,因为 DuckDB 缺少这些函数.

## 交易

```typescript
await db.transaction(async (tx) => {
  await tx.insert(accounts).values({ balance: 100 });
  await tx.update(accounts).set({ balance: 50 }).where(eq(accounts.id, 1));
});
```

DuckDB 与 Postgres 不同 :

-   没有 `SAVEPOINT`. Nested 交易重新使用外部交易,所以内部回滚会中止所有交易.
-   没有游泳池,其他 `db` 查询在交易打开共享连接时等待,而不是加入它.
-   任何失败的语句都会中止整个交易 。 捕捉回调中的错误不会保留更早的写法 . `db.transaction()` 倒卷而拒之.
-   这个 `config` 参数( e)`isolationLevel`, (中文(简体) ), `accessMode`, (中文(简体) ), `deferrable`)被贬低并被一次性警告而忽略,因为 DuckDB 没有 `SET TRANSACTION`。 。 。 .

## 移徙

```typescript
import { migrate } from '@duckdbfan/drizzle-duckdb';

await migrate(db, { migrationsFolder: './drizzle' });
```

元数据到 `drizzle.__drizzle_migrations` 默认。 同时 `migrate()` 调用每个迁移一次, DuckLake 作为默认目录工作。 见 [移徙](https://leonardovida.github.io/drizzle-duckdb/features/migrations) 用于配置.

## Schema 内览

由 CLI 的现有数据库生成 Drizzle 计划 :

```bash
bunx duckdb-introspect --url ./my-database.duckdb --out ./drizzle/schema.ts
```

或从代码:

```typescript
import { introspect } from '@duckdbfan/drizzle-duckdb';

const result = await introspect(db, {
  schemas: ['public', 'analytics'],
  includeViews: true,
});

console.log(result.files.schemaTs);
```

见 [回顾](https://leonardovida.github.io/drizzle-duckdb/features/introspection) 所有选项.

## 分析员和Duck母亲助手

包件船的可堆叠 SQL 帮助分析工作:

-   OLAP 帮手等 `sumN`, (中文(简体) ), `percentileCont`窗口助手和 `olap()` 分组措施制定者.
-   兰斯矢量,全文和混合搜索.
-   MotherDuck 表用于潜水、飞行、文件列表和访问令牌的功能,以及会话身份缩写等 `mdCurrentEmail()` 财务报告和审定财务报表 `mdIsRoleInSession()`。 。 。 .
-   输入的 MotherDuck AI 构建器 : `mdPromptJev()` 分类文本或图像,并 `mdPrompt()` 生成文本或结构输出.
-   `duckLakeMergeAdjacentFiles()` 为"鸭子"收缩.
-   批量和箭头读取 `db.executeBatches()`, (中文(简体) ), `db.executeBatchesRaw()` 财务报告和审定财务报表 `db.executeArrow()`。 。 。 .
-   快速散装货物通过 `db.appendRows()`,它使用 DuckDB 的附件,而不是INSERT 语句.

```typescript
import { sql } from 'drizzle-orm';
import { mdCreateFlight, mdListDives, mdRunFlight } from '@duckdbfan/drizzle-duckdb';

const dives = await db.execute(sql`
  select id, title, updated_at
  from ${mdListDives({ limit: 10, includeOrgShares: true })}
  order by updated_at desc
`);

const [flight] = await db.execute(sql`
  select flight_id, status
  from ${mdCreateFlight({
    name: 'daily-refresh',
    sourceCode: 'print("hello")',
    scheduleCron: '0 0 * * *',
    maxRuntimeSec: 1_800,
    instanceType: 'F16',
  })}
`);

await db.execute(sql`
  select run_number, status
  from ${mdRunFlight(String(flight.flight_id), { config: { region: 'eu-west-1' } })}
`);
```

年长者 `mdJobs()` 财务报告和审定财务报表 `mdFlights()` 帮助者名称仍为已贬值的别名。 见 [OLAP 帮助者](https://leonardovida.github.io/drizzle-duckdb/api/olap-helpers) 完整列表、飞行选项和日志标记,以及 [妈妈](https://leonardovida.github.io/drizzle-duckdb/integrations/motherduck) 为人工智能的构建者.

## 已知的限制

| 特性 | 状态 |
| --- | --- |
| 基本 CRUD 操作 | 全力支持 |
| 组合和子组合 | 全力支持 |
| 交易 | 没有保存点(已记账的交易重复使用外接点) 。 配置被忽略 |
| JSON/JSONB栏 | 使用 `duckDbJson()` 换成 |
| 发言稿 | 每次跑步都准备好了 没有语句缓存和命名语句 |
| 成果的流出 | 读取 `executeBatches()`,没有光标流线 |
| 同时进行查询 | 每个连接一个查询 。 并行化使用集合 |

见 [限制](https://leonardovida.github.io/drizzle-duckdb/reference/limitations) 详细情况.

## 实例

-   **[Parquet 分析](https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/example/parquet-analytics.ts)**: 未导入表格的 Parquet 文件上的打入选择和分组措施
-   **[母亲Duck NYC出租车](https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/example/motherduck-nyc-taxi.ts)**: 使用连接池查询 MotherDuck 样本 NYC 出租车数据集
-   **[分析盘](https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/example/analytics-dashboard.ts)**:带有 DuckDB 类型和 Parquet 加载的本地内膜分析
-   **[本地鸭湖](https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/example/ducklake-local.ts)** 财务报告和审定财务报表 **[鸭子在妈妈Duck上](https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/example/ducklake-motherduck.ts)**: 附加 DuckLake 目录

从寄存器根中运行 :

```bash
bun example/analytics-dashboard.ts
MOTHERDUCK_TOKEN=your_token bun example/motherduck-nyc-taxi.ts
```

见 [实例/README.md](https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/example/README.md) 完整名单.

## 捐款

欢迎捐款。 见 [捐款额](https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/CONTRIBUTING.md) 指南和指南 [警卫](https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/SECURITY.md) 报告脆弱性.

```bash
bun install      # install dependencies
bun run test     # run tests (Vitest, not `bun test`)
bun run t        # watch mode with the UI
bun run build    # build dist/
```

包含新特性的测试 `test/<feature>.test.ts`,注意您碰到的 DuckDB 怪事, 并使用简短的强制任务 .

## 许可证

[阿帕奇 - 2.0](https://npmcn.com/package/%40duckdbfan/drizzle-duckdb/LICENSE)

## 常见问题

### @duckdbfan/drizzle-duckdb 是什么？

用于 DuckDB 的细管ORM 客户端\. 基于细雨"Postgres"客户端\.

### 如何安装 @duckdbfan/drizzle-duckdb？

在项目目录运行 npm install @duckdbfan/drizzle-duckdb，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：drizzle-orm（\>=0\.40\.1 \<0\.46\.0）、@duckdb/node-api（\>=1\.4\.4 \<1\.6\.0 \|\| \>=1\.4\.4-r\.1 \<1\.4\.5 \|\| \>=1\.4\.5-r\.1 \<1\.4\.6 \|\| \>=1\.5\.0-r\.1 \<1\.5\.1 \|\| \>=1\.5\.1-r\.1 \<1\.5\.2 \|\| \>=1\.5\.2-r\.1 \<1\.5\.3 \|\| \>=1\.5\.3-r\.1 \<1\.5\.4 \|\| \>=1\.5\.4-r\.1 \<1\.5\.5 \|\| \>=1\.5\.5-r\.1 \<1\.5\.6 \|\| \>=1\.5\.6-r\.1 \<1\.5\.7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 duckdb-introspect，可以用 npx duckdb-introspect 直接运行。

### @duckdbfan/drizzle-duckdb 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @duckdbfan/drizzle-duckdb 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @duckdbfan/drizzle-duckdb 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.17。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @duckdbfan/drizzle-duckdb 可以商用吗？

@duckdbfan/drizzle-duckdb 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @duckdbfan/drizzle-duckdb 的下载量有多少？

根据 npm 官方下载统计，@duckdbfan/drizzle-duckdb 在 2026/10/13 – 2026/11/11 这 30 天内被下载 24,187 次，日均约 806 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @duckdbfan/drizzle-duckdb 还在维护吗？

最新版本 2\.5\.0 发布于 2026/11/10（3 天前）；至今共发布 45 个版本，其中过去 12 个月发布了 38 个；首次发布于 2025/03/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。