云数据库概述

云数据库是 CloudBase 提供的核心数据存储服务，为开发者提供高性能、高可用的数据管理能力。

📋 数据库类型一览

CloudBase 提供三种数据库解决方案，您可以根据业务需求灵活选择：

数据库类型	适用场景	核心优势
📄 文档型数据库	快速开发、灵活数据结构	NoSQL 灵活性，MongoDB 兼容
🗃️ MySQL 型数据库	传统业务、复杂查询	标准 SQL，事务支持
🔌 自有 MySQL 数据库	数据迁移、混合架构	现有数据复用，自主可控

💡 提示：不同类型的数据库可以在同一个环境中共存使用，根据具体业务场景选择最适合的数据库类型。

📄 云数据库（文档型）

🏗️ 架构特点

单实例设计：每个云开发环境有且仅有一个文档型数据库实例
灵活共存：可与其他类型数据库实例同时使用
MongoDB 兼容：基于腾讯云 MongoDB 服务构建

📚 核心概念

集合（Collection）

集合是数据操作的基本单位，类似于关系型数据库中的"表"概念。

命名规范：每个集合都有唯一的集合名，如 users、articles、orders 等
数据组织：一个数据库实例可以包含多个集合
记录归属：所有记录都必须归属于某个集合

记录（Record / Document）

文档型数据库中的每条记录都是一个 JSON 格式的文档对象，支持嵌套结构。

示例记录结构：

