连接自有 MongoDB

您可以将腾讯云 MongoDB 数据库接入云开发平台，复用现有数据库资源，降低数据迁移成本。

接入腾讯云数据库后，您可以：

无缝集成：直接管理现有数据库中的数据，无需数据迁移
数据模型：基于现有集合快速生成数据模型，自动化数据管理
SDK 支持：使用云开发 Web SDK / Node SDK / 小程序 SDK 统一访问
安全可控：数据保留在您的数据库中，完全掌控数据安全

注意

当前仅支持连接「相同地域腾讯云 MongoDB 数据库」，暂不支持其他云服务商或自建的 MongoDB 数据库。

前置条件

在配置腾讯云 MongoDB 数据库连接前，请确保：

检查项	要求
数据库来源	必须是腾讯云 MongoDB 数据库实例
网络访问	数据库具有公网访问能力或已配置内网访问
用户权限	已创建专用数据库用户账号，具备集合操作权限
防火墙配置	数据库防火墙已开放相应端口（MongoDB 默认 27017）
IP 白名单	已配置云开发服务 IP 白名单（见文档末尾）

创建连接配置

1. 进入配置页面

访问云开发平台/文档型数据库，点击顶部「新增连接」按钮

文档型数据库新增页面

2. 填写连接信息

参数	说明	必填
配置名称	自定义名称，用于在平台中识别此连接	是
配置标识	英文标识符，用于 SDK 中指定连接（如 `my-mongodb`）	是
数据库名	要连接的目标数据库名称	是
用户名	数据库连接用户名	是
密码	数据库连接密码	是
连接参数	额外的 MongoDB 连接参数（如 `authSource=admin`）	否
超时时间	连接和查询的超时时间（单位：秒）	否

3. 设置默认实例(可选)

创建连接配置后，您可以将其设置为默认实例，简化代码调用。

默认实例的作用

数据模型支持：默认数据库支持创建数据模型，可通过数据模型的 API 操作数据，也可在微搭低代码中使用模型方法
SDK 自动连接：所有 SDK（JavaScript/Node.js/小程序）在调用相关接口时，若不主动指定目标实例与数据库，将会默认指向该默认实例的默认数据库

设置方法

访问云开发平台/文档型数据库/连接管理，在目标连接配置处点击「设置为默认实例」按钮。

切换影响

默认数据库的切换可能影响业务代码中原数据库的调用方式，建议检查代码后在业务低峰期进行操作。

受影响的 SDK 调用示例：

小程序：wx.cloud.database()（未指定 instance 参数）
Web SDK：app.database()（未指定 instance 参数）
Node SDK：app.database()（未指定 instance 参数）

使用方式

接入自有 NoSQL 数据库后，可通过以下两种方式操作数据。

方式一：直接操作数据库集合

直接通过 SDK 进行 CRUD 操作

小程序
Web
Node.js

方式 1：使用默认实例（wx 原生 API，仅中国站可用）

小程序中使用 wx.cloud.database() 调用的是默认数据库实例。如需访问腾讯云 MongoDB 数据库，请先在云开发控制台将其设置为「默认实例」。

// 初始化云开发
wx.cloud.init({
  env: "your-env-id", // 替换为您的环境ID
});

// 自动连接默认实例（无需指定 instance）
const db = wx.cloud.database();

const result = await db
  .collection("users")
  .where({
    status: "active",
  })
  .get();

方式 2：使用 JS SDK 指定实例

通过 @cloudbase/js-sdk 可以明确指定要访问的数据库实例。

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id", // 替换为您的环境ID
  region: "ap-shanghai", // 不指定 region 时，默认使用 ap-shanghai
});

// 登录认证
const auth = app.auth();
await auth.signInWithOpenId();

// 指定访问腾讯云 MongoDB 实例
const db = app.database({
  instance: "my-mongodb", // 配置标识
  database: "test",
});

