pgdoc Document plugin

pgdoc is a Tencent Cloud PostgreSQL extension. As a Document plugin, it runs on the CloudBase PostgreSQL database and provides the document database usage model.

Applications originally built on the document database can run on PostgreSQL without changing how they call the database.

This page covers how it works and how to enable it. For reading and writing data, permissions, and indexes after enabling, see Using pgdoc.

How it works

In a CloudBase environment, once the pgdoc plugin is enabled on the PostgreSQL database, it takes over HTTP API requests for the CloudBase document database:

• The client calling convention does not change — you still use the document database HTTP API and SDK
• The actual serving backend becomes the PostgreSQL database

The request domain and path of the document database HTTP API stay the same:

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

pgdoc disabled: client → document database HTTP API → document database
pgdoc enabled:  client → document database HTTP API → PostgreSQL database (pgdoc)

Data storage location

After pgdoc is enabled, the collections and data that belonged to the document database are stored in the pgdoc_data schema of PostgreSQL. The data is not converted into the public schema; it is collected under pgdoc_data.

When you view, maintain, or import this data directly in PostgreSQL, specify the pgdoc_data schema explicitly:

-- List tables in the pgdoc_data schema
select table_name
from information_schema.tables
where table_schema = 'pgdoc_data'
order by table_name;

-- Query data with an explicit schema
select *
from pgdoc_data.<your_collection>
order by created_at desc
limit 10;

Schemas added after enabling

After you enable the plugin, the following schemas are created in the database. They are maintained by the plugin and together support document database reads and writes:

schema	Purpose
pgdoc	Public API layer — the only entry point that keeper calls
pgdoc_catalog	Metadata and catalog, including collection_indexes and queue rows
pgdoc_data	Where document data is actually stored in tables
pgdoc_core	bson type definitions
pgdoc_internal	Internal implementation

⚠️ Note: Do not delete or modify tables, routines, or types in these schemas. They are maintained by the plugin, and manual changes can break document database HTTP API reads and writes or corrupt data. The number of objects in each schema varies with the actual data volume; use the database as the source of truth.

Behavior when the document database is also enabled

If the environment also has the document database enabled, enabling pgdoc makes database requests switch from the document database to the PostgreSQL database. The HTTP API entry point and request bodies stay the same; what changes is the service behind them.

⚠️ Note: The takeover is an environment-level behavior. It affects every request that goes through the document database HTTP API in that environment. Confirm the impact scope before enabling it.

Enable

Enable the pgdoc plugin in the Document editor of the CloudBase console. If the conditions are not met when you activate it, the console shows a corresponding message.

Complete data migration first. Once enabled, requests are served by PostgreSQL immediately; if the migration is not finished, the data in the original document database is no longer reachable through the HTTP API.

Do not enable an environment that is already enabled. Confirm the current state before retrying.

💡 Tip: The availability and version of the plugin are subject to what the console actually shows. When you enable it through the API, only Enabled being true means the backend has confirmed success.

Error codes when enabling fails

Judge by the error code. How some codes are handled depends on the instance type (shared instance / dedicated instance), which the console shows in the instance details.

Extension and kernel state

Error code	Scenario	Handling
FailedOperation.DocumentLibraryUnavailable	shared_preload_libraries does not load pgdoc or pgdoc_core	Shared instance: wait for a platform upgrade and retry; do not change parameters or restart Dedicated instance: add the libraries and restart. See Dedicated instance handling
FailedOperation.DocumentExtensionFilesMissing	The kernel lacks the pgdoc / pgdoc_core extension files	Shared instance: wait for a platform upgrade and retry Dedicated instance: upgrade the kernel and retry
FailedOperation.DocumentDependencyFilesMissing	The kernel lacks the dependency extension files the Document plugin needs	Shared instance: wait for a platform upgrade and retry Dedicated instance: upgrade the kernel and retry
FailedOperation.DocumentExtensionUnavailable	The Document extension is unavailable	Shared instance: wait for a platform upgrade and retry Dedicated instance: upgrade the kernel and retry; stop retrying if the same code persists

Other errors

Error code	Scenario	Handling
FailedOperation.DocumentFlexdbCoexistence	The environment already has a document database	Enable from the CloudBase console; the console confirms again and clears the data in the original document database
OperationDenied.ResourceAlreadyExists	The resource already exists, usually a repeated enable	Check whether it is already enabled: stop if it is, otherwise retry once and then report
AuthFailure.DataSourceOperationAuthFailure	Data source authentication failed	Grant the required database / data source permissions, then retry; the platform does not grant them automatically
FailedOperation.InstanceStatusConflict	The instance state does not allow this operation	Check the instance state: wait for a transient state, resolve a blocking state first, then retry
OperationDenied.InstanceStatusLimitOpError	A parameter change or restart was rejected during a transient state	Wait until the instance returns to running / limited run, then retry; do not resubmit
FailedOperation.PGConnectError	The backend cannot connect to the PG instance	Confirm the instance state and network connectivity, then retry; do not retry at high frequency
FailedOperation.PGExecuteSqlError	The plugin install or grant SQL failed	Query pg_extension to see whether it is partially installed; retry once and contact technical support if it still fails
FailedOperation.PlatformError	A backend dependency failed	Retry with backoff; if it persists, contact technical support with the RequestId
InternalError.SYS_ERR	Internal system error	Retry with backoff; if it persists, contact technical support with the RequestId
InvalidParameter.INVALID_PARAM	Invalid request parameter	Validate the environment ID and retry; do not repeat the call with the same parameters
ResourceNotFound.InstanceNotFound	No PG instance is found for the environment	Refresh the environment information and retry; if the instance is being created or migrated, retry later
ResourceNotFound.RoleNotFound	The database role does not exist	Retry once; contact technical support if it still fails, and do not create the role yourself
OperationDenied	The operation was denied	Check the account permissions and instance state, then retry
OperationDenied.ResourceDepended	The resource is depended on	Stop the operation and contact technical support
InvalidAction	The API is not available in this environment	Do not retry; confirm whether the API has been released in the target environment
Error code not listed	Unknown error	Retry at most once; if it still fails, contact technical support with the error code and RequestId

Before changing parameters or restarting, confirm the instance state is running or limited run. In transient states such as restarting or a running task, only wait. In blocking states such as isolated, recycling, or offline, resolve the instance state first.

Dedicated instance handling

1. Open the instance parameter settings and add the missing pgdoc and pgdoc_core to shared_preload_libraries, keeping the other existing libraries. Restart the instance to apply the change, then enable again.
2. If the allowed values of the parameter do not include pgdoc or pgdoc_core, the current kernel does not support the extension. Skip the parameter change and upgrade the kernel version instead.
3. When you get DocumentExtensionFilesMissing, DocumentDependencyFilesMissing, or DocumentExtensionUnavailable, upgrade the database kernel version and enable again.
4. If the same error code persists after the upgrade, stop retrying and contact technical support with the error code and RequestId.

You can also do these steps through the API: ModifyDBInstanceParameters to change parameters, RestartDBInstance to restart, and UpgradeDBInstanceKernelVersion to upgrade the kernel.

⚠️ Note: Parameter changes and restarts affect instance availability immediately. Do this during off-peak hours.

⚠️ Note: Do not run DROP EXTENSION manually when the plugin installation fails. The plugin objects are maintained by the platform, and manual changes can break reads and writes through the document database HTTP API.

Related documentation

• Using pgdoc
• Data migration
• Extensions
• Supported extensions
• Import data
• DMC database management
• Document database HTTP API
• PostgreSQL data permissions
• PostgreSQL database HTTP API