pgdoc Document 插件

pgdoc 是腾讯云提供的 PostgreSQL 扩展，作为一个 Document 插件，运行在 CloudBase PostgreSQL 数据库上，用于提供文档型数据库的使用方案。

原本基于文档型数据库构建的应用，无需改动调用方式即可把数据落到 PostgreSQL 上运行。

本页说明工作方式与启用方法。启用后怎么读写数据、怎么配权限、怎么建索引，见使用 pgdoc。

工作方式

在云开发环境中，PostgreSQL 数据库启用 pgdoc 插件后，会接管云开发文档型数据库的 HTTP API 请求：

客户端调用方式不变——仍然使用文档型数据库的 HTTP API 与 SDK
请求的实际承载方由 PostgreSQL 数据库承担

文档型数据库 HTTP API 的请求域名与路径保持不变：

https://{envId}.api.tcloudbasegateway.com/v1/database/instances/{instance}/databases/{database}/

未启用 pgdoc：客户端 → 文档型数据库 HTTP API → 文档型数据库
启用 pgdoc：  客户端 → 文档型数据库 HTTP API → PostgreSQL 数据库（pgdoc）

数据的存放位置

启用 pgdoc 后，原本属于文档型数据库的 collection 与数据都存放在 PostgreSQL 的 pgdoc_data schema 下。数据不会被转换到 public schema，而是集中收纳在 pgdoc_data 中。控制台的 Document 编辑器固定使用这个 schema，集合的浏览、读写与导入都在其中进行，不需要指明 schema。

因此在 PostgreSQL 中直接查看、维护或导入这些数据时，需要显式指定 pgdoc_data schema：

-- 查看 pgdoc_data schema 下的表
select table_name
from information_schema.tables
where table_schema = 'pgdoc_data'
order by table_name;

-- 指定 schema 查询数据
select *
from pgdoc_data.<your_collection>
order by created_at desc
limit 10;

启用后新增的 schema

启用插件后，会在数据库中创建一组以 pgdoc 开头的 schema。它们由插件维护，共同支撑文档型数据库的读写：

schema	作用
`pgdoc`	公开 API 层——keeper 唯一调用的入口
`pgdoc_catalog`	元数据与 catalog，包括 `collection_indexes`、队列行等
`pgdoc_data`	文档数据实际落表的位置
`pgdoc_core`	`bson` 类型定义
`pgdoc_internal`	内部实现

⚠️ 禁止删除以 pgdoc 开头的 schema：pgdoc、pgdoc_catalog、pgdoc_data、pgdoc_core、pgdoc_internal 均由插件维护。不要执行 DROP SCHEMA、不要重命名 schema，也不要删除或修改其中的表、例程、类型。删除 pgdoc_data 会连带丢失全部集合数据，删除其他 schema 会导致文档型数据库 HTTP API 读写失败。需要清理这些对象时，请通过控制台停用或卸载插件，不要手工操作数据库对象。

💡 提示：各 schema 中的对象数量会随实际数据量变化，以数据库中的实际结果为准。

与文档型数据库并存时的行为

如果当前环境同时启用了文档型数据库，启用 pgdoc 后，数据库请求会由文档型数据库切换到 PostgreSQL 数据库；HTTP API 入口与请求内容不变，变化的是请求背后的承载服务。

⚠️ 注意：接管是环境级行为，会影响该环境下所有走文档型数据库 HTTP API 的请求。启用前请先确认影响范围。

启用

在云开发控制台的 Document 编辑器 中启用 pgdoc 插件即可。开通时如果不满足条件，会提供相关提示。

启用后请求立即由 PostgreSQL 接管，若迁移尚未完成，原文档型数据库中的数据将无法通过 HTTP API 访问。

已开通的环境不要重复开通，先确认开通状态再决定是否重试。

💡 提示：插件的可用范围与版本以控制台实际展示为准。通过 API 开通时，只有返回 Enabled 为 true 才表示后端确认开通成功。

开通失败的错误码

开通失败时按错误码判断。部分错误码的处理方式取决于实例类型（共享实例 / 独享实例），可在控制台的实例信息中查看。

扩展与内核状态

错误码	触发场景	处理手段
`FailedOperation.DocumentLibraryUnavailable`	`shared_preload_libraries` 未加载 `pgdoc`、`pgdoc_core`	共享实例：等待平台升级后重试，不要改参或重启独享实例：补预加载库并重启，见独享实例处理
`FailedOperation.DocumentExtensionFilesMissing`	内核缺少 `pgdoc` / `pgdoc_core` 扩展文件	共享实例：等待平台升级后重试独享实例：升级内核后重试
`FailedOperation.DocumentDependencyFilesMissing`	内核缺少 Document 插件依赖的扩展文件	共享实例：等待平台升级后重试独享实例：升级内核后重试
`FailedOperation.DocumentExtensionUnavailable`	Document 扩展不可用	共享实例：等待平台升级后重试独享实例：升级内核后重试，仍返回同码则停止重试

其他错误

错误码	触发场景	处理手段
`FailedOperation.DocumentFlexdbCoexistence`	环境中已存在文档型数据库	到云开发控制台开通，控制台会二次确认并清空原文档型数据库的数据
`OperationDenied.ResourceAlreadyExists`	资源已存在，多为重复开通	先复核是否已开通：已开通则停止，未开通则重试 1 次后上报
`AuthFailure.DataSourceOperationAuthFailure`	数据源鉴权失败	为开通操作配置数据库 / 数据源权限后重试；平台不会自动补授权
`FailedOperation.InstanceStatusConflict`	实例当前状态不允许该操作	查看实例状态：过渡态等待可操作后重试，阻塞态先恢复实例
`OperationDenied.InstanceStatusLimitOpError`	过渡态下发起改参或重启被拒绝	等待实例恢复到 `running` / `limited run` 后重试，不要重复提交
`FailedOperation.PGConnectError`	后端无法连接 PG 实例	确认实例状态与网络连通性，恢复后重试，不要高频重复调用
`FailedOperation.PGExecuteSqlError`	插件安装或授权 SQL 执行失败	查询 `pg_extension` 确认是否部分安装，重试 1 次仍失败则联系技术支持
`FailedOperation.PlatformError`	后台依赖服务异常	退避后重试，持续失败联系技术支持并提供 `RequestId`
`InternalError.SYS_ERR`	系统内部异常	退避后重试，持续失败联系技术支持并提供 `RequestId`
`InvalidParameter.INVALID_PARAM`	请求参数错误	校验环境 ID 后重试，不要用相同参数重复调用
`ResourceNotFound.InstanceNotFound`	未找到环境对应的 PG 实例	刷新环境信息后重试；实例创建或迁移中则稍后重试
`ResourceNotFound.RoleNotFound`	数据库角色不存在	重试 1 次，仍失败联系技术支持，不要自行创建角色
`OperationDenied`	操作被拒绝	检查账号权限与实例状态后重试
`OperationDenied.ResourceDepended`	资源被依赖	停止操作并联系技术支持
`InvalidAction`	当前环境未开放该接口	不要重试，确认接口是否已在目标环境发布
未收录的错误码	未知错误	最多重试 1 次，仍失败联系技术支持并提供错误码与 `RequestId`

改参、重启前必须确认实例状态为 running 或 limited run。重启中、任务执行中等过渡态只等待，隔离、回收、下线等阻塞态先处理实例状态。

独享实例处理

打开实例的参数设置，把 shared_preload_libraries 补上缺失的 pgdoc、pgdoc_core，保留原有的其他库，然后重启实例使配置生效，再重新开通。
参数的可选值中不含 pgdoc 或 pgdoc_core 时，说明当前内核不支持这个扩展，跳过改参，直接升级内核版本。
报 DocumentExtensionFilesMissing、DocumentDependencyFilesMissing、DocumentExtensionUnavailable 时，升级数据库内核版本后重新开通。
升级后仍返回同样的错误码，停止重试，携带错误码与 RequestId 联系技术支持。

以上操作也可通过 API 完成：改参用 ModifyDBInstanceParameters，重启用 RestartDBInstance，升级内核用 UpgradeDBInstanceKernelVersion。

⚠️ 注意：改参和重启会立即影响实例可用性，请在业务低峰期操作。

⚠️ 注意：插件安装失败时不要手工执行 DROP EXTENSION。插件对象由平台维护，手工改动可能导致文档型数据库 HTTP API 读写异常。

工作方式​

数据的存放位置​

启用后新增的 schema​

与文档型数据库并存时的行为​

启用​

开通失败的错误码​

独享实例处理​

相关文档​