开发指南

在项目中启用扩展数据库

扩展数据库作为uniCloud的一个扩展库，使用时需要在云函数或者云数据库中启用。

注意

1. 需要 HBuilderX 4.71+ 的版本（暂未发版）才能进行此操作，如低于此版本，请查看手动升级HBuilderX教程
2. 云函数设置的Node.js版本需要 ≥ Nodejs16，推荐使用Nodejs18，查看设置云函数Nodejs版本教程

欢迎进入扩展数据库技术交流群

查看手动升级HBuilderX教程

1. 下载压缩包 unicloud.zip
2. 复制 unicloud.zip 到/HBuilderX/plugins 目录下
3. 右键 unicloud.zip，提取到当前位置，当出现弹窗是否需要替换文件时，点全部替换

设置云函数Nodejs版本教程

打开云函数根目录的 package.json 文件，添加以下配置

设置为Nodejs18

"cloudfunction-config": {
  ...你的其他配置
  "runtime": "Nodejs18",
}

设置为Nodejs16

"cloudfunction-config": {
  ...你的其他配置
  "runtime": "Nodejs16",
}

云函数/云对象操作步骤

在云函数或云对象中使用扩展数据库，需要进行如下操作：

1. 在 云函数/云对象 上右键，并点击 - 管理公共模块或扩展库依赖

2. 勾选 uni-cloud-ext-database 扩展库

3. 上传云函数/云对象

云数据库（clientDB）操作步骤

如果你还使用了clinetDB或JQL，还需要进行如下操作：

1. 在 uniCloud/database 目录右键，并点击 - 配置Shema扩展JS的公共模块或扩展库

2. 勾选 uni-cloud-ext-database 扩展库

3. 再在 uniCloud/database 目录右键，并点击 - 上传Schema扩展Js的配置

API

扩展数据库已包含内置数据库拥有的所有API，并且还拥有以下特殊API

切换数据库实例

注意：需要先在扩展数据库控制台授权空间后，此空间才能使用

// 返回的db对象就是连接指定数据库实例的db对象
const db = uniCloud.database({
	id: "数据库实例ID"
});

切换数据库

// 返回的db对象就是连接指定库名的db对象
const db = uniCloud.database({
	database: "数据库实例下的数据库名称"
});

切换数据库实例和库

// 返回的db对象就是连接指定数据库实例且指定了库名的db对象
const db = uniCloud.database({
	id: "数据库实例ID",
	database: "数据库实例下的数据库名称"
});

获取原生MongoDB操作对象

API

uniCloud.databaseForNative(options: Options): Promise<Db>

Options

参数名	类型	必填	默认值	说明
id	string	否	-	数据库实例id
database	string	否	-	数据库名称

Db

Db 实例是 MongoDB 的数据库对象，提供了对数据库的操作方法。 详细的 API 参考 MongoDB Db Class

示例

// 获取默认数据库实例
const dbNative = await uniCloud.databaseForNative();

// 切换数据库
const dbNative = await uniCloud.databaseForNative({
	database: "数据库名称",
});

MongoDB 基本概念

• 数据库： MongoDB 存储数据的基本单位，类似于关系型数据库中的数据库。
• 集合：MongoDB 文档的存储单位，类似于关系型数据库中的表。
• 文档：存储文字数据的基本单位，类似于关系型数据库中的行。更多关于文档的概念可以参考 MongoDB 文档

新建集合（表）

在首次向不存在的集合中插入数据时，MongoDB 会隐式创建集合。如果要显式创建集合，可以使用 createCollection 方法。

API

db.createCollection(name: string, options?: CreateCollectionOptions): Promise<Collection>

name

集合名称

CreateCollectionOptions

参考

Collection

参考

示例

const dbNative = await uniCloud.databaseForNative();

// 创建名为 book 的集合
await dbNative.createCollection('book');

获取集合列表

API

db.listCollections(filter?: Document, options?: ListCollectionsOptions): ListCollectionsCursor

Document

参考

ListCollectionsOptions

参考

ListCollectionsCursor

ListCollectionsCursor 是一个游标对象，用于遍历集合列表。它提供了多种方法来处理查询结果，例如 toArray()、forEach() 等。

• toArray()：将游标中的所有文档转换为数组。
• 异步迭代器：可以使用 for await...of 循环来遍历游标中的文档。关于异步迭代器参考AsyncIterator

其他方法和属性可以参考 ListCollectionsCursor

示例

const dbNative = await uniCloud.databaseForNative();

// 获取集合列表 (toArray)
const collections = await dbNative.listCollections().toArray();
console.log(collections);

