数据迁移
如果需要把数据从文档型数据库迁移到 PostgreSQL 数据库的 Document 能力中,可以按如下方式操作。pgdoc 不会自动搬迁文档型数据库中的既有数据。
文档型数据库 --导出--> 中间数据文件(JSON / EJSON) --导入--> PostgreSQL 数据库(pgdoc_data schema)
导入入口由 pgdoc 插件提供,需要先在目标环境启用插件,再导入数据,按下文的顺序操作即可。迁移期间建议暂停写入,避免两边数据不一致;同时保留原文档型数据库的数据作为回滚依据,确认业务在 PostgreSQL 上运行正常后,再决定是否下线原有数据。
从文档型数据库导出数据
- 通过控制台对目标集合执行导出
- 或使用 SDK / HTTP API 遍历集合,把文档导出为 JSON 文件
- 导出格式沿用文档型数据库的 JSON 表达(EJSON),可保留
ObjectId、日期等类型信息
💡 提示:建议按集合逐个导出,便于导入阶段分批校验与定位问题。
启用 pgdoc
在导入数据之前,先在目标环境启用 pgdoc 插件。导入依赖这一步,原因有两点:
- 存放数据的
pgdoc_data及相关的pgdoc开头 schema 由插件创建并维护,见启用后新增的 schema - 导入入口位于插件的 Document 编辑器页面,未启用时无法发起导入
启用后,客户端仍使用文档型数据库的 HTTP API 与 SDK,调用方式不变,变化的是请求背后的承载服务。
⚠️ 注意:启用是环境级接管,该环境下所有走文档型数据库 HTTP API 的请求都会改由 PostgreSQL 承载。如果环境中已有需要保留的文档型数据库数据,请先导出备份,否则启用后这些数据将无法再通过 HTTP API 访问。
启用方法与开通失败的错误码见启用 pgdoc。
导入 PostgreSQL 数据库
启用插件后,在目标环境 PostgreSQL 的 Document 编辑器页面导入前面导出的 JSON 文件。插件提供的文档编辑器固定使用 pgdoc_data schema,数据直接落在其中,不需要另行指定 schema,详见数据的存放位置。
单个导入批次不超过 1000 条,超过时按批拆分,避免整批失败后回退重来。数据量较大时可按集合或时间分批导入。
导入完成后建议抽样校验。启用插件后客户端调用方式不变,用文档型数据库原有的方式查询即可,不需要写 SQL:
- Document 编辑器:直接浏览集合,核对文档数量与字段内容
- SDK:按文档型数据库的方式查询集合,见下方示例
- HTTP API:调用文档型数据库 HTTP API 查询集合,入口与请求方式不变,见文档型数据库 HTTP API
以小程序端为例,分批核对总数与明细:
const db = wx.cloud.database()
const { total } = await db.collection('todos').count()
const { data } = await db.collection('todos').limit(10).get()
💡 提示:除了核对总数,建议按
_id或创建时间抽查首条、末条等边界数据,更容易发现导入截断或字段丢失。
其他导入方式
数据量很大,或需要在导入时清洗、转换字段时,也可以不使用插件页面的导入入口,改为直接写入 PostgreSQL。这仍然需要先启用插件,pgdoc_data 等 schema 才会存在:
| 方式 | 适用场景 |
|---|---|
| DMC 导入 | 少量集合、开发测试、人工操作 |
| SQL / 脚本导入 | 结构与数据初始化,过程可控、可审计 |
| 业务脚本批量写入 | 需要在导入时清洗或转换字段结构 |
⚠️ 注意:文档型数据库中的文档结构与 PostgreSQL 的表结构并非一一对应。直接写入前需要先确定映射关系——哪些集合落成表、哪些字段落成列或
jsonb字段,并确保与插件维护的表结构兼容。这些 schema 与其中的对象不建议手工改动,原因见启用后新增的 schema。