Skip to main content

Data migration

If you need to migrate data from the document database into the Document capability of the PostgreSQL database, follow the steps below. pgdoc does not move the existing data in the document database automatically.

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

The import entry point is provided by the pgdoc plugin, so enable the plugin in the target environment before importing any data. Work through the steps below in order. Pause writes during the migration to avoid inconsistencies between the two sides, and keep the original document database data as the basis for rollback. Decide whether to retire the old data only after verifying that your workloads run correctly on PostgreSQL.

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.

Enable pgdoc​

Enable the pgdoc plugin in the target environment before importing data. The import depends on this step for two reasons:

  • The pgdoc_data schema that holds the data, along with the related schemas prefixed with pgdoc, is created and maintained by the plugin. See Schemas added after enabling
  • The import entry point sits in the plugin's Document editor page, so no import can be started until the plugin is enabled

Once enabled, clients still use the document database HTTP API and SDK — the calling convention does not change. What changes is the service behind the request.

⚠️ Note: Enabling takes over the whole environment — every request to the document database HTTP API in that environment is served by PostgreSQL. If the environment already holds document database data that must be kept, export a backup first; otherwise that data is no longer reachable through the HTTP API.

For the enable procedure and the error codes returned when enabling fails, see Enable pgdoc.

Import into PostgreSQL​

After the plugin is enabled, import the exported JSON files in the target environment's PostgreSQL Document editor page. The plugin's Document editor always uses the pgdoc_data schema, so the data lands there without you having to pick a schema. See Data storage location.

Keep each import batch to 1000 records or fewer. Split larger imports into batches so that a failed batch does not force you to start over. For large data sets, import by collection or by time range.

Verify with sampling after the import. Once the plugin is enabled the client calling convention does not change, so query the collections the same way as before — no SQL required:

  • Document editor: browse the collection and check the document count and field values
  • SDK: query the collection as you would on the document database, see the example below
  • HTTP API: call the document database HTTP API to query collections; the entry point and request format are unchanged. See Document database HTTP API

For example, in a Mini Program, check the total count and sample records in batches:

const db = wx.cloud.database()

const { total } = await db.collection('todos').count()
const { data } = await db.collection('todos').limit(10).get()

💡 Tip: Beyond the total count, sample boundary records by _id or creation time — the first and last records — to catch truncation or dropped fields more easily.

Other import methods​

If the data set is very large, or fields need cleaning or conversion during import, you can bypass the plugin page's import entry point and write to PostgreSQL directly. The plugin still has to be enabled first so that schemas such as pgdoc_data exist:

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. Before writing directly, decide the mapping — which collections become tables, and which fields become columns or jsonb fields — and make sure the result stays compatible with the tables the plugin maintains. Avoid modifying these schemas and the objects inside them by hand; the reasons are covered in Schemas added after enabling.