# @drizzle-adapter/tidb-serverless 中文文档

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

版本：1\.0\.10
npm 元数据更新时间：2025-07-11T21:09:15.874Z
中文译文更新时间：2026-11-12T20:16:19.125Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：88.3 kB，61 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2024-12-03T05:43:02.859Z
- 最新版本发布：2025-07-11T21:09:15.663Z
- 近 30 天下载量：20320（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 0 个）

## 中文简介

TiDB 无服务器适配器执行 Drizzle适配器生态系统.

## 安装

```sh
npm install @drizzle-adapter/tidb-serverless
```

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

## README

# @ 细雨适应器/ tidb- server

TiDB 无服务器适配器执行 Drizzle适配器生态系统.

## 概览

这个 `@drizzle-adapter/tidb-serverless` 软件包为 Drizzle 适配器接口提供 TiDB 无服务器执行。 虽然你不直接与此软件包互动( 您使用 `@drizzle-adapter/core` 相反,它为Drizzle适配器生态系统中的TiDB服务器提供了支持.

## 为什么没有TiDB服务器?

TiDB 无服务器为现代应用提供了独特的优势:

-   **分布的 SQL**: TiDB 是一个分布式SQL数据库,在保持强烈一致性的同时水平缩放
-   **MySQL 兼容性**: 100% MySQL 兼容,同时提供分布式能力
-   **自动缩放**: 根据工作量自动计算和储存资源
-   **无服务器定价**: 只支付每秒计费使用的费用
-   **HTAP 能力**: 实时分析的双重交易和分析处理
-   **全球分布**: 跨区域部署自动复制数据
-   **高可用性**: 内置高可用性,自动故障
-   **实时分析**: 运行复杂的分析查询和交易工作量

### 完美为:

1.  **微服务**: 独立调整个人服务规模
2.  **全球应用**: 为全球低延迟用户服务
3.  **实时分析**:同时处理交易和分析工作量
4.  **成本敏感工作量**: 只按实际使用支付
5.  **高成长应用**: 从启动到企业的无缝规模

## 安装

```bash
# Install both the core package and the TiDB adapter
pnpm install @drizzle-adapter/core @drizzle-adapter/tidb-serverless
```

## 重要:适配器注册

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

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

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

## 使用量

### 配置

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

const config: TypeDrizzleDatabaseConfig = {
  DATABASE_DRIVER: 'tidb-serverless',
  DATABASE_URL: 'mysql://user:pass@your-cluster.tidbcloud.com:4000/your-database'
};

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

### Schema 定义

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

const users = dataTypes.dbTable('users', {
  id: dataTypes.dbBigInt('id', { mode: 'number' }).primaryKey().autoincrement(),
  name: dataTypes.dbVarChar('name', { length: 255 }).notNull(),
  email: dataTypes.dbVarChar('email', { length: 255 }).notNull().unique(),
  status: dataTypes.dbEnum('status', ['active', 'inactive']).default('active'),
  metadata: dataTypes.dbJson('metadata'),
  createdAt: dataTypes.dbTimestamp('created_at').defaultNow()
});

const posts = dataTypes.dbTable('posts', {
  id: dataTypes.dbBigInt('id', { mode: 'number' }).primaryKey().autoincrement(),
  userId: dataTypes.dbBigInt('user_id', { mode: 'number' })
    .references(() => users.id),
  title: dataTypes.dbVarChar('title', { length: 255 }).notNull(),
  content: dataTypes.dbText('content').notNull(),
  published: dataTypes.dbBoolean('published').default(false),
  createdAt: dataTypes.dbTimestamp('created_at').defaultNow()
});
```

### 基本 CRUD 操作

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

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

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

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

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

  // Select with conditions
  const activeUsers = await client
    .select()
    .from(users)
    .where(eq(users.status, 'active'));

  // Select with multiple conditions
  const specificPosts = await client
    .select()
    .from(posts)
    .where(
      and(
        eq(posts.userId, newUser.id),
        eq(posts.published, true)
      )
    );

  // Select with join
  const userPosts = await client
    .select({
      userName: users.name,
      postTitle: posts.title,
      postContent: posts.content
    })
    .from(posts)
    .leftJoin(users, eq(posts.userId, users.id))
    .where(eq(posts.published, true))
    .orderBy(desc(posts.createdAt));

  // Select with complex conditions
  const searchResults = await client
    .select()
    .from(posts)
    .where(
      or(
        eq(posts.published, true),
        eq(posts.userId, newUser.id)
      )
    )
    .orderBy(desc(posts.createdAt))
    .limit(10);

  // UPDATE
  // Update single record
  const [updated] = await client
    .update(users)
    .set({ name: 'John Smith' })
    .where(eq(users.id, newUser.id))
    .returning();

  // Update multiple records
  await client
    .update(posts)
    .set({ published: true })
    .where(eq(posts.userId, newUser.id));

  // DELETE
  // Delete single record
  await client
    .delete(users)
    .where(eq(users.id, newUser.id));

  // Delete with conditions
  await client
    .delete(posts)
    .where(
      and(
        eq(posts.userId, newUser.id),
        eq(posts.published, false)
      )
    );

} finally {
  await connection.disconnect();
}
```

## TiDB 特定特性

### 分布式交易

```typescript
const orders = dataTypes.dbTable('orders', {
  id: dataTypes.dbBigInt('id', { mode: 'number' }).primaryKey().autoincrement(),
  userId: dataTypes.dbBigInt('user_id', { mode: 'number' }),
  amount: dataTypes.dbDecimal('amount', { precision: 10, scale: 2 }),
  status: dataTypes.dbEnum('status', ['pending', 'completed', 'failed']),
  createdAt: dataTypes.dbTimestamp('created_at').defaultNow()
});

// TiDB handles distributed transactions automatically
async function createOrder(userId: number, amount: number) {
  const connection = await adapter.getConnection();
  const client = connection.getClient();

  try {
    const [order] = await client
      .insert(orders)
      .values({
        userId,
        amount,
        status: 'pending'
      })
      .returning();

    // Even in a distributed environment, this is ACID compliant
    return order;
  } finally {
    await connection.disconnect();
  }
}
```

### 实时分析

```typescript
const analytics = dataTypes.dbTable('analytics', {
  id: dataTypes.dbBigInt('id', { mode: 'number' }).primaryKey().autoincrement(),
  metric: dataTypes.dbVarChar('metric', { length: 255 }),
  value: dataTypes.dbDouble('value'),
  dimensions: dataTypes.dbJson('dimensions'),
  timestamp: dataTypes.dbTimestamp('timestamp').defaultNow()
});

// TiDB can handle analytical queries alongside transactional workloads
async function getMetricsTrends() {
  const client = await adapter.getConnection().getClient();
  
  return client
    .select({
      metric: analytics.metric,
      hourly_avg: sql`AVG(${analytics.value})`,
      hour: sql`DATE_FORMAT(${analytics.timestamp}, '%Y-%m-%d %H:00:00')`
    })
    .from(analytics)
    .groupBy(analytics.metric, sql`hour`)
    .orderBy(desc(sql`hour`));
}
```

## 最佳做法

1.  **连接管理**: 总是尝试/最后使用以确保连接被正确关闭
2.  **批量操作**: 尽可能使用批量插入/更新,以提高性能
3.  **交易**: 利用TiDB的分布式交易能力
4.  **查询优化**: 使用适当的索引和限制结果集
5.  **处理错误**: 对瞬态错误执行正确的再试逻辑

## 捐款

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

## 相关软件包

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

## 常见问题

### @drizzle-adapter/tidb-serverless 是什么？

TiDB 无服务器适配器执行 Drizzle适配器生态系统\.

### 如何安装 @drizzle-adapter/tidb-serverless？

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

### @drizzle-adapter/tidb-serverless 支持 TypeScript 吗？

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

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

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

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

@drizzle-adapter/tidb-serverless 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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