# @cloudbase/database 中文文档

规范地址：https://npmcn.com/package/%40cloudbase/database/

版本：2\.0\.0
npm 元数据更新时间：2026-10-21T09:42:53.968Z
中文译文更新时间：2026-11-10T02:36:15.076Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40cloudbase/database
原文对照：https://npmcn.com/package/%40cloudbase/database/?lang=original

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

- 包体积（解压后）：661 kB，232 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2019-03-27T02:19:38.086Z
- 最新版本发布：2026-10-21T09:42:53.655Z
- 近 30 天下载量：148471（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 10 个）

## 中文简介

用于(节点.)js sdk的数据库

## 安装

```sh
npm install @cloudbase/database
```

也可以使用：`pnpm add @cloudbase/database`、`yarn add @cloudbase/database`、`bun add @cloudbase/database`

## README

# @cloudbase/database

[![NPM Version](https://img.shields.io/npm/v/@cloudbase/database.svg?style=flat)](https://www.npmjs.com/package/@cloudbase/database) [![](https://img.shields.io/npm/dt/@cloudbase/database.svg)](https://www.npmjs.com/package/@cloudbase/database)

## 介绍

提供 TCB JS SDK 操作数据库的接口。

## 安装

```
yarn add @cloudbase/database
```

## 使用

使用 `@cloudbase/database` 时，需要提供发送请求的类 `reqClass`。

```js
// index.js

const database = require('@cloudbase/database/').Db;
const Request = require('./request');

class Tcb {
  ...
  database(dbConfig) {
    database.reqClass = Request;
    return new database(dbConfig);
  }
}
```

实现 `Request` 类，需要提供异步的 `send` 方法。

```js
// request.js

// 进一步处理，鉴权等...
const requestHandler = require('requestHandler')

class Request {
  constructor(config) {
    this.config = config
  }

  async send(action, data) {
    const params = Object.assign({}, data, {
      action
    })

    const slowQueryWarning = setTimeout(() => {
      console.warn(
        'Database operation is longer than 3s. Please check query performance and your network environment.'
      )
    }, 3000)

    try {
      return await requestHandler({
        timeout: this.config.timeout,
        config: this.config.config,
        params,
        method: 'post',
        headers: {
          'content-type': 'application/json'
        }
      })
    } finally {
      clearTimeout(slowQueryWarning)
    }
  }
}

module.exports = Request
```

请求数据样例

```json
{
  "url": "https://tcb-admin.tencentcloudapi.com/admin?eventId=1554896261428_92044",
  "method": "post",
  "timeout": 15000,
  "headers": { "user-agent": "tcb-admin-sdk/1.4.6", "content-type": "application/json" },
  "body": {
    "collectionName": "coll-1",
    "action": "database.addCollection",
    "envName": "base-830cab",
    "timestamp": 1554896261428,
    "eventId": "1554896261428_92044",
    "authorization": "q-sign-algorithm=sha1&q-ak=xxx&q-sign-time=1554896260;1554897160&q-key-time=1554896260;1554897160&q-header-list=content-type;user-agent&q-url-param-list=action;collectionname;envname;eventid;timestamp&q-signature=xxxxx",
    "sdk_version": "1.4.6"
  },
  "json": true
}
```

## 开发指南

### 注意

当前 database 库是通过分支来控制了两个不同的版本，主干版提供给@cloudbase/js-sdk 库使用，feature/support\_db\_2.0 分支提供给@cloudbase/node-sdk 库使用。

两个分支区别： support\_db\_2.0 分支进行了数据库接口的升级，将原有的 json 协议转换为 mongo 支持的 bson 协议处理，目的是解决旧接口存在的问题，描述如下

-   日期对象 是走约定协议处理，即转换为 {$date: timestamp}，这种方式应摒弃(EJSON 协议可解决)
-   无法支持 null, NaN 等特殊类型处理(EJSON 协议可解决)
-   serverDate 这种自定义类型的实现，是继续保留 还是摒弃
-   接口实现混杂，普通 CRUD 接口均走 flexdb，而聚合，事务又用 runcommand 方式
-   原插入文档接口返回 docId 形式混杂

目前仅针对服务端 sdk @cloudbase/node-sdk 完成了升级，而客户端 sdk @cloudbase/js-sdk 以及 小程序端 SDK 仍保留为旧接口形式。

### 开发及发布事项

1.  数据库接口的改动务必补充测试用例验证
2.  发布时，约定 feature/support\_db\_2.0 分支上发布正式版（for @cloudbase/node-sdk）使用，master 分支上发布 beta 版 (for @cloudbase/js-sdk)使用。两 sdk 均通过锁版本方式依赖该库，不会受自动更新依赖影响。

## 常见问题

### @cloudbase/database 是什么？

用于\(节点\.\)js sdk的数据库

### 如何安装 @cloudbase/database？

在项目目录运行 npm install @cloudbase/database，或使用 pnpm add / yarn add / bun add。

### @cloudbase/database 支持 TypeScript 吗？

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

### @cloudbase/database 支持 ESM 还是 CommonJS？

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

### @cloudbase/database 可以商用吗？

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

### @cloudbase/database 的下载量有多少？

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

### @cloudbase/database 还在维护吗？

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