FAQ

What business scenarios is this capability suitable for?

This capability is suitable for online businesses that require a flexible schema and use the document model for development, such as content management, user profiling, IoT, and game save data. It is also built on PolarDB for MySQL, so the same data can be read and written flexibly as documents, and also queried and analyzed by using standard SQL. It is suitable for unified data platform scenarios where you want to use one copy of data for both business operations and analytics.

How is this capability billed?

The document database (compatible with the MongoDB protocol) capability itself is free of charge. You only pay for the underlying PolarDB for MySQL cluster resources, including compute node specifications, storage, and backups. If you enable the Serverless elasticity feature on a fixed-specification cluster, billing is based on PCUs (PolarDB Capacity Units).

How do I get started?

1. Confirm whether your cluster meets the scope of application:

   • Kernel version: MySQL 8.0.2, and the minor kernel version must be 8.0.2.2.36 or later.

   • PolarProxy version: 2.9.22 or later.

   • Other limits: Serverless clusters do not currently support the document database compatibility feature.

2. After the conditions are met, log on to the PolarDB console and go to the Basic Information page of the target cluster.

3. Find the Document Database Compatibility configuration item and click Enable. The system automatically creates a default Endpoint for Document Database.

4. Create a privileged account for the document database, and then connect by using a MongoDB driver or mongosh. For more information, see Use document database (MongoDB-compatible).

Does this capability provide high availability?

Yes. Compute nodes use a one-primary, multiple-read-only high-availability architecture. Enterprise Edition supports up to 15 read-only nodes, and Standard Edition supports up to 7 read-only nodes. The primary node handles write requests, and read-only nodes share read requests. The architecture supports automatic failover, and availability is guaranteed by the underlying PolarDB for MySQL cluster.

Which cluster types do not support this capability?

The following cluster types do not support the document database (compatible with the MongoDB protocol) capability:

• Serverless clusters.

  Note

  You can enable the Serverless elasticity feature on a fixed-specification cluster. However, if you purchase a Serverless cluster, the document database (compatible with the MongoDB protocol) capability is not supported.

How do clients connect to the document database (compatible with the MongoDB protocol) endpoint?

Use a standard MongoDB driver or mongosh to connect to the document database (compatible with the MongoDB protocol) endpoint. The connection string format is:

mongodb://<username>:<password>@<polardb_endpoint>:<port>

• <username>: the document database account name, such as doc_root or a standard account created by using createUser.

• <password>: the password for the account. If the password contains special characters, perform URL encoding.

• <polardb_endpoint>: the domain name of the document database compatibility endpoint.

• <port>: the port number of the document database compatibility endpoint.

Which drivers and clients are supported?

Common drivers and tools that support the standard MongoDB Wire Protocol are supported, including mongosh, Python (pymongo), Node.js (mongoose), and the official Go MongoDB driver. For more information, see Drivers and ecosystem tools.

How does the connection layer implement read/write splitting and load balancing?

Protocol conversion is performed at the database proxy layer and is decoupled from the kernel. This allows the capability to reuse the connection pooling, load balancing, and read/write splitting capabilities of PolarDB. Write requests are routed to the primary node, and read requests are distributed to read-only nodes. This provides horizontal read scalability while maintaining protocol compatibility.

Which MongoDB protocols and features are supported?

PolarDB for MySQL is compatible with the MongoDB Wire Protocol through the database proxy layer. It supports common query, update, and projection operators, aggregation pipelines, and common database commands. For a detailed list of supported operators and commands, see Compatibility and limits.

Can I migrate data from MongoDB to PolarDB?

Yes. We recommend that you use Alibaba Cloud Data Transmission Service (DTS) for migration. DTS supports schema migration, full data migration, and incremental data migration. For more information, see Migrate data from MongoDB to document database (MongoDB-compatible).

What behavioral differences should I be aware of after migration?

Some administrative commands, server-side extensions, and edge-case semantics may differ from native MongoDB. We recommend that you verify functionality in a test environment with real workloads before switching over, and refer to Compatibility and limits to confirm that the operators and commands you use are supported.

How do I scale performance?

• Vertical scaling: Upgrade the compute node specification.

• Horizontal read scaling: Add read-only nodes. Enterprise Edition supports up to 15 read-only nodes. The proxy layer uses read/write splitting to distribute read requests across nodes.

• Storage scaling: Based on the cloud-native distributed storage architecture, storage capacity can scale to the PB level.

• Elastic scaling: Enable the Serverless elasticity feature on a fixed-specification cluster for second-level elastic scaling based on PCUs.

Sharding is not supported. You can add read-only nodes to improve read request performance, or scale up compute nodes to improve write request performance.

How do I monitor and troubleshoot performance issues?

Use the monitoring metrics, slow query logs, and SQL Explorer tools in the PolarDB console to identify slow requests. Because document operations are ultimately converted to SQL statements for execution, you can use the existing performance diagnostics capabilities of PolarDB for MySQL, such as execution plans and SQL statistics, for analysis.