# @denny-il/drizzle-pg-utils 中文文档

规范地址：https://npmcn.com/package/%40denny-il/drizzle-pg-utils/

版本：0\.8\.2
npm 元数据更新时间：2026-10-22T12:11:05.673Z
中文译文更新时间：2026-11-11T22:39:04.899Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40denny-il/drizzle-pg-utils
原文对照：https://npmcn.com/package/%40denny-il/drizzle-pg-utils/?lang=original
项目主页：https://github.com/denny-il/drizzle-pg-utils
源码仓库：https://github.com/denny-il/drizzle-pg-utils

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

- 包体积（解压后）：145 kB，90 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：drizzle-orm 1\.0\.0-rc\.5，temporal-polyfill ^1\.0\.1
- 首次发布：2025-07-25T08:50:38.346Z
- 最新版本发布：2026-10-22T12:11:05.015Z
- 近 30 天下载量：74772（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 13 个）

## 中文简介

Drizzle ORM 和 PostgreSQL 的一套公用事业

## 安装

```sh
npm install @denny-il/drizzle-pg-utils
```

也可以使用：`pnpm add @denny-il/drizzle-pg-utils`、`yarn add @denny-il/drizzle-pg-utils`、`bun add @denny-il/drizzle-pg-utils`

## README

# 滴入后闪光SQL 用户

一个TypeScript库,为Drizzle ORM应用程序中PostgreSQL JSONB数据和Temperal类型的工作提供类型安全的公用设备.

## 快速启动

### 安装

```bash
npm install @denny-il/drizzle-pg-utils
```

### 查询示例( 选择 + 更新)

```typescript
import { json } from '@denny-il/drizzle-pg-utils'
import { eq, gte } from 'drizzle-orm'
import { jsonb, pgTable, serial, text } from 'drizzle-orm/pg-core'

type Profile = {
  user: {
    name: string
    preferences?: { theme: 'light' | 'dark'; tags?: string[] }
  }
}

const users = pgTable('users', {
  id: serial('id').primaryKey(),
  email: text('email').notNull(),
  profile: jsonb('profile').$type<Profile>().notNull(),
})

const profile = json(users.profile)

const [row] = await db
  .select({
    id: users.id,
    // This now works without having any runtime schemas,
    // and is fully type-safe
    theme: profile.user.preferences.theme.$value,
  })
  .from(users)
  .where(eq(profile.user.preferences.theme.$value, 'dark'))

await db
  .update(users)
  .set({
    // Update specific paths in JSONB column atomically in a single query,
    // without merging the entire object in application code.
    profile: json(users.profile).$pipe(
      // Initialize the optional branch before writing inside it.
      (s) => s.user.preferences.$default({ theme: 'light', tags: [] }),
      // Set theme to 'dark'.
      (s) => s.user.preferences.theme.$set('dark'),
      // Set first value in tags array to 'intro'.
      (s) => s.user.preferences.tags['0'].$set('intro'),
    ),
  })
  .where(eq(users.id, row!.id))
```

## 特征

### JSON 水电

-   访问嵌入 JSONB 路径 `json(source)` 和完整的脚本推论.
-   查询JSONB封装有打出路径的横道和全列索引方便SQL.
-   解析更新深分支 `.$set(...)`, (中文(简体) ), `.$default(...)`, (中文(简体) ), `.$push(...)`, (中文(简体) ), `.$merge(...)`,以及 `.$pipe(...)`。 。 。 .
-   构建,合并,并用已键入的 SQL 帮助器对数组进行修改.

```typescript
import { json } from '@denny-il/drizzle-pg-utils'
import { eq } from 'drizzle-orm'

// Access nested properties with type safety
const profile = json(users.profile)
const rows = await db
  .select({
    id: users.id,
    theme: profile.user.preferences.theme.$value,
  })
  .from(users)
  .where(eq(profile.user.preferences.theme.$value, 'dark'))

// Query JSONB containment while keeping the predicate rooted at users.profile
const darkUsers = await db
  .select({ id: users.id })
  .from(users)
  .where(profile.user.preferences.$contains({ theme: 'dark' }))

// Update values at specific paths
await db
  .update(users)
  .set({
    profile: profile.user.name.$set('New Name'),
  })
  .where(eq(users.id, rows[0]!.id))
```

### 临时公用事业

-   将 PostgreSQL 日期和时间列直接映射到 Temperal 值 .
-   选择三个平等的切入点: `/temporal`, (中文(简体) ), `/temporal/global`,或 `/temporal/polyfill`。 。 。 .
-   为 `yearMonth` 财务报告和审定财务报表 `monthDay` 文本栏.

```typescript
import {
  timestamp,
  timestampz,
} from '@denny-il/drizzle-pg-utils/temporal/global'

const events = pgTable('events', {
  id: serial('id').primaryKey(),
  scheduledAt: timestamp.column('scheduled_at'),
  createdAt: timestampz.column('created_at'),
})

await db.insert(events).values({
  scheduledAt: Temporal.PlainDateTime.from('2026-03-15T09:30:00'),
  createdAt: Temporal.Instant.from('2026-03-15T08:30:00Z'),
})

const upcoming = await db
  .select({ scheduledAt: events.scheduledAt })
  .from(events)
  .where(
    gte(events.scheduledAt, Temporal.PlainDateTime.from('2026-03-01T00:00:00')),
  )
```

见 `docs/temporal.md` 用于设置选择,运行时间行为,驱动笔记,以及示例.

## 文档

-   **[JSON 水电](https://npmcn.com/package/%40denny-il/drizzle-pg-utils/docs/json.md)** - JSON业务完整指南
-   **[临时公用事业](https://npmcn.com/package/%40denny-il/drizzle-pg-utils/docs/temporal.md)** - 使用临时API处理PostgreSQL日期/时间类型

## 代理技能

该存储库包括图书馆-消费者使用实例和排除故障的代理技能:

-   **[细雨- pg- utils](https://npmcn.com/package/%40denny-il/drizzle-pg-utils/skills/drizzle-pg-utils/SKILL.md)** - JSONB和临时助手指导,提供以查询为重点的实例

## 许可证

麻省理工学院执照 - 看 [利比里亚](https://npmcn.com/package/%40denny-il/drizzle-pg-utils/LICENSE.md) 详细情况.

## 常见问题

### @denny-il/drizzle-pg-utils 是什么？

Drizzle ORM 和 PostgreSQL 的一套公用事业

### 如何安装 @denny-il/drizzle-pg-utils？

在项目目录运行 npm install @denny-il/drizzle-pg-utils，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：drizzle-orm（1\.0\.0-rc\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @denny-il/drizzle-pg-utils 支持 TypeScript 吗？

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

### @denny-il/drizzle-pg-utils 支持 ESM 还是 CommonJS？

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

### @denny-il/drizzle-pg-utils 可以商用吗？

@denny-il/drizzle-pg-utils 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @denny-il/drizzle-pg-utils 的下载量有多少？

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

### @denny-il/drizzle-pg-utils 还在维护吗？

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