const result = await db
  .collection("users")
  .where({
    status: "active",
  })
  .get();

// 引入 SDK
import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id", // 替换为你的环境ID
  region: "ap-shanghai", // 不指定 region 时，默认使用 ap-shanghai
});

// 登录认证
const auth = app.auth();
await auth.signInAnonymously(); // 或使用其他登录方式

// 连接自有数据库实例
const db = app.database({
  instance: "my-mongodb", // 配置标识（创建连接时填写的标识）
  database: "test", // 数据库名称
});

// 查询数据
const result = await db
  .collection("users")
  .where({
    status: "active",
  })
  .get();

if (result.data) {
  console.log("查询结果:", result.data);
} else {
  console.error("查询失败:", result.errMsg);
}

// 引入 SDK
const cloudbase = require("@cloudbase/node-sdk");

const app = cloudbase.init({
  env: "your-env-id", // 替换为你的环境ID
});

// 连接自有数据库实例
const db = app.database({
  instance: "my-mongodb", // 配置标识
  database: "test", // 数据库名称
});

// 查询数据
const result = await db
  .collection("users")
  .where({
    status: "active",
  })
  .limit(10)
  .get();

console.log(result.data);

参数说明

instance：创建连接配置时填写的「配置标识」
database：目标数据库名称
查询语法请参考：Web SDK 或 Node SDK

方式二：使用数据模型

适用于需要结构化数据管理、自动校验、关联查询等场景。

1. 创建数据模型

访问云开发平台/文档型数据库/连接管理，在对应连接配置处点击「数据模型」

选择现有集合，系统将自动生成对应的数据模型。

2. 操作数据模型

小程序
Web
Node.js

// 引入 SDK
const { init } = require("@cloudbase/wx-cloud-client-sdk");

wx.cloud.init({
  env: "your-env-id", // 替换为你的环境ID
});

const client = init(wx.cloud);
const models = client.models;

// 创建数据（假设已创建 todos 模型）
const { data, error } = await models.todos.create({
  data: {
    title: "学习云开发",
    completed: false,
  },
});

// 查询数据
const todos = await models.todos.findMany({
  where: {
    completed: false,
  },
  orderBy: {
    createdAt: "desc",
  },
});

console.log(todos);

// 引入 SDK
import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id", // 替换为你的环境ID
  region: "ap-shanghai", // 不指定 region 时，默认使用 ap-shanghai
});

// 登录认证
const auth = app.auth();
await auth.signInAnonymously();

// 创建数据（假设已创建 todos 模型）
const { data, error } = await app.models.todos.create({
  data: {
    title: "学习云开发",
    completed: false,
  },
});

// 查询数据
const todos = await app.models.todos.findMany({
  where: {
    completed: false,
  },
  orderBy: {
    createdAt: "desc",
  },
});

console.log(todos);

const cloudbase = require("@cloudbase/node-sdk");

const app = cloudbase.init({
  env: "your-env-id", // 替换为你的环境ID
});

// 创建数据
const { data } = await app.models.todos.create({
  data: {
    title: "学习云开发",
    completed: false,
  },
});

// 更新数据
await app.models.todos.update({
  where: {
    id: data.id,
  },
  data: {
    completed: true,
  },
});

提示

详细使用方法请参考数据模型文档

常见问题

数据会被同步到云开发吗？

不会。连接自有数据库后：

数据存储：所有数据仍保留在您的数据库中
访问方式：云开发 SDK 直接连接您的数据库进行操作
数据控制：您完全掌控数据的存储和备份

前置条件​

创建连接配置​

1. 进入配置页面​

2. 填写连接信息​

3. 设置默认实例(可选)​

默认实例的作用​

设置方法​

使用方式​

方式一：直接操作数据库集合​

方式二：使用数据模型​

1. 创建数据模型​

2. 操作数据模型​

常见问题​

数据会被同步到云开发吗？​