# @broberg/db-sdk 中文文档

规范地址：https://npmcn.com/package/%40broberg/db-sdk/

版本：0\.2\.0
npm 元数据更新时间：2026-09-23T17:28:09.973Z
中文译文更新时间：2026-11-08T15:53:52.722Z
软件包许可：FSL-1\.1-Apache-2\.0

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

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

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

- 包体积（解压后）：29.8 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-06-08T00:55:42.587Z
- 最新版本发布：2026-09-23T17:28:09.540Z
- 近 30 天下载量：6173（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

Broberg.ai车队的瘦共享数据库客户端——在libSQL/Turso和PostgreSQL/Supabase上有一个DbClient外观. SQL方言通过而未翻译.

## 安装

```sh
npm install @broberg/db-sdk
```

也可以使用：`pnpm add @broberg/db-sdk`、`yarn add @broberg/db-sdk`、`bun add @broberg/db-sdk`

## README

# @broberg/db-sdk (英语)

Broberg.ai舰队共享 **数据库客户端** 一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一二一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一二一一一一一一一一一一一一一一一一一一一一一一一一一一一一二一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一 运输:

| 运输 | 对于 | 信封默认 |
| --- | --- | --- |
| `libsql` (默认) | Turso / libSQL, 当地 `file:` 数据库 | `TURSO_DATABASE_URL`, (中文(简体) ), `TURSO_AUTH_TOKEN` |
| `postgres` | PostgreSQL,包括Supabase | `DATABASE_URL` |

`createClient()` 返回同样的 `DbClient` 从两者,所以切换运输是 调用时更改为 `createClient` —— 说 **为了连接.**

> **SQL 未被翻译 .** 使用 libSQL 选项 `?` 占位符, Postgres 获取 `$1`,这两个方言在DDL,功能和 `PRAGMA`外观 通过未更改的 SQL : 重写 `?` 输入 `$1` 还会重写一个 `?` 在字符串文字或 JSON 操作员中。 在一个应用程序之间移动 运输也意味着移动其SQL.

## 安装

```bash
bun add @broberg/db-sdk
# or: npm i @broberg/db-sdk
```

## 使用

```ts
import { createClient, createReplica, health } from '@broberg/db-sdk';

// Turso (reads TURSO_DATABASE_URL + TURSO_AUTH_TOKEN)
const db = createClient();

// Postgres / Supabase (reads DATABASE_URL)
const pg = createClient({ backend: 'postgres' });

await pg.execute({ sql: 'insert into notes (id, body) values ($1, $2)', args: [1, 'hej'] });
const { rows } = await pg.execute('select id, body from notes');
// rows: [{ id: 1, body: 'hej' }]

// Several statements in ONE transaction — all apply or none do.
await db.batch([
  { sql: 'delete from s where edge = ?', args: ['m1'] },
  { sql: 'insert into s (edge, name) values (?, ?)', args: ['m1', 'x'] },
], 'write');

await health(pg); // { ok: true, transport: 'postgres', version: '16.4' }
```

`health()` 报告运输情况 **已回复** - 在那里读,而不是 从你自己的设定中推断出来.

### 逃生舱

`client.raw` 驱动程序本身的客户端,每台运算键入,用于 任何表面没有覆盖的:

```ts
const pg = createClient({ backend: 'postgres' });
await pg.raw.listen('events', (payload) => { /* … */ }); // postgres.js

const db = createClient();
await db.raw.executeMultiple(script); // @libsql/client
```

### 嵌入式复制品(只有libSQL)

本地 SQLite 文件与远程 Turso 主机同步 。 没有 Postgres对应, 和配置类型说: `backend: 'postgres'` 编号 `ReplicaConfig` 是一个编译错误.

```ts
const edge = createReplica({ path: '/data/buddy.db', syncIntervalSeconds: 30 });
await edge.sync(); // or rely on the interval
```

### 苏巴基地

使用鼠标连接字符串作为 `DATABASE_URL`发言稿 **总是关闭** 因为他们对Supabase做了些什么 交易-模式池(端口6543)。 2026年9月23日对照真实 Supabase项目(eu-North-1),40项同时询问,并准备以下说明:

| 路线 | 结果 |
| --- | --- |
| 交易总汇, 6543 | **挂载** 5–8 个答案后——无出错,3个运行 3 |
| 会话集合器 | 第40/40号决议 |
| 直接,5432 | 第40/40号决议 |

它不会失败——它 **绞刑**,而且只在货币下,所以顺序 测试和本地Postgres都保持绿色。 合同套房开60个 在20秒期限内通过真正的集合器同时查询 将准备好的语句转回红色 `HUNG`。 。 。 .

在服务器上保留服务-作用连接字符串. Supabase auth 属于 `@broberg/auth`,存储于 `@broberg/media`; 此软件包是 SQL 连接 只有这个.

### 机构

ORM留在消费者。 龙虾取出 **驱动程序** 客户端,你给我 `raw`数字 :

```ts
import { drizzle } from 'drizzle-orm/postgres-js';
const orm = drizzle(createClient({ backend: 'postgres' }).raw, { schema });
```

## API 密码

| 导出 | 签署 |
| --- | --- |
| `createClient` | `(cfg?: LibsqlConfig) => DbClient<LibsqlClient>` • 妇女 `(cfg: PostgresConfig) => DbClient<Sql>` |
| `createReplica` | `(cfg: ReplicaConfig) => ReplicaClient` - 仅限自由 |
| `health` | `(client) => Promise<{ ok, transport, version }>` ——如无法到达则投出 |

`DbClient`数字 : `transport`, (中文(简体) ), `raw`, (中文(简体) ), `execute(stmt)`, (中文(简体) ), `batch(stmts, mode?)`, (中文(简体) ), `close()`。 。 。 . 一个声明是: `string` 或者说 `{ sql, args? }`。结果是 `{ rows, columns, rowsAffected }`,以行为由列键入的普通对象.

**值是驱动器自己的——外观统一了形状,而不是类型.** 在同一查询中衡量:

| SQL 值 | 独立 | 邮资 |
| --- | --- | --- |
| `count(*)`, (中文(简体) ), `bigint` | `number` | **`string`** (单位:千美元)`'1'`(中文(简体) ) |
| `numeric` 编号 : `1.5` 字义 | `number` | **`string`** (单位:千美元)`'1.5'`(中文(简体) ) |
| `integer` | `number` | `number` |
| `timestamptz` | `string` | `Date` |
| `jsonb` | `string` | 解析对象 |

Postgres 返回 int8 和数字作为字符串,因为 JS 数字不能持有 在2^53上方的int8,而外观不以同样的理由转换它们—— 静态精度损失比可见的字符串更糟糕。 与 `Number(...)` 你知道范围是安全的。 合同套间是这些,所以一个司机 改变它们变成红色.

`batch` 模式为 `'write'` 财务报告和审定财务报表 `'deferred'`。这里有 **没有 `'read'` 模式**(单位:千美元) libSQL 对照本地文件读取批次被测量为执行 INSERT 邮递员拒绝,只读承诺 仅停留在运输 一个外表可以制造.

## 从0.1.x迁移

`createClient()` 用于返回 `@libsql/client`属于自己的 `Client`。它现在返回 `DbClient`。给一个打电话的人带来什么变化 :

-   `execute(string | { sql, args })` 财务报告和审定财务报表 `batch(stmts, 'write')` —— 说 **不变**。 。 。 .
-   `rows[i]['column']` ——不变. 位置访问 `rows[i][0]` 已删除:行 现在都是普通物体了.
-   `lastInsertRowid` ——从外观上走去(这是一个SQLite概念). 使用 `client.raw.execute(...)`,或 `returning id`。 。 。 .
-   LibSQL 客户端上的其他任何信息 (`executeMultiple`, (中文(简体) ), `transaction`, (中文(简体) ), `sync`: 到达它通过 `client.raw`。 。 。 .
-   **滴滴:** `drizzle(createClient(), { schema })` 这个读取器的图案 曾被显示——不再有效,因为细雨想要司机的客户端. 写入 `drizzle(createClient().raw, { schema })`. 为双方计量工作 运输(`drizzle-orm/libsql` 财务报告和审定财务报表 `drizzle-orm/postgres-js`) (中文(简体) ).
-   `type Client` 仍作为被贬值的别名存在 `DbClient`。 。 。 .

哥们`apps/server`),已知的0.1.x消费者,打字和通过自己的 db-sdk 对照此版本进行测试,没有源变化.

## 测试

```bash
DB_SDK_TEST_PG_URL=postgres://… bun test
```

一个合同套房运行 **不变** 涉及LibSQL的案件(当地档案),a **真实** 邮资,以及——何时 `DB_SDK_TEST_PG_POOLER_URL` 已经设定——一个真实的 Supabase 交易池。 无 `DB_SDK_TEST_PG_URL` 套房失败而不是 跳过 Postgres —— 跳过运输读取为绿色 。 CI提供 邮递服务集装箱.

## 许可证

FSL-1.1-Apache-2.0 克里斯蒂安·布罗伯格

## 常见问题

### @broberg/db-sdk 是什么？

Broberg\.ai车队的瘦共享数据库客户端——在libSQL/Turso和PostgreSQL/Supabase上有一个DbClient外观\. SQL方言通过而未翻译\.

### 如何安装 @broberg/db-sdk？

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

### @broberg/db-sdk 支持 TypeScript 吗？

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

### @broberg/db-sdk 支持 ESM 还是 CommonJS？

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

### @broberg/db-sdk 可以商用吗？

@broberg/db-sdk 使用 FSL-1\.1-Apache-2\.0 许可。声明的许可为 FSL-1\.1-Apache-2\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @broberg/db-sdk 的下载量有多少？

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

### @broberg/db-sdk 还在维护吗？

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