{
  "name": "Tom",
  "age": 18,
  "tags": ["developer", "student"],
  "location": {
    "country": "China",
    "province": "Guangdong",
    "city": "Shenzhen"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

🎯 文档型数据库优势

🔧 灵活的数据结构：无需预定义 schema，支持动态字段
📦 嵌套数据支持：天然支持复杂的嵌套对象和数组
🚀 快速开发：减少数据建模复杂度，加速开发进程
📈 水平扩展：更适合大规模数据和高并发场景

🔑 系统字段说明

文档型数据库包含两个重要的系统字段，用于数据管理和权限控制：

`_id` 字段 - 唯一标识符

自动生成：插入记录时系统自动生成唯一标识
全局唯一：在整个集合中保证唯一性
自定义支持：可以指定自定义 _id，但需确保唯一性

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "示例记录",
  // ... 其他字段
}

`_openid` 字段 - 创建者标识

用于标识记录的创建者身份，根据调用来源自动生成：

调用来源	`_openid` 含义	示例值
微信小程序	用户的微信 OpenID	`oGZUI0egBJY1zhBYw2KhdUfwVJJE`
Web SDK	用户的云开发 UID	`uid_12345678`

💡 重要说明

服务端调用（如云函数、控制台）创建的记录不会生成 _openid 字段，因为这些是管理员权限创建的记录，不属于特定用户。

🛡️ 权限控制价值

数据隔离：基于 _openid 实现用户数据隔离
安全访问：用户只能访问自己创建的数据
权限管理：结合安全规则实现细粒度权限控制

🔌 访问方式

云数据库（文档型）支持多端访问，满足不同开发场景的需求：

访问方式	适用场景	权限级别	鉴权要求
👤 用户端调用	Web、小程序、移动应用	用户权限	需要登录鉴权
🔧 服务端调用	云函数、服务器	管理员权限	腾讯云密钥

👤 用户端调用

使用场景：Web 网页、小程序、Flutter 等客户端应用

权限模式：以用户身份进行数据库操作，只能访问用户有权限的数据

安全机制：必须先完成登录鉴权才能访问数据库

🛡️ 为什么需要登录鉴权？

用户端代码可能被恶意用户获取和分析，攻击者可能通过伪造请求来盗用您的 CloudBase 资源。登录鉴权机制确保只有合法用户才能访问数据库，保护您的资源安全。

Web
小程序

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

const app = cloudbase.init({
  env: "xxxx",
});

/**
  登录鉴权流程，此处代码略，请参考：
  https://docs.cloudbase.net/authentication-v2/auth/introduce
*/

// 1. 获取数据库引用
var db = app.database();

// 2. 构造查询语句
db
  // collection() 方法获取一个集合的引用
  .collection("books")
  // where() 方法传入一个 query 对象，数据库返回集合中字段等于指定值的 JSON 文档。
  .where({
    name: "The Catcher in the Rye",
  })
  // get() 方法会触发网络请求，往数据库取数据
  .get()
  .then(function (res) {
    console.log(res);
    // 输出 [{ "name": "The Catcher in the Rye", ... }]
  });

// 1. 获取数据库引用
const db = wx.cloud.database();

// 2. 构造查询语句
db
  // collection() 方法获取一个集合的引用
  .collection("books")
  // where() 方法传入一个 query 对象，数据库返回集合中字段等于指定值的 JSON 文档。
  .where({
    name: "The Catcher in the Rye",
  })
  // get() 方法会触发网络请求，往数据库取数据
  .get()
  .then(function (res) {
    console.log(res);
    // 输出 [{ "name": "The Catcher in the Rye", ... }]
  });

🔧 服务端调用

使用场景：云函数、服务器端应用、后台管理系统

权限模式：以管理员身份进行数据库操作，拥有完整的数据访问权限

鉴权方式：使用腾讯云密钥（SecretID 和 SecretKey）进行身份验证

💡 云函数特殊说明

在 CloudBase 云函数环境中，系统会自动处理身份验证，无需手动配置腾讯云密钥即可直接使用服务端 SDK。

Node.js

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

const app = cloudbase.init({});

// 1. 获取数据库引用
var db = app.database();

exports.main = async (event, context) => {
  // 2. 构造查询语句
  const res = await db
    // collection() 方法获取一个集合的引用
    .collection("books")
    // where() 方法传入一个 query 对象，数据库返回集合中字段等于指定值的 JSON 文档。
    .where({
      name: "The Catcher in the Rye",
    })
    // get() 方法会触发网络请求，往数据库取数据
    .get();

  return {
    res,
  };
};

⚙️ 技术实现与特性

🏗️ 底层架构

云数据库（文档型）基于腾讯云 MongoDB 服务构建，提供企业级的数据存储能力：

🔧 完全兼容：100% 兼容 MongoDB 协议和语法
🚀 高性能：分布式架构，支持高并发访问
🛡️ 高可用：多副本部署，保障数据安全
📈 弹性扩展：支持存储和计算资源的弹性伸缩

📊 部署模式

根据云开发环境的规格，采用不同的部署策略：

环境规格	部署模式	特点	适用场景
基础套餐	共享实例	成本优化，资源共享	开发测试、小型应用
高级套餐	独享实例	性能保障，资源独占	生产环境、大型应用

✨ 核心优势

💰 成本优化：按需付费，无需预付费用
🔄 自动运维：无需关心数据库维护和升级
📊 监控告警：内置监控和告警机制
🔒 安全保障：多层安全防护，数据加密存储

🗃️ 云数据库（MySQL 型）

🏗️ 架构特点

单实例设计：每个云开发环境有且仅有一个 MySQL 型数据库实例
灵活共存：可与文档型数据库和自有数据库同时使用
MySQL 8.0：基于最新的 MySQL 8.0 版本构建

📚 核心概念

表（Table）

表是 MySQL 数据库的基本存储单元，用于组织和存储结构化数据。

结构化存储：由行和列组成的二维数据结构
唯一命名：每个表都有唯一的表名进行标识
类比关系：类似于文档型数据库中的"集合"概念

行（Rows）

表中的每一行代表一条完整的数据记录。

数据记录：每行包含一组相关的数据值
字段对应：每个数据值对应表中的一个列
类比关系：类似于文档型数据库中的"记录"概念

列（Columns）

列定义了表中数据的结构和类型。

数据类型：每列都有明确的数据类型（如 INT、VARCHAR、DATE 等）
结构约束：定义了该列可以存储的数据格式和范围
字段属性：支持主键、外键、索引等数据库特性

🛠️ 管理方式

管理工具	功能描述	适用场景
数据库管理工具（DMC）	可视化数据库管理界面	日常管理、数据查看
数据模型 API	通过模型进行数据操作	应用开发、业务逻辑
原生 SQL 查询	执行标准 SQL 语句	复杂查询、数据分析

🔒 安全说明：MySQL 型数据库不对外暴露直接访问的 IP 和端口，所有访问都通过 CloudBase 的安全网关进行。

⚙️ 技术实现与特性

🏗️ 底层架构

云数据库（MySQL 型）基于腾讯云 TDSQL-C MySQL 版构建，采用云原生架构设计：

🔧 云原生设计：融合传统数据库与云计算技术优势
⚡ 极致弹性：计算和存储资源独立扩缩
🚀 高性能：新硬件技术加速，性能卓越
🛡️ 安全可靠：企业级安全保障和数据保护

🔄 智能扩缩特性

特性	说明	优势
自动扩缩	根据请求压力自动调整计算资源	性能保障，成本优化
智能休眠	无请求时自动休眠节点	显著降低费用
快速唤醒	请求到达时快速启动服务	按需使用，灵活计费

⚙️ 休眠配置选项

配置模式	特点	适用场景
开启休眠	无请求时自动休眠，按需计费	开发测试、间歇性应用
关闭休眠	保持常驻，避免冷启动延迟	生产环境、实时性要求高

💡 配置建议：可在数据库设置中根据业务需求调整休眠策略，平衡性能和成本。

🔌 自有 MySQL 数据库

🎯 适用场景

自有 MySQL 数据库连接功能让您可以无缝接入现有的数据库系统，实现云端和本地数据的统一管理。

数据迁移：逐步将现有业务迁移到云开发
混合架构：同时使用云端和自建数据库
数据复用：充分利用现有的数据资产
灵活部署：支持多个数据库连接配置

⚙️ 连接配置

每个连接配置对应一个独立的 MySQL 数据库实例：

配置项	说明	示例值
主机地址	数据库服务器的域名或 IP	`db.example.com` 或 `192.168.1.100`
端口号	MySQL 服务端口	`3306`（默认）
数据库名	要连接的数据库名称	`my_business_db`
用户名	数据库访问用户名	`app_user`
密码	数据库访问密码	`secure_password`
连接超时	连接超时时间设置	`5` 秒（默认）

🔧 高级连接参数

支持丰富的连接参数优化，提升数据库性能：

参数类型	功能说明	配置示例
字符集	设置数据库字符编码	`utf8mb4`
语句缓存	启用预编译语句缓存	`true`
读写超时	设置读写操作超时时间	`30` 秒
自动提交	控制事务自动提交行为	`true`

🔗 关联关系限制

在配置数据模型关联关系时，需要注意以下限制：

✅ 同库关联：同一数据库内的表可以配置关联关系
❌ 跨库关联：不同数据库之间无法配置关联关系
❌ 跨类型关联：文档型、MySQL 型、自有数据库之间无法关联

💡 设计建议：在规划数据模型时，将有关联关系的表放在同一个数据库中。

🛡️ IP 白名单配置

为了保障自建 MySQL 数据库的安全性，需要配置 IP 白名单来限制访问来源。

📋 CloudBase 访问 IP 列表

请将以下 所有 IP 地址 添加到您的数据库白名单中：

# CloudBase 数据模型组件访问 IP
24.211.44
24.212.162
24.213.48
24.214.104
24.214.93
234.25.245
234.27.58
234.3.160
234.34.31
234.35.33

⚠️ 重要提醒

完整添加：必须将上述所有 IP 地址都添加到白名单
安全防护：白名单配置是防止非法访问的重要安全措施
网络要求：确保您的数据库可以通过公网访问

🔧 配置步骤

登录数据库管理后台
找到安全设置或白名单配置
添加上述所有 IP 地址
保存配置并重启服务（如需要）
测试连接：在 CloudBase 控制台测试数据库连接

🎯 数据库选型指南

面对三种数据库类型，如何选择最适合您业务的数据库？以下是详细的选型对比：

📊 全面对比分析

对比维度	📄 文档型数据库	🗃️ MySQL 型数据库	🔌 自有 MySQL 数据库
数据结构	灵活的 JSON 文档	严格的表结构	严格的表结构
底层查询	MongoDB 语法	标准 SQL	标准 SQL
扩展性	水平扩展优秀	垂直扩展为主	取决于自建架构
事务支持	支持	不支持	-
成本控制	按需付费	按需付费	自主控制

🎯 选型建议

📄 选择文档型数据库，如果您：

✅ 需要快速开发和迭代
✅ 数据结构经常变化
✅ 处理非结构化或半结构化数据
✅ 需要水平扩展能力
✅ 团队熟悉 NoSQL 技术

典型场景：内容管理、用户画像、日志分析、IoT 数据存储

🗃️ 选择 MySQL 型数据库，如果您：

✅ 需要复杂的关联查询
✅ 对数据一致性要求严格
✅ 团队熟悉 SQL 语法
✅ 需要完整的事务支持
✅ 数据结构相对稳定

典型场景：电商系统、财务系统、ERP 系统、传统业务系统

🔌 选择自有 MySQL 数据库，如果您：

✅ 已有成熟的数据库系统
✅ 需要渐进式迁移到云端
✅ 对数据库有特殊配置需求
✅ 需要与现有系统保持兼容
✅ 希望保持数据库的完全控制权

典型场景：企业数字化转型、混合云架构、数据迁移过渡期

💡 混合使用策略

在实际项目中，您也可以同时使用多种数据库类型：

文档型 + MySQL 型：新功能用文档型快速开发，核心业务用 MySQL 保障
云数据库 + 自有数据库：新业务上云，老业务保持现状
分层存储：热数据用云数据库，冷数据用自有数据库

🚀 开始建议：如果是全新项目，推荐从文档型数据库开始，享受快速开发的优势；如果是传统项目迁移，可以先使用自有数据库连接，再逐步迁移到云数据库。

云数据库概述

📋 数据库类型一览​

📄 云数据库（文档型）​

🏗️ 架构特点​

📚 核心概念​

集合（Collection）​

记录（Record / Document）​

🎯 文档型数据库优势​

🔑 系统字段说明​

_id 字段 - 唯一标识符​

_openid 字段 - 创建者标识​

🛡️ 权限控制价值​

🔌 访问方式​

👤 用户端调用​

🔧 服务端调用​

⚙️ 技术实现与特性​

🏗️ 底层架构​

📊 部署模式​

✨ 核心优势​

🗃️ 云数据库（MySQL 型）​

🏗️ 架构特点​

📚 核心概念​

表（Table）​

行（Rows）​

列（Columns）​

🛠️ 管理方式​

⚙️ 技术实现与特性​

🏗️ 底层架构​

🔄 智能扩缩特性​

⚙️ 休眠配置选项​

🔌 自有 MySQL 数据库​

🎯 适用场景​

⚙️ 连接配置​

🔧 高级连接参数​

🔗 关联关系限制​

🛡️ IP 白名单配置​

📋 CloudBase 访问 IP 列表​

⚠️ 重要提醒​

🔧 配置步骤​

🎯 数据库选型指南​

📊 全面对比分析​

🎯 选型建议​

📄 选择文档型数据库，如果您：​

🗃️ 选择 MySQL 型数据库，如果您：​

🔌 选择自有 MySQL 数据库，如果您：​

💡 混合使用策略​

📋 数据库类型一览

📄 云数据库（文档型）

🏗️ 架构特点

📚 核心概念

集合（Collection）

记录（Record / Document）

🎯 文档型数据库优势

🔑 系统字段说明

`_id` 字段 - 唯一标识符

`_openid` 字段 - 创建者标识

🛡️ 权限控制价值

🔌 访问方式

👤 用户端调用

🔧 服务端调用

⚙️ 技术实现与特性

🏗️ 底层架构

📊 部署模式

✨ 核心优势

🗃️ 云数据库（MySQL 型）

🏗️ 架构特点

📚 核心概念

表（Table）

行（Rows）

列（Columns）

🛠️ 管理方式

⚙️ 技术实现与特性

🏗️ 底层架构

🔄 智能扩缩特性

⚙️ 休眠配置选项

🔌 自有 MySQL 数据库

🎯 适用场景

⚙️ 连接配置

🔧 高级连接参数

🔗 关联关系限制

🛡️ IP 白名单配置

📋 CloudBase 访问 IP 列表

⚠️ 重要提醒

🔧 配置步骤

🎯 数据库选型指南

📊 全面对比分析

🎯 选型建议

📄 选择文档型数据库，如果您：

🗃️ 选择 MySQL 型数据库，如果您：

🔌 选择自有 MySQL 数据库，如果您：

💡 混合使用策略