# @drizzle-adapter/pglite 中文文档

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

版本：1\.1\.1
npm 元数据更新时间：2026-03-25T23:49:38.071Z
中文译文更新时间：2026-11-12T20:16:43.327Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40drizzle-adapter/pglite
原文对照：https://npmcn.com/package/%40drizzle-adapter/pglite/?lang=original

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

- 包体积（解压后）：28.2 MB，1034 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@electric-sql/pglite ^0\.2\.17
- 首次发布：2024-12-03T05:42:31.500Z
- 最新版本发布：2026-03-25T23:49:37.942Z
- 近 30 天下载量：18049（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 1 个）

## 中文简介

PgLite适配器用于Drizzle适配器生态系统,提供一种轻量级的PostgreSQL兼容数据库,适合开发和测试.

## 安装

```sh
npm install @drizzle-adapter/pglite
```

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

## README

# @ 细雨适应器/ pglite

PgLite适配器用于Drizzle适配器生态系统,提供一种轻量级的PostgreSQL兼容数据库,适合开发和测试.

## 概览

这个 `@drizzle-adapter/pglite` 软件包为 Drizzle 适应器接口提供 PgLite 执行。 虽然你不直接与此软件包互动( 您使用 `@drizzle-adapter/core` 相反,它可以在Drizzle适应器生态系统中建立一个轻量级的PostgreSQL兼容数据库.

## 为什么是PgLite?

PgLite为开发和测试提供了独特的优势:

-   **嵌入式邮递SQL**: 完全不安装的 PostgreSQL 兼容性
-   **0 配置**: 在没有设置的盒子内工作
-   **内存或文件存储**: 选择内存或持久存储
-   **适合测试**: 用于每次测试的快速、孤立的数据库实例
-   **发展友好组织**: 快速启动, 没有外部依赖
-   **邮递SQL 兼容**: 使用没有 PostgreSQL 服务器的 PostgreSQL 特性
-   **轻巧**:足迹小,适合CI/CD环境
-   **快速执行**: 原地执行,以改善业绩

### 完美为:

1.  **单位测试**: 每个测试中孤立的数据库实例
2.  **集成测试**: 用于测试的全部 PostgreSQL 兼容性
3.  **地方发展**: 不需要安装 PostgreSQL
4.  **CI/CD 管道**: 用于自动化测试的快速、轻量级数据库
5.  **原型制作**: 新项目快速设置

## 安装

```bash
# Install both the core package and the PgLite adapter
pnpm install @drizzle-adapter/core @drizzle-adapter/pglite
```

## 重要:适配器注册

适配器要正确使用 DrizzleAdapterFactory 操作,必须导入它进行自我注册的副作用:

```typescript
// Import for side effects - adapter will self-register
import '@drizzle-adapter/pglite';

// Now you can use the factory
import { DrizzleAdapterFactory } from '@drizzle-adapter/core';
```

## 使用量

### 配置

```typescript
import { DrizzleAdapterFactory, TypeDrizzleDatabaseConfig } from '@drizzle-adapter/core';

// In-memory database (perfect for testing)
const config: TypeDrizzleDatabaseConfig = {
  DATABASE_DRIVER: 'pglite'
};

const factory = new DrizzleAdapterFactory();
const adapter = factory.create(config);
```

### Schema 定义

```typescript
const dataTypes = adapter.getDataTypes();

const users = dataTypes.dbTable('users', {
  id: dataTypes.dbSerial('id').primaryKey(),
  name: dataTypes.dbText('name').notNull(),
  email: dataTypes.dbText('email').notNull().unique(),
  profile: dataTypes.dbJsonb('profile'),
  createdAt: dataTypes.dbTimestamp('created_at').defaultNow()
});

const posts = dataTypes.dbTable('posts', {
  id: dataTypes.dbSerial('id').primaryKey(),
  userId: dataTypes.dbInteger('user_id')
    .references(() => users.id),
  title: dataTypes.dbText('title').notNull(),
  content: dataTypes.dbText('content').notNull(),
  tags: dataTypes.dbArray('tags', { type: 'text' }),
  metadata: dataTypes.dbJsonb('metadata'),
  published: dataTypes.dbBoolean('published').default(false),
  createdAt: dataTypes.dbTimestamp('created_at').defaultNow()
});
```

### 基本 CRUD 操作

```typescript
import { eq, and, or, desc, sql } from 'drizzle-orm';

const client = await adapter.getConnection().getClient();

// INSERT
// Single insert with returning
const [newUser] = await client
  .insert(users)
  .values({
    name: 'John Doe',
    email: 'john@example.com',
    profile: { bio: 'Hello!' }
  })
  .returning();

// Bulk insert
await client
  .insert(posts)
  .values([
    {
      userId: newUser.id,
      title: 'First Post',
      content: 'Hello, world!',
      tags: ['hello', 'first']
    },
    {
      userId: newUser.id,
      title: 'Second Post',
      content: 'Another post',
      tags: ['second']
    }
  ]);

// SELECT
// Select all
const allUsers = await client
  .select()
  .from(users);

// Select with conditions
const user = await client
  .select()
  .from(users)
  .where(eq(users.email, 'john@example.com'));

// Select with join and array operations
const postsWithTags = await client
  .select({
    userName: users.name,
    postTitle: posts.title,
    tags: posts.tags
  })
  .from(posts)
  .leftJoin(users, eq(posts.userId, users.id))
  .where(sql`${posts.tags} && ARRAY['hello']::text[]`)
  .orderBy(desc(posts.createdAt));

// UPDATE
await client
  .update(users)
  .set({
    name: 'John Smith',
    profile: { bio: 'Updated bio' }
  })
  .where(eq(users.id, newUser.id));

// DELETE
await client
  .delete(posts)
  .where(
    and(
      eq(posts.userId, newUser.id),
      eq(posts.published, false)
    )
  );
```

### 测试示例

```typescript
import { DrizzleAdapterFactory } from '@drizzle-adapter/core';

describe('User Repository Tests', () => {
  let adapter: DrizzleAdapterInterface;
  let repository: UserRepository;

  beforeEach(async () => {
    // New in-memory database for each test
    const factory = new DrizzleAdapterFactory();
    adapter = factory.create({
      DATABASE_DRIVER: 'pglite'
    });

    repository = new UserRepository(adapter);
    await repository.connect();

    // Create tables
    const client = await adapter.getConnection().getClient();
    await client.execute(sql`
      CREATE TABLE users (
        id SERIAL PRIMARY KEY,
        name TEXT NOT NULL,
        email TEXT NOT NULL UNIQUE
      )
    `);
  });

  afterEach(async () => {
    await repository.disconnect();
  });

  it('should create a new user', async () => {
    const user = await repository.create({
      name: 'Test User',
      email: 'test@example.com'
    });

    expect(user.name).toBe('Test User');
    expect(user.email).toBe('test@example.com');
  });

  it('should find user by email', async () => {
    await repository.create({
      name: 'Test User',
      email: 'test@example.com'
    });

    const user = await repository.findByEmail('test@example.com');
    expect(user).not.toBeNull();
    expect(user?.name).toBe('Test User');
  });
});
```

## 最佳做法

1.  **测试**: 使用内存数据库进行测试
2.  **隔离**: 为每个测试创建新实例
3.  **发展**: 不使用 PostgreSQL 用于本地开发
4.  **排雷中心/发改委**: 适用于自动化测试管道的完美
5.  **Schema 验证**: 测试没有完整服务器的 PostgreSQL 计划

## 捐款

我们欢迎捐款! 请随意提交拉力请求 对于重大变动,请先开出一个问题来讨论你想要改变什么.

## 相关软件包

-   [@ 细雨适应器/ 核心](https://npmcn.com/package/%40drizzle-adapter/core) - 核心接口和类型
-   [@ 细雨适应器/ pg- core](https://npmcn.com/package/%40drizzle-adapter/pg-core) - 共享 PostgreSQL 功能

## 常见问题

### @drizzle-adapter/pglite 是什么？

PgLite适配器用于Drizzle适配器生态系统,提供一种轻量级的PostgreSQL兼容数据库,适合开发和测试\.

### 如何安装 @drizzle-adapter/pglite？

在项目目录运行 npm install @drizzle-adapter/pglite，或使用 pnpm add / yarn add / bun add。

### @drizzle-adapter/pglite 支持 TypeScript 吗？

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

### @drizzle-adapter/pglite 支持 ESM 还是 CommonJS？

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

### @drizzle-adapter/pglite 可以商用吗？

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

### @drizzle-adapter/pglite 的下载量有多少？

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

### @drizzle-adapter/pglite 还在维护吗？

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