# @app-studio/qa-db 中文文档

规范地址：https://npmcn.com/package/%40app-studio/qa-db/

版本：0\.11\.6
npm 元数据更新时间：2026-11-05T23:13:48.156Z
中文译文更新时间：2026-11-08T08:32:20.072Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40app-studio/qa-db
原文对照：https://npmcn.com/package/%40app-studio/qa-db/?lang=original

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

- 包体积（解压后）：76.1 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- peer 依赖：pg \>=8，@electric-sql/pglite \>=0\.2
- 首次发布：2026-08-09T15:45:46.734Z
- 最新版本发布：2026-11-05T23:13:47.989Z
- 近 30 天下载量：1854（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

每个运行的测试数据库——真实的Postgres或嵌入式PGlite——创建,迁移,用经过核实的后置条件截取,出站时被丢弃.

## 安装

```sh
npm install @app-studio/qa-db
```

也可以使用：`pnpm add @app-studio/qa-db`、`yarn add @app-studio/qa-db`、`bun add @app-studio/qa-db`

## README

# @app-studio/qa-db (英语)

`createCheckpointStore`, (中文(简体) ), `createPgliteCheckpointAdapter` 财务报告和审定财务报表 `createPostgresCheckpointAdapter` 将已验证的种子前缀保存为本地 DB 图像、栅栏作家和在重放重点之前恢复相容的检查站. 锁定跟踪数据库身份, 横跨检查; 恢复 API 校验闸门 执行。 见 [检查站发展](https://npmcn.com/package/docs/API_STUDIO.md)。 。 。 .

每个运行的测试数据库——真正的Postgres或嵌入式PGlite——创建,迁移, 以经核实的后置条件被截断,出道后弃去.

## 每跑一个数据库,没有记忆

替代的公约是“每次会议都指定自己的数据库名称”,以及 它失败了公约的方式。 共用一个数据库的两套套房 其他——幽灵401s,在单独通过的测试中"没有找到记录"——以及 在同一次复选中,当第二场课忘记规则时,审计必须 从头开始重做.

这里没有什么可记住的。 默认路径是安全路径 :

```ts
// tests/setup/test-db.ts
import { createTestDbGlobalSetup } from '@app-studio/qa-db';
import { execFileSync } from 'node:child_process';

export default createTestDbGlobalSetup({
  mode: 'postgres',
  prefix: 'myapp_test_run_',
  adminUrl: process.env.POSTGRES_URL ?? 'postgres://localhost:5432/postgres',
  applySchema: async ({ url }) => {
    execFileSync('pnpm', ['prisma', 'db', 'push'], { env: { ...process.env, DATABASE_URL: url } });
  },
});
```

```ts
// vitest.config.ts
export default { test: { globalSetup: ['tests/setup/test-db.ts'] } };
```

每次跑步都会 `myapp_test_run_<pid>_<timestamp>`被撕毁 数据库 6个多小时以上 被扫走的路上, 所以一个被杀死的跑道留下了碎片 一个下午,而不是永远.

**`TEST_DATABASE_URL` 设置在外壳中仍然获胜**,这就是CI如何针入a 服务数据库。 在任何 dotenv 装入前故意读取: 仓库 船舶共享默认值 `.env` 为方便起见,并尊重 完全恢复这个防止的碰撞. `TEST_DB_KEEP=1` 保存数据库 因此,失败可以打开之后.

## PGlite 是一等模式, 不是倒置模式

```ts
createTestDbGlobalSetup({
  mode: 'pglite',
  prefix: 'myapp_test_',
  applySchema: async ({ dataDir }) => { /* … */ },
  publish: ({ dataDir }) => ({ DB_TYPE: 'pglite', PGLITE_DATA_DIR: dataDir ?? '' }),
});
```

PGlite 是 Postgres 编译为 Web Assembly, 运行在进程中 . `pg_tables`, (中文(简体) ), `TRUNCATE … RESTART IDENTITY CASCADE` 财务报告和审定财务报表 `SET LOCAL lock_timeout` 都表现为 在服务器上做,所以同样的测试 运行不变—— 没有多克,在一个 笔记本电脑或者CI 这个软件包自己的重置测试 运行在它上, 这就是论证 在实践中,而不是原则上.

使用它来开发, 不仅仅是测试: “电子数据库”是一个 临时目录,没有服务器可与之相撞.

## 重设,并证明它发生

```ts
import { fromPrisma, makeResetDatabase } from '@app-studio/qa-db';

const resetDatabase = makeResetDatabase(fromPrisma(prisma), { verifyTable: 'User' });

beforeEach(resetDatabase);
```

两个细节是负载的.

**锁出后.** `TRUNCATE` 需要一个进入 ExCLUSIVE锁,和一个真实的 应用在回复后合法地发布火灾和遗忘的文字——a 届会 `lastSeenAt`一个分析的行。 没有超时,与其中之一比赛 这变成了无休止的等待, 套房挂而不是失败。 失败 快速和重试严格来说更好:同样的比赛以毫秒的速度解决 下一次尝试.

**条件.** 重置验证自身效果. 开始的套房 相对于所剩行,它不会在这里失败;它会在稍后的三次测试中失败,在某种程度上 读取为应用程序错误。 检查成本一次查询,然后产生混乱 失败成一个明显的.

从数据库中发现表格,而不是公布,以及迁移 簿记独活.

## 任何客户端

`SqlExecutor` 是三种方法,所以同样的重置工作 通过Prisma, `pg` 或 PGlite 类型 :

```ts
import { fromPg, fromPglite, fromPrisma } from '@app-studio/qa-db';
```

Prisma是经过结构调整而不是进口的—— `@prisma/client` 实值 依此,每个主机都会被 版本的软件包,在运行生成器之前不存在.

## 出口

| 导出 | 目的 |
| --- | --- |
| `createTestDbGlobalSetup` | 恶毒 `globalSetup`,安装在一个行. |
| `createEphemeralDatabase`, (中文(简体) ), `sweepStaleDatabases` | 同样的生命周期,绝对, 对于管弦乐剧本. |
| `makeResetDatabase`, (中文(简体) ), `tableNames` | 带有经核实的后置条件的断接; 发现什么可以断接 . |
| `fromPrisma`, (中文(简体) ), `fromPg`, (中文(简体) ), `fromPglite` | 适配器进入 `SqlExecutor`。 。 。 . |
| `explicitDatabaseUrl`, (中文(简体) ), `withDatabase`, (中文(简体) ), `ephemeralName` | 命名和推翻规则,为需要的脚本曝光. |

## 所需资源

节点.js20或更新. `pg` 财务报告和审定财务报表 `@electric-sql/pglite` 是可选的对等方——安装 使用哪种模式 .

## 常见问题

### @app-studio/qa-db 是什么？

每个运行的测试数据库——真实的Postgres或嵌入式PGlite——创建,迁移,用经过核实的后置条件截取,出站时被丢弃\.

### 如何安装 @app-studio/qa-db？

在项目目录运行 npm install @app-studio/qa-db，或使用 pnpm add / yarn add / bun add。

### @app-studio/qa-db 支持 TypeScript 吗？

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

### @app-studio/qa-db 支持 ESM 还是 CommonJS？

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

### @app-studio/qa-db 需要什么版本的 Node\.js？

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

### @app-studio/qa-db 可以商用吗？

@app-studio/qa-db 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @app-studio/qa-db 的下载量有多少？

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

### @app-studio/qa-db 还在维护吗？

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