# @aws-blocks/bb-distributed-data 中文文档

规范地址：https://npmcn.com/package/%40aws-blocks/bb-distributed-data/

版本：0\.3\.0
npm 元数据更新时间：2026-11-02T10:26:18.355Z
中文译文更新时间：2026-11-07T13:34:53.615Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws-blocks/bb-distributed-data
原文对照：https://npmcn.com/package/%40aws-blocks/bb-distributed-data/?lang=original
项目主页：https://github.com/aws-devtools-labs/aws-blocks/tree/main/packages/bb-distributed-data#readme
源码仓库：https://github.com/aws-devtools-labs/aws-blocks

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

- 包体积（解压后）：241 kB，82 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：kysely \>=0\.28\.12 \<0\.30\.0，constructs ^10\.6\.0，aws-cdk-lib \>=2\.100\.0
- 首次发布：2026-06-15T23:39:26.677Z
- 最新版本发布：2026-11-02T10:26:17.981Z
- 近 30 天下载量：63343（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

无服务器SQL数据库由亚马逊·奥罗拉DSQL支持. 0-ops,即时提供,规模为零,可选的多区域活性写作.

## 安装

```sh
npm install @aws-blocks/bb-distributed-data
```

也可以使用：`pnpm add @aws-blocks/bb-distributed-data`、`yarn add @aws-blocks/bb-distributed-data`、`bun add @aws-blocks/bb-distributed-data`

## README

# @aws- blocks/ bb- 分布数据

无服务器SQL数据库由亚马逊·奥罗拉DSQL支持. 0-ops,即时提供,规模为零,可选的多区域活性写作.

**何时使用 :** 无服务器应用程序需要缩放,不需要操作管理,零闲成本要求的工作量,多区域活性写作,或者不需要行级安全,触发,程序,或PL/pgSQL功能的任何SQL应用程序.

**不使用时 :** 如果需要行级安全,触发器,程序,或PL/pgSQL函数——使用 `Database` (奥罗拉语). Aurora DSQL支持SQL语言功能. 如果您需要交易, 且交易不能在争议中失败 `Database`如果连接到Supabase——使用 `Database` 与 `fromExisting()`。 。 。 .