// 获取集合列表 (异步迭代)
const collections = dbNative.listCollections();
for await (const collection of collections) {
  console.log(collection);
}

// 仅查询集合名称
const onlyNameCollections = await dbNative.listCollections({}, { nameOnly: true }).toArray();
console.log(onlyNameCollections);

新建集合索引

API

collection.createIndex(indexSpec: IndexSpecification, options?: CreateIndexesOptions): Promise<string>

IndexSpecification

IndexSpecification 是一个对象，定义了索引的字段和排序方式。它的键是要索引的字段名，值是排序方式（1 表示升序，-1 表示降序，2dsphere 表示地理空间索引，2d 表示二维索引等）。

参考

CreateIndexesOptions

参考

示例

const dbNative = await uniCloud.databaseForNative();
const collection = dbNative.collection('book');

// 创建索引（单字段索引）
await collection.createIndex({ title: 1 });

// 自定义索引名称
await collection.createIndex({ title: 1 }, { name: 'title_index' });

// 创建唯一索引
await collection.createIndex({ title: 1 }, { unique: true });

// 创建地理空间索引
await collection.createIndex({ location: '2dsphere' });

// 后台创建索引
await collection.createIndex({ title: 1 }, { background: true });

// 创建索引（复合索引）
await collection.createIndex({ title: 1, author: -1 });

获取集合索引

API

collection.listIndexes(options?: ListIndexesOptions): ListIndexesCursor

ListIndexesOptions

参考

ListIndexesCursor

参考

示例

const dbNative = await uniCloud.databaseForNative();
const collection = dbNative.collection('book');

// 获取索引列表 (toArray)
const indexes = await collection.listIndexes().toArray();
console.log(indexes);

删除集合索引

API collection.dropIndex(indexName: string, options?: CommandOperationOptions): Promise<Document>

CommandOperationOptions

参考

示例

const dbNative = await uniCloud.databaseForNative();
const collection = dbNative.collection('book');

// 删除索引
await collection.dropIndex('title_index');

注意

1. _id 索引是MongoDB默认创建的索引，不可以删除。

删除表所有索引

API

collection.dropIndexes(options?: CommandOperationOptions): Promise<boolean>

CommandOperationOptions

参考

示例

const dbNative = await uniCloud.databaseForNative();
const collection = dbNative.collection('book');

// 删除所有索引
await collection.dropIndexes();

注意

1. _id 索引是MongoDB默认创建的索引，删除所有索引时不会删除 _id 索引。

授权绑定空间

进入uniCloud控制台，进入扩展数据库首页

选择对应的数据库，进入详情后，再点击左侧菜单-空间授权管理

在弹窗中输入对应的信息，如下图所示

性能监控

进入扩展数据库详情页，点击左侧菜单-性能监控

慢日志查询

进入扩展数据库详情页，点击左侧菜单-慢日志查询

注意：扩展数据库没有慢日志限流，此处显示慢日志是为了方便你优化数据库代码，提升系统响应速度

参数设置

进入扩展数据库详情页，点击左侧菜单-参数设置

IP白名单

进入扩展数据库详情页，点击左侧菜单-IP白名单设置

成员管理

进入扩展数据库详情页，点击左侧菜单-成员管理，如下图所示

可以添加以下几种角色的成员

角色	权限说明
普通成员	实例详情、性能监控、慢日志查询、参数查看、备份查看
管理员	除成员管理外的功能
超级管理员	所有功能

注意：变配和续费仅主账号才能操作。

常见问题

使用扩展数据库后，我原先的项目代码是否需要修改？

不需要修改，只需要关联扩展数据库的扩展库，并重新上传云函数和JQL的JS扩展即可，详情见在项目中启用扩展数据库

内置数据库如何迁移到扩展数据库？

特别注意： 只有阿里云、腾讯云空间的内置数据库可按下方步骤导出导入数据，如果是支付宝云空间，请进入扩展数据库技术交流群协助迁移数据

进入内置数据库控制台，选择表，点导出，然后使用扩展数据库的数据库可视化管理工具，将导出的json文件导入即可，具体操作如下：

1. 进入内置数据库控制台，点击-云数据库-选择对应的表-点导出，如下图所示（因为内置数据库不支持批量导出表数据，因此以下步骤每个表都要这样操作一下）

2. 在弹窗中，选择导出格式为JSON，然后点确定，等待导出，最终浏览器会自动下载。

3. 打开 MongoDB Compass 数据库可视化管理工具，选择对应的库，再选择对应的表，没有表就新建表，关于 MongoDB Compass 的操作帮助请点击查看

4. 选择对应的表后，再按下图所示导入第1步导出的JSON文件即可。