pg_doc Document 插件
pg_doc 是腾讯云提供的 PostgreSQL 扩展，作为一个 Document 插件，它用于在 PostgreSQL 数据库上提供文档型数据库的使用方案。
原本基于文档型数据库构建的应用，无需改动调用方式即可把数据落到 PostgreSQL 上运行。
什么是 pg_doc
| 项目 | 说明 |
|---|---|
| 名称 | pg_doc（Document 插件） |
| 提供方 | 腾讯云 |
| 运行位置 | CloudBase PostgreSQL 数据库 |
| 作用 | 在 PostgreSQL 数据库上提供文档型数据库的使用方案 |
| 内核要求 | PostgreSQL 内核版本不低于 v17.10_r1.26 |
工作方式
在云开发环境中，PostgreSQL 数据库启用 pg_doc 扩展后，会接管云开发文档型数据库的 HTTP API 请求。
这意味着：
- 客户端调用方式不变——仍然使用文档型数据库的 HTTP API 与 SDK
- 请求的实际承载方由 PostgreSQL 数据库承担
- 集合与数据实际存放在 PostgreSQL 的
pgdocschema 下
文档型数据库 HTTP API 的请求域名与路径保持不变：
https://{envId}.api.tcloudbasegateway.com/v1/database/instances/{instance}/databases/{database}/
未启用 pg_doc：客户端 → 文档型数据库 HTTP API → 文档型数据库
启用 pg_doc： 客户端 → 文档型数据库 HTTP API → PostgreSQL 数据库（pg_doc）
数据的存放位置
启用 pg_doc 后，原本属于文档型数据库的 collection 与数据都存放在 PostgreSQL 的 pgdoc schema 下。也就是说，数据并没有被转换到 public schema，而是集中收纳在 pgdoc 这一个 schema 内。
因此在 PostgreSQL 中直接查看、维护或导入这些数据时，需要显式指定 pgdoc schema：
-- 查看 pgdoc schema 下的表
select table_name
from information_schema.tables
where table_schema = 'pgdoc'
order by table_name;
-- 指定 schema 查询数据
select *
from pgdoc.<your_collection>
order by created_at desc
limit 10;
💡 提示：注意区分命名——数据存放的 schema 是
pgdoc（无下划线），扩展名是pg_doc（有下划线）。这与 启用说明 中内核依赖库pgdoc的命名一致。
与文档型数据库并存时的行为
如果当前环境同时启用了文档型数据库，启用 pg_doc 后，数据库请求会由文档型数据库切换到 PostgreSQL 数据库。
也就是说，HTTP API 入口与请求内容都不变，变化的是请求背后的承载服务——从文档型数据库切换为 PostgreSQL + pg_doc。
⚠️ 注意：接管是环境级行为，会影响该环境下所有走文档型数据库 HTTP API 的请求。启用前请先确认影响范围，并完成数据迁移。
数据迁移
无论是启用扩展还是切换数据库，都需要先把数据从文档型数据库迁移到 PostgreSQL 数据库。pg_doc 不会自动搬迁文档型数据库中的既有数据。
文档型数据库 --导出--> 中间数据文件（JSON / EJSON） --导入--> PostgreSQL 数据库
迁移期间建议暂停写入，避免两边数据不一致；同时保留原文档型数据库的数据，作为回滚依据。
💡 提示：启用说明 中的内核准备步骤（第 1、2 步）不改变数据库的现有行为，可以和数据迁移并行进行；但第 3 步启用扩展会立即触发接管，必须在数据迁移完成后执行。
从文档型数据库导出数据
- 通过控制台对目标集合执行导出
- 或使用 SDK / HTTP API 遍历集合，把文档导出为 JSON 文件
- 导出格式沿用文档型数据库的 JSON 表达（EJSON），可保留
ObjectId、日期等类型信息
💡 提示：建议按集合逐个导出，便于导入阶段分批校验与定位问题。
导入 PostgreSQL 数据库
把导出的数据导入 PostgreSQL 数据库，可按数据量与运维要求选择方式：
| 方式 | 适用场景 |
|---|---|
| DMC 导入 | 少量集合、开发测试、人工操作 |
| SQL / 脚本导入 | 结构与数据初始化，过程可控、可审计 |
| 业务脚本批量写入 | 需要在导入时清洗或转换字段结构 |
⚠️ 注意：文档型数据库中的文档结构与 PostgreSQL 的表结构并非一一对应。导入前需要先确定映射关系——哪些集合落成表、哪些字段落成列或
jsonb字段，再执行导入。
导入的目标 schema 应为 pgdoc，与 pg_doc 读取数据的位置保持一致，参见 数据的存放位置。
导入完成后建议抽样校验：
select count(*) from pgdoc.<your_collection>;
select * from pgdoc.<your_collection> order by created_at desc limit 10;
启用说明
启用 pg_doc 需要依次完成三步。前两步是实例级准备，不改变数据库的现有行为；第三步会让接管正式生效，因此必须在数据迁移完成后执行。
| 步骤 | 操作 | 是否改变现有行为 |
|---|---|---|
| 1 | 检查 PG 内核版本不低于 v17.10_r1.26 | 否 |
| 2 | 在内核参数 shared_preload_libraries 中选择启用 pgdoc、pgdoc_core | 否 |
| 3 | 启用 pg_doc 扩展 | 是，文档型数据库的 HTTP API 请求开始由 PostgreSQL 接管 |
1. 检查内核版本
pg_doc 要求 PostgreSQL 数据库的内核版本不低于 v17.10_r1.26。低于该版本时无法启用。
💡 提示：内核版本可在数据库实例信息中查看。若当前版本低于
v17.10_r1.26，需先升级内核版本再继续。
2. 启用内核依赖库
在 PostgreSQL 内核参数 shared_preload_libraries 中选择启用以下两个依赖库：
pgdocpgdoc_core
两者需要同时启用，缺少任意一个都会导致 pg_doc 扩展无法正常工作。
⚠️ 注意：
shared_preload_libraries属于实例级参数，修改后通常需要重启实例才能生效，请以控制台的提示为准，并尽量安排在业务低峰期操作。
💡 提示：注意区分命名——内核依赖库是
pgdoc、pgdoc_core（无下划线），扩展名是pg_doc（有下划线），两者不能混写。
3. 启用 pg_doc 扩展
完成上述两步、在 PostgreSQL 数据库中启用 Document 扩展，可以通过控制台启动。
启用成功后，云开发文档型数据库的 HTTP API 请求即由 PostgreSQL 数据库接管：
客户端 → 文档型数据库 HTTP API → PostgreSQL 数据库（pg_doc）
⚠️ 注意：这一步是接管生效的分界点。若尚未完成数据迁移就启用，切换后原文档型数据库中的数据将无法通过 HTTP API 访问。
💡 提示：扩展的具体启用方式、可用范围与版本以控制台实际展示为准。
注意事项
- 核对内核版本与依赖库：PG 内核版本需不低于
v17.10_r1.26，并在shared_preload_libraries中同时启用pgdoc、pgdoc_core - 留意数据的存放位置：启用后 collection 与数据存放在 PostgreSQL 的
pgdocschema 下，在 PostgreSQL 中直接运维时需显式指定该 schema - 先导出，后启用：
pg_doc不会自动迁移文档型数据库中的既有 数据，未完成迁移就启用会导致数据不可见 - 接管是环境级的：影响该环境下所有走文档型数据库 HTTP API 的请求，请提前评估影响面
- 保留回滚能力：迁移和切换期间请勿删除原文档型数据库的数据；确认业务在 PostgreSQL 上运行正常后，再决定是否下线原有数据
- 重新验证权限模型：文档型数据库的安全规则与 PostgreSQL 的 GRANT + RLS 策略不是同一套机制，切换到 PostgreSQL 后需要重新配置并验证数据权限，参见 PostgreSQL 数据权限
- 重新验证索引与查询：文档型数据库的索引类型与 PostgreSQL 不一致，切换后需按实际查询重新建索引，参见 索引管理