> 设计与模拟等价细节 : [设计](https://npmcn.com/package/%40aws-blocks/bb-distributed-data/DESIGN.md)

## 快速启动

```typescript
import { DistributedDatabase, sql } from '@aws-blocks/bb-distributed-data';

const db = new DistributedDatabase(scope, 'main', {
  migrationsPath: './aws-blocks/dsql-migrations',
});

// Same query API as Database — parameterized via sql tagged template
const users = await db.query<{ id: string; name: string }>(
  sql`SELECT * FROM users WHERE active = ${true}`
);

const user = await db.queryOne<{ id: string; name: string }>(
  sql`SELECT * FROM users WHERE id = ${userId}`
);

const { rowCount } = await db.execute(
  sql`INSERT INTO users (id, name, email) VALUES (${id}, ${name}, ${email})`
);
```

## 交易(货币管制)

DSQL使用OCC——如果另一笔交易修改了同一行,交易可能会失败. 回调执行一次, 除非你选择重试 .

```typescript
// Default: no retry. Throws SerializationFailureException (HTTP 409 Conflict, retriable) on conflict.
await db.transaction(async (tx) => {
  await tx.execute(sql`UPDATE accounts SET balance = balance - ${100} WHERE id = ${fromId}`);
  await tx.execute(sql`UPDATE accounts SET balance = balance + ${100} WHERE id = ${toId}`);
});

// Opt-in retry: callback may execute multiple times.
// ⚠️ Do NOT include external side effects (HTTP calls, emails) inside.
await db.transaction(async (tx) => {
  await tx.execute(sql`UPDATE accounts SET balance = balance - ${100} WHERE id = ${fromId}`);
  await tx.execute(sql`UPDATE accounts SET balance = balance + ${100} WHERE id = ${toId}`);
}, { retryOnConflict: true, maxRetries: 3 });
```

第二个论点 `transaction()` 接受:

```typescript
interface TransactionOptions {
  /** Retry on OCC conflict. Callback may execute multiple times. @default false */
  retryOnConflict?: boolean;
  /** Max retry attempts. Only applies when retryOnConflict is true. @default 3 */
  maxRetries?: number;
}
```

## 移徙

每个文件有一个DDL语句. DML在不同的文件中。 这符合DSQL的交易限制.

```
aws-blocks/dsql-migrations/
  001_create_users.sql       ← single DDL
  002_create_posts.sql       ← single DDL
  003_create_index.sql       ← single DDL (CREATE INDEX ASYNC)
  004_seed_admin.sql         ← DML only
```

```sql
-- 001_create_users.sql
CREATE TABLE users (
  id TEXT PRIMARY KEY DEFAULT gen_random_uuid(),
  email TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

```sql
-- 003_create_index.sql
CREATE INDEX ASYNC idx_users_email ON users(email);
```

移民情况得到检查 [`dsql-lint`](https://github.com/awslabs/aurora-dsql-tools/tree/main/dsql-lint) 在合成时间.

> **设定 `migrationsPath` 与工程根相对的路径** (例如:. `'./aws-blocks/dsql-migrations'`); 由您运行的目录合成解析 `cdk` 编号 : `npm run deploy` 进来 这是最简单的可靠模式.
> 
> 你用不着 `fileURLToPath(import.meta.url)` 为了这个 您的后端模块在当地作为无害环境管理运行,但捆绑到 **常见JS** 在兰布达,在那里 `import.meta` 为空。 AWS 屏蔽闪烁 `import.meta.url` 编号 : `import.meta.dirname` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}所以它不会在装货时坠毁 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}但是在运行时 **捆绑输出** 位置,而不是您的源树。 所以别用 `import.meta.url` 在请求的时间读取与您来源相关的文件; 输入数据或将其作为Lambda资产.

## 邮递SQL 兼容性

Aurora DSQL是 PostgreSQL 有线-protocol相容的. SQL 特性兼容性不同于 PostgreSQL; 见 [Aurora DSQL SQL 兼容文档](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility.html) 详细情况.

| 未支持 | 备选案文 |
| --- | --- |
| 行级安全 | 在应用程序代码中过滤条款的位置 |
| 触发器 | 事件驱动逻辑(Event Bridge、Lambda) |
| 程序 | `LANGUAGE SQL` 函数或应用程序逻辑 |
| PL/pgSQL 函数 | `LANGUAGE SQL` 函数或应用程序逻辑 |
| 职位/职位 | `BIGINT GENERATED BY DEFAULT AS IDENTITY (CACHE 1)` 或 UUID (% 1) (`gen_random_uuid()`(三); `CACHE` 用于身份栏和序列,必须是 `1` 或者说 `>= 65536` |
| 特伦特 | `DELETE FROM` |
| 临时表格 | CTEs 或子电池 |
| 听/通知 | AppSync事件、事件桥或民意调查 |
| 扩展 | 不详 |
| ADD COLUMN 与国防 | 在不默认情况下添加列, 回填已存在的行, 然后使用 `ALTER COLUMN ... SET DEFAULT` |
| 索引密钥排序方向( E)`ASC`编号 :`DESC`(中文(简体) ) | 关闭它; 执行命令 `ORDER BY` 查询(`NULLS FIRST/LAST` 已支持) |

### 交易限制

| 约束 | 限制 |
| --- | --- |
| 货币模型 | OCC(可能发生冲突) |
| 隔离级别 | 固定: 可重复读取 |
| 每个交易的最大行变异 | 3 000个 |
| 每笔交易的最大数据 | 10个小米B |
| 最大交易期限 | 5分钟 |
| 每笔交易的DDL | 1个最大语句 |
| DDL + DML 混合 | 不允许 |

## Kysely 查询构建器

```typescript
import { createKyselyAdapter } from '@aws-blocks/bb-distributed-data';

interface Schema {
  users: { id: string; email: string; name: string };
}

const kysely = createKyselyAdapter<Schema>(db);

const users = await kysely
  .selectFrom('users')
  .where('email', '=', 'user@example.com')
  .selectAll()
  .execute();
```

别用Kysely的 `.addForeignKeyConstraint()` - 它会在DSQL上失败.

## 处理错误

```typescript
import { DistributedDatabaseErrors } from '@aws-blocks/bb-distributed-data';
import { isBlocksError } from '@aws-blocks/core';

try {
  await db.transaction(async (tx) => { /* ... */ });
} catch (e: unknown) {
  if (isBlocksError(e, DistributedDatabaseErrors.SerializationFailure)) {
    // OCC conflict — transaction was NOT committed. Serialized as HTTP 409
    // (Conflict), retriable — safe to retry.
  }
  if (isBlocksError(e, DistributedDatabaseErrors.UniqueConstraintViolation)) {
    // Duplicate key — serialized as HTTP 409 (Conflict), not retriable
    // (a blind retry of the same insert fails identically).
  }
  if (isBlocksError(e, DistributedDatabaseErrors.QueryFailed)) {
    // General query failure
  }
  if (isBlocksError(e, DistributedDatabaseErrors.TransactionRowLimitExceeded)) {
    // More than 3,000 rows mutated in one transaction
  }
  if (isBlocksError(e, DistributedDatabaseErrors.ConnectionFailed)) {
    // Cannot reach the DSQL cluster
  }
  if (isBlocksError(e, DistributedDatabaseErrors.TransactionFailed)) {
    // Transaction could not commit (general failure distinct from serialization/row-limit)
  }
}
```

## 测试 OCC 冲突

模型提供了 `simulateConflict()` 单位测试的助手。 它只与本地的嘲弄相悖: 部署 AWS 运行时间 `cdk synth` 它抛出通常的合成时错误.

```typescript
db.simulateConflict(); // next commit will fail with SerializationFailureException

await expect(db.transaction(fn)).rejects.toThrow('SerializationFailureException');
```

```typescript
db.simulateConflict(); // first attempt fails, second succeeds
const result = await db.transaction(fn, { retryOnConflict: true });
```

## 它的规定

-   **奥罗拉DSQL集群** ——无服务器,不需要VPC,公开端点
-   **移徙Lambda** —运行 `.sql` 关于通过自定义资源进行再试部署的文件
-   **行政会议** —— 说 `dsql:DbConnect` (app Lambda,仅限DML), `dsql:DbConnectAdmin` (移民兰布达,DDL)
-   **环境变量** —— 说 `BLOCKS_{name}_ENDPOINT`, (中文(简体) ), `BLOCKS_{name}_REGION`

没有VPC,没有秘密,没有安全小组,没有代理. DSQL使用 IAM 令牌认证.

## 地方发展

-   **引擎 :** PGlite (WASM PostgreSQL) 由 DSQL 兼容层所包裹
-   **存储 :** `.bb-data/{fullId}/` ——在重启期间坚持不懈
-   **验证 :** `dsql-lint` 在 PGlite 执行前检查 SQL
-   **交易跟踪 :** DDL/DML混合和3 000行限制在当地执行

迁移 SQL 还检查过 `dsql-lint` 在CDK合成时,在捆绑用于部署之前.

## 配置

```typescript
interface DistributedDatabaseOptions {
  /** Path to directory containing numbered .sql migration files. */
  migrationsPath?: string;
  /** Removal policy. @default 'retain' */
  removalPolicy?: 'destroy' | 'retain';
  /** Optional logger for internal operations. When omitted, a default Logger at error level is created. */
  logger?: ChildLogger;
}
```

## 软件包导出条件

```json
{
  "exports": {
    ".": {
      "cdk": "./dist/index.cdk.js",
      "aws-runtime": "./dist/index.aws.js",
      "default": "./dist/index.mock.js"
    }
  }
}
```

## 与数据库的差异(奥罗拉)

| 侧面 | `Database` (bb-data) (英语) | `DistributedDatabase` (bb-分布数据) |
| --- | --- | --- |
| 发动机 | Aurora 无服务器 v2(数据 API) | 奥罗拉 DSQL (pg + IAM) |
| PostgreSQL 兼容性 | 满 | 电线协议兼容; 见 [SQL 兼容性细节](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility.html) |
| 交易 | 悲观主义(准确的一) | OCC(可能发生冲突) |
| `withRLS()` | ✅ | ❌ |
| `fromExisting()` | ✅ | ❌ |
| `crud()` | ✅ | ❌ |
| 外国密钥 | ✅ | ✅ |
| 多国 | ❌ | 积极活动 |
| 要求 | 对 | 没有 |
| 部署时间 | ~10分钟 | 秒数 |
| 闲置费用 | 0美元(0 ACU) | 0美元 (单位:美元) |

## 常见问题

### @aws-blocks/bb-distributed-data 是什么？

无服务器SQL数据库由亚马逊·奥罗拉DSQL支持\. 0-ops,即时提供,规模为零,可选的多区域活性写作\.

### 如何安装 @aws-blocks/bb-distributed-data？

在项目目录运行 npm install @aws-blocks/bb-distributed-data，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：kysely（\>=0\.28\.12 \<0\.30\.0）、constructs（^10\.6\.0）、aws-cdk-lib（\>=2\.100\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-blocks/bb-distributed-data 支持 TypeScript 吗？

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

### @aws-blocks/bb-distributed-data 支持 ESM 还是 CommonJS？

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

### @aws-blocks/bb-distributed-data 可以商用吗？

@aws-blocks/bb-distributed-data 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-blocks/bb-distributed-data 的下载量有多少？

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

### @aws-blocks/bb-distributed-data 还在维护吗？

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