# @btravstack/prisma 中文文档

规范地址：https://npmcn.com/package/%40btravstack/prisma/

版本：0\.58\.0
npm 元数据更新时间：2026-11-07T21:13:37.579Z
中文译文更新时间：2026-11-08T17:46:55.154Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：108 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12
- 运行依赖：0 个
- peer 依赖：unthrown ^5\.0\.0，@btravstack/di ^0\.58\.0，@btravstack/core ^0\.58\.0，@btravstack/config ^0\.58\.0，@prisma/orm-postgres ^8\.0\.0-rc\.11
- 首次发布：2026-08-25T23:43:23.071Z
- 最新版本发布：2026-11-07T21:13:37.216Z
- 近 30 天下载量：8418（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

@btravstack/core的 Prisma 启动器: 通过 Config 的 DATABASE URL , Postgres 驱动程序适配器, 以及一个应用范围的客户端

## 安装

```sh
npm install @btravstack/prisma
```

也可以使用：`pnpm add @btravstack/prisma`、`yarn add @btravstack/prisma`、`bun add @btravstack/prisma`

## README

# @btravstack/prisma (英语)

> Prisma 启动程序 [`@btravstack/core`](https://github.com/btravstack/btravstack)数字 : `DATABASE_URL` 约束通过 `Config`作为中间器皿的每克观测, 以及一个客户 其池是应用范围。 普里斯马 **第8条**。 。 。 .

📖 **[文档](https://btravstack.github.io/btravstack/reference/prisma)** • 妇女 [API 参考](https://btravstack.github.io/btravstack/api/prisma/)

```sh
pnpm add @btravstack/prisma @btravstack/core @btravstack/config @btravstack/di unthrown \
  @prisma/orm-postgres@8.0.0-rc.20 temporal-polyfill@1.0.4
```

安装所需的对等器, 因此应用程序持有每个的单一副本; `temporal-polyfill` 是 Postgres 软件包中来自 rc.14 的对等端。 这个 `@prisma/orm-postgres` 端点是 `^8.0.0-rc.11`,两端均测试:a 应用程序已保存在 rc.11 上.

**以释放的迁移升级 :** 升级 `@btravstack/prisma` 联 合 国 `@btravstack/*` 同伴们 离开普里斯玛的地方 没有合同、移民或 数据库标记更改。 从 rc.11 更新 Prisma 本身 发布迁移,并重新签名每个数据库,这是Prisma的路径 大于此软件包; 参见 [支持的 Prisma 列车](https://btravstack.github.io/btravstack/reference/prisma#supported-prisma-trains)编辑 `prisma` CLI是你的,作为一个dev依赖:客户是 从 __ 因此,没有这个包裹可以运送. 节点 `>=22.12`。 。 。 .

**生产包装:** 被钉住的 Postgres 外观要求 `@prisma/orm-toolchain`,包括其CLI引擎对等和构建工具 关闭。 A 类 `/runtime` 导入和 `pnpm deploy --prod` 不删除这些 过渡性依赖。 将合同排放量保持在建造阶段 在部署中迁移任务, 启用严格的对等器; 无工具链 运行时间 : [上游被封锁](https://btravstack.github.io/btravstack/reference/prisma#production-dependency-closure)。 。 。 . 该节记录了明显的分裂和跟踪的依赖.

**这是Prisma 8号**,这是一个不同的软件包家族,而不是一个版本 颠倒 -- `@prisma/orm-postgres` 替换 `@prisma/client` 财务报告和审定财务报表 `@prisma/adapter-pg` 两者,没有 `@prisma/instrumentation`用于 Prisma 7 `@btravstack/prisma@0.14`。 。 。 .

## 实例

```ts
import { prismaDatabase } from "@btravstack/prisma";
import { contractFromJson } from "@prisma/orm-postgres/static";

const contract = contractFromJson<Contract>(contractJson);
const database = prismaDatabase("OrderDatabase")({
  client: ({ url, middleware }) => postgres({ contract, url, middleware }),
});
```

这就是整个地表. `database` 是一个 **模块** 携带端口 a 组成根为; 提供者绑定 `DATABASE_URL`聪明的 客户提供商和健康检查在其中:

```ts
export const PersistenceModule = Module("Persistence")({
  imports: [database],
  exports: [database.port],
  needs: [Env],
});
```

**客户类型是你的,这是故意的.** 一个Prisma 8 客户端是 类型 __ 发射 `Contract` 从 __ `contract.json`这样 没有这个包裹可以运送。 从Prisma rc.19,把JSON变成 输入值一次 `contractFromJson<Contract>(contractJson)` 通过 `contract` 改为 `postgres({ contract, ... })`编辑 `client` 箭头在那边 合同和这个启动器相会, 端口按它的确切键 返回。 散开 `middleware` 它将你交给客户: 下面的每克观测数据来自此.

## 它拥有的

-   **`DATABASE_URL` 结束 `Config`。 。 。 .** 缺少或空白值是一个模型 `ConfigInvalid` 命名变量, 而不是抛出—— 所以一个配置错误 部署出口 `78` 与原因在 stderr 而不是崩溃在 第一个查询.
-   **池从生.** 提供商是 _聪明_这样 `release` 关上它 包括跑后失败的靴子.
-   **一个在任何工作运行前回答的数据库.** 打开范围运行 健康检查的探测器, 所以一个新鲜的池子 在它第一次爆发之前就已经核实了 和不回答启动失败的数据库 `DatabaseUnreachable` ——数据库的名称和驱动原因,从不 URL (中文(简体) ).
-   **角色行安全适用于.** 任何表格都有行级安全 启用,一个超级用户的角色,拥有 `BYPASSRLS`,或拥有一行安全 表格为非 `FORCE`d 启动失败 `RowSecurityBypassed`名称 每个政策都承认每一行 对于它.
-   **健康检查**,以启动器命名—— `SELECT 1` 穿过生地 ,折叠入内核 `GET /healthz` 没有线. `/readyz` 不读它: 无法依赖每个复制股 立即全部删除.
-   **每个查询都交给 `Observers`**,作为一个声明的中间软件,所以 编译 `observability()` 将失败写成行并 `otel()` 打开 长度和薄荷的仪器——没有旗和端口列表 满足当你没有作曲。 中间软件看到ORM道, SQL 建筑工和原始车道都一样 搭乘跑道 `latencyMs`。 。 。 .

## `Result`s, 打开 `@btravstack/prisma/result` 子路径

Prisma 8 丢出一个 **结构化** 携带 PostgreSQL 自己的 SQLSTATE 出错 . `tryQuery` 把它变成一个 `Result` 手持三只模范武器—— `UniqueConstraintViolation` (单位:千美元)`23505`,与 `constraint` 数据库 名称), `ForeignKeyViolation` (单位:千美元)`23503`和 `NotAuthorized` (单位:千美元)`42501`, (中文(简体) ), 包括拒绝写行安保政策)。 其他的都是缺陷, 除非你把它列入 `raises` - SQLSTATE 你自己的触发器是故意提高的 之后,作为一名 `RaisedException` 带着密码.

```ts
const saved = tryQuery(() => db.orm.orders.Order.create({ orderId })).mapErrCases(
  (matcher, defect) =>
    matcher
      .with(P.tag("UniqueConstraintViolation"), () => duplicate(orderId))
      .with(P.tag("ForeignKeyViolation"), P.tag("NotAuthorized"), (cause) => defect(cause)),
);
```

它需要一个 **th克** 而不是承诺: `AsyncResult` 渴望着,所以 在呼叫站点所构建的许诺在结果存在之前就已经开始了.

## 列级安全 `@btravstack/prisma/rls` 子路径

**保险单在合同中公布** —— 说 `@@rls` 在模型和一个 `policy_all` 旁边有电线,规划者就发出 `ENABLE ROW LEVEL SECURITY` 财务报告和审定财务报表 `CREATE POLICY` 像其他迁移行动一样. **针是 交易:**

```ts
const orders = await tenantPinned(db, tenant, (tx) => tx.orm.orders.Order.all());
```

为了连续的快照,通过 `{ isolationLevel: "repeatable read", readOnly: true }` 作为第四个论点。 启动器在 租户针。 使用它的启动端客户端和回调 `tx` 每笔 相关读取;省略特性保存连接默认值. 见 [连续的快照](https://btravstack.github.io/btravstack/reference/prisma#consistent-snapshots)。 。 。 .

`set_config(…, true)` 实值 **当地交易**,这就是为什么这个打开一个 而不是交回被绑定的客户端:一个会话瞄准针只在同时有效 池子碰巧还原了同样的连接 并且没有第一个 时间没有。 政策必须读取 **不变** 设置 - `app.tenant_id` 仅仅是默认,因为 `tenantPinned(db, tenant, work, { setting })` 和一项政策 命名不同的一个 拒绝每行和每写, 它看起来 就像排安全工作一样.

两分之一保持部署, 和两者在被遗忘时都悄悄地失败: Prisma 8 作者政策,但没有 `GRANT`s,它会发出 `ENABLE ROW LEVEL SECURITY` 与 没办法说 `FORCE` -所以桌子是... -是的 - so the table's.. **拥有者**,这是运行 移民,绕过一切政策。 连接为既不是所有者的角色 或超级用户——靴子拒绝使用 `RowSecurityBypassed`编辑 [参考页](https://btravstack.github.io/btravstack/reference/prisma) 携带 DDL 和同样故障的较小行.

## 预定工作的租户发现情况

`tenantListing` 打开 `/rls` 宣布只使用租户身份查询(每页100个身份证, 在最后标识后恢复)和 a 检查 Prisma 迁移安装其功能、所有者政策和执行 赠款。 它在强制行级安全下工作 而普通应用 保留租户范围。 共享数据不需要特权 应用程序连接。 见 [租户名单](https://btravstack.github.io/btravstack/reference/prisma#list-tenants-without-cross-tenant-row-access)。 。 。 .

## 没有

**正在迁移.** 部署运行 `prisma db migrate` 根据同一数据库 _进程开始前_ ——,在行安全的地方,作为它的 **拥有者** 而不是角色 `DATABASE_URL` 携带。 自动迁移的应用程序 在靴子比赛 其他复制品.

**引擎级追踪.** 没有引擎: Prisma 8 是 TypeScript 运行时间 和船舶没有仪表包, 所以声明中间软件是 整个接缝,它已经承载了 运行时间的自身时间.

**交易.** 交界属于适配器,在呼叫时拼出—— `db.transaction(fn)` 这是原始的。 这个 `rls` 子路径打开一个交易 将一个设置 和它内部的工作是你的。 没有单位范围 交易,不会有一个 [内核映射无](https://btravstack.github.io/btravstack/explanation/the-kernel-maps-nothing)。 。 。 .

**库基类.** 端口是您的应用程序的词汇, 而不是这个 包裹的.

## 选项

| 选项 | 何处 | 这是什么 |
| --- | --- | --- |
| `name` | `prismaDatabase(name)` | 港口的身份证和卫生检查的名称——要求 |
| `client` | `prismaDatabase(name)({ client })` | 从 URL 和中间软件中构建您的客户端 。 此软件包捆绑 - 需要 |
| `DATABASE_URL` | 环境,读作 `prismaDatabase(name)` | 连接字符串 — 需要, 在图表构建中验证; 空白是一个错误, 退出 `78` |
| `setting` | `tenantPinned(db, tenant, work, { setting })` | postgreSQL 运行时间设置策略为- 默认 `app.tenant_id` |
| `isolationLevel`, (中文(简体) ), `readOnly` | `tenantPinned(db, tenant, work, options)` | 交易特性在 pin 之前建立—— 省略时的连接默认 |
| `raises` | `tryQuery(run, { raises })`, (中文(简体) ), `tenantPinned(…, { raises })` | SQLSTATEs 建模为 `RaisedException` 而不是缺陷——默认无 |
| `schema`, (中文(简体) ), `table`, (中文(简体) ), `tenantColumn` | `tenantListing(options)` | 缩小列表的物理表和租户栏 |
| `name`, (中文(简体) ), `owner`, (中文(简体) ), `role` | `tenantListing(options)` | 上市功能、其信任的拥有者和应用程序调用者 |

有一个 **没有 `instrumented` 旗帜**: 观察是设定的端口, 每一次呼叫都是 因此,一个图 拼凑,没有可观察 支付一个惰性呼叫,没有 端口列表. 完整表——默认,语义和推理——活在 [参考页](https://btravstack.github.io/btravstack/reference/prisma), (中文(简体) ), 这张名单是详细的.

## 许可证

麻省理工学院

## 常见问题

### @btravstack/prisma 是什么？

@btravstack/core的 Prisma 启动器: 通过 Config 的 DATABASE URL , Postgres 驱动程序适配器, 以及一个应用范围的客户端

### 如何安装 @btravstack/prisma？

在项目目录运行 npm install @btravstack/prisma，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：unthrown（^5\.0\.0）、@btravstack/di（^0\.58\.0）、@btravstack/core（^0\.58\.0）、@btravstack/config（^0\.58\.0）、@prisma/orm-postgres（^8\.0\.0-rc\.11）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @btravstack/prisma 支持 TypeScript 吗？

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

### @btravstack/prisma 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @btravstack/prisma 需要什么版本的 Node\.js？

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

### @btravstack/prisma 可以商用吗？

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

### @btravstack/prisma 的下载量有多少？

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

### @btravstack/prisma 还在维护吗？

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