Skip to main content

pg_doc Document plugin

pg_doc is a Tencent Cloud PostgreSQL extension. As a Document plugin, it provides the document database usage model on PostgreSQL.

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

What is pg_doc​

ItemDescription
Namepg_doc (Document plugin)
Provided byTencent Cloud
Runs onCloudBase PostgreSQL database
PurposeProvide the document database usage model on PostgreSQL
Kernel requirementPostgreSQL kernel version v17.10_r1.26 or later

How it works​

In a CloudBase environment, once the pg_doc extension is enabled on the PostgreSQL database, it takes over HTTP API requests for the CloudBase document database.

This means:

  • 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
  • Collections and data are physically stored in the pgdoc schema of PostgreSQL

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}/
pg_doc disabled: client → document database HTTP API → document database
pg_doc enabled:  client → document database HTTP API → PostgreSQL database (pg_doc)

Data storage location​

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

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

-- List tables in the pgdoc schema
select table_name
from information_schema.tables
where table_schema = 'pgdoc'
order by table_name;
-- Query data with an explicit schema
select *
from pgdoc.<your_collection>
order by created_at desc
limit 10;

💡 Tip: Mind the spelling — the schema that holds the data is pgdoc (no underscore), while the extension is pg_doc (with an underscore). This matches the naming of the pgdoc preload library in Enabling pg_doc.

Behavior when the document database is also enabled​

If the environment also has the document database enabled, enabling pg_doc makes database requests switch from the document database to the PostgreSQL database.

In other words, the HTTP API entry point and the request bodies stay the same. What changes is the service behind them — from the document database to PostgreSQL with pg_doc.

⚠️ 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 and finish the data migration before enabling it.

Data migration​

Whether you are enabling the extension or switching databases, you must first migrate data from the document database to the PostgreSQL database. pg_doc does not automatically move the existing data in the document database.

document database  --export-->  intermediate files (JSON / EJSON)  --import-->  PostgreSQL database

Pause writes during the migration to avoid inconsistencies between the two sides, and keep the original document database data as the basis for rollback.

💡 Tip: The kernel preparation steps (steps 1 and 2) in Enabling pg_doc do not change the current database behavior and can run in parallel with the data migration. Step 3, enabling the extension, triggers the takeover immediately, so it must come after the migration completes.

Export data from the document database​

  • Export target collections from the console
  • Or iterate collections with the SDK / HTTP API and export documents as JSON files
  • The export keeps the document database JSON representation (EJSON), preserving type information such as ObjectId and dates

💡 Tip: Export collection by collection so that you can verify and troubleshoot in batches during the import stage.

Import into PostgreSQL​

Import the exported data into the PostgreSQL database. Choose a method based on data volume and operational requirements:

MethodUse case
DMC importA small number of collections, development and testing, manual operations
SQL / script importSchema and data initialization, with a controllable and auditable process
Batch writes from a business scriptData that needs cleaning or field conversion during import

For details, see Import data and DMC database management.

⚠️ Note: Documents in the document database and tables in PostgreSQL are not one-to-one. Decide the mapping first — which collections become tables, and which fields become columns or jsonb fields — and then run the import.

The target schema for the import should be pgdoc, matching where pg_doc reads data. See Data storage location.

Verify with sampling after the import:

select count(*) from pgdoc.<your_collection>;
select * from pgdoc.<your_collection> order by created_at desc limit 10;

Enabling pg_doc​

Enabling pg_doc takes three steps. The first two are instance-level preparation and do not change the current database behavior. The third makes the takeover take effect, so it must come after the data migration completes.

StepActionChanges current behavior
1Check that the PostgreSQL kernel version is v17.10_r1.26 or laterNo
2Select pgdoc and pgdoc_core in the shared_preload_libraries kernel parameterNo
3Enable the pg_doc extensionYes — HTTP API requests for the document database start being served by PostgreSQL

1. Check the kernel version​

pg_doc requires the PostgreSQL database kernel to be v17.10_r1.26 or later. Enabling it is not possible on an older version.

💡 Tip: You can find the kernel version in the database instance information. If the current version is older than v17.10_r1.26, upgrade the kernel before continuing.

2. Enable the kernel preload libraries​

In the PostgreSQL kernel parameter shared_preload_libraries, select the following two preload libraries:

  • pgdoc
  • pgdoc_core

Both are required. Missing either one prevents the pg_doc extension from working.

⚠️ Note: shared_preload_libraries is an instance-level parameter. Changing it usually requires an instance restart to take effect. Follow the prompt in the console, and schedule the operation during off-peak hours.

💡 Tip: Mind the spelling — the kernel preload libraries are pgdoc and pgdoc_core (no underscore), while the extension is pg_doc (with an underscore). They are not interchangeable.

3. Enable the pg_doc extension​

After the two steps above, enable the Document extension on the PostgreSQL database. You can start it from the console.

Once enabled, HTTP API requests for the CloudBase document database are served by the PostgreSQL database:

client → document database HTTP API → PostgreSQL database (pg_doc)

⚠️ Note: This step is the point of no return for the takeover. If you enable it before the data migration is done, the data in the original document database will no longer be reachable through the HTTP API.

💡 Tip: The exact way to enable the extension, its availability, and its version are subject to what the console actually shows.

Notes​

  • Check the kernel version and preload libraries: the PostgreSQL kernel must be v17.10_r1.26 or later, with both pgdoc and pgdoc_core enabled in shared_preload_libraries
  • Know where the data lives: once enabled, collections and data are stored in the pgdoc schema of PostgreSQL. Specify that schema explicitly when operating on the data directly in PostgreSQL
  • Export before you enable: pg_doc does not migrate existing data from the document database. Enabling it before the migration completes leaves that data inaccessible
  • The takeover is environment-level: it affects every request that goes through the document database HTTP API in the environment, so assess the impact first
  • Keep a rollback path: do not delete the original document database data during the migration and switch. Only decide whether to retire the old data after verifying that your workloads run correctly on PostgreSQL
  • Revalidate the permission model: document database security rules and PostgreSQL GRANT + RLS policies are different mechanisms. After switching to PostgreSQL, reconfigure and verify data permissions. See PostgreSQL data permissions
  • Revalidate indexes and queries: document database index types differ from PostgreSQL. After switching, rebuild indexes based on your actual queries. See Index management