PolarDB for PostgreSQL offers high compatibility with document databases. This allows your applications to connect seamlessly using standard document database drivers, such as pymongo for Python, Mongoose for Node.js, and the official Go driver for MongoDB, without modifying your business code. This feature provides API compatibility and integrates the core enterprise-level capabilities of the PolarDB cloud-native database, including elastic scaling in seconds, massive data storage, and finance-grade high availability. It provides a cost-effective and high-performance NoSQL solution.
Feature overview
PolarDB for PostgreSQL achieves compatibility with document databases by coordinating the database proxy layer and compute nodes. Understanding how this feature works helps you use it more effectively.
Database proxy layer (Proxy)
The proxy layer is key to achieving protocol compatibility. It receives BSON requests from document database clients, performs identity authentication, parses protocols, and handles read/write splitting. The proxy layer then transforms the BSON requests into query or write statements that PostgreSQL can recognize and sends these PostgreSQL statements to the compute nodes based on read/write splitting and load balancing policies. This design completely decouples protocol transformation from the database kernel. This ensures the stability and integrity of the underlying PostgreSQL kernel and reuses the mature load balancing and read/write splitting capabilities of PolarDB.
Database compute node
Compute nodes use a high availability (HA) architecture with one primary node and multiple read-only nodes. Enterprise Edition supports up to 15 read-only nodes, and Standard Edition supports up to 7 read-only nodes. The primary node handles all write operations, while the read-only nodes handle read requests. The compute layer is based on the standard PostgreSQL kernel. It uses only the built-in DocumentDB plugin to execute all read and write requests for the document database. This minimal modification design ensures the feature's maintainability and allows for quick adoption of major version updates from the PostgreSQL community. This approach abstracts away the concept of table schemas in relational data and provides a collection management experience consistent with document databases.
Advantages
Compared to community edition document databases, the document database feature of PolarDB for PostgreSQL offers significant advantages in storage capacity, transaction processing, scale-out capabilities, and compute elasticity. This provides better support for enterprise-level application scenarios. The following table compares the core capabilities of the two.
Item | PolarDB document database compatibility | Community edition document database |
Maximum storage per collection | 32 TB | 16 TB |
Support duration for long-running/large transactions | No time limit. Supports long-running transactions that last for hours. | 1-minute limit |
Maximum size of a single row | 4 GB | 16 MB |
Storage expansion | Automatic scaling in seconds. Storage is pay-as-you-go. | Automatic scaling is limited and depends on the rules of the underlying disk. |
Maximum storage per instance | 500 TB | Limited by the specifications of the underlying disk. |
Scope
Before you use the document database compatibility feature, ensure that your cluster meets the following version requirements:
Kernel version: PostgreSQL 16, and the revision version must be 2.0.16.10.10.0 or later.
Database proxy version: 2.3.60.1 or later.
The document database compatibility feature is not supported on PolarDB for PostgreSQL (Distributed Edition) or serverless clusters.
Go to the PolarDB console and check the versions of your cluster on the page. If the versions do not meet the requirements, upgrade the minor version.
Billing
The document database compatibility feature itself does not incur extra fees. You only pay the related fees for the PolarDB for PostgreSQL cluster.
What to do next
Get started: After you review the feature overview, follow the instructions in Usage notes to create a cluster, configure an account, and verify the initial connection.
Compatibility and limitations: This feature is highly compatible with document database APIs, but some behavioral differences and limitations exist. For example, some deprecated parameters are not supported, and the error reporting behavior for failed transactions differs from that of native MongoDB. For more information, see Compatibility and limitations.
(Optional) Data migration: To migrate data from an existing MongoDB database, see the Data migration guide for detailed steps and tool usage.