# @cloudbase/database

> database for (node.)js sdk

Latest version **2.0.0** (published 2026-10-21) · ISC license · 0 weekly downloads

## Install

```sh
npm install @cloudbase/database
pnpm add @cloudbase/database
yarn add @cloudbase/database
bun add @cloudbase/database
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-10-21 |
| First published | 2019-03-27 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 645.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | starkwang, yhyang, binggg, fengkx, liuyanjie, justan, woodenstone, miusuncle, yuzhen, wedabot, joeyren, byronpiao, yandrewding, areo-joe, coylexie, lukejyhuang |

## Links

- npm: https://www.npmjs.com/package/@cloudbase/database
- npm.io page: https://npm.io/package/@cloudbase/database

## Dependencies (1)

- [bson](https://npm.io/package/bson.md) ^6.10.4

## Recent versions

- 2.0.0 (latest) — 2026-10-21
- 1.5.1 (next) — 2026-09-03
- 0.10.0-alpha.0 (alpha) — 2025-12-29
- 0.9.18-beta (beta) — 2020-08-12
- 1.5.0 — 2026-08-21
- 0.12.1 — 2026-04-30
- 0.12.0 — 2026-04-21
- 0.11.0 — 2026-01-22
- 1.4.3 — 2026-01-14
- 0.10.0 — 2026-01-13
- 1.4.3-alpha.0 — 2025-12-26
- 0.9.22 — 2024-07-31
- 0.9.21 — 2024-04-25
- 0.9.20 — 2023-07-03
- 1.4.2 — 2023-07-03
- … 66 more at https://npm.io/package/@cloudbase/database/versions

## 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 均通过锁版本方式依赖该库，不会受自动更新依赖影响。

---
_Source: https://npm.io/package/@cloudbase/database · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._