All Products
Search

This Product

    PolarDB:Service types

    Document Center

    PolarDB:Service types

    Last Updated:Mar 30, 2026

    PolarDB-X exposes binary logs (binlogs) through two independent modes: single-stream mode (Global Binlog) and multi-stream mode (Binlog-X). Both modes are fully compatible with the MySQL binlog format and binlog dump protocol, so downstream consumers can subscribe using standard MySQL replication tooling. Both modes can run on the same instance simultaneously.

    The choice between them is a trade-off between consistency guarantees and throughput scalability: single-stream mode provides full transaction ordering at the cost of a single-stream throughput ceiling; multi-stream mode removes that ceiling by distributing events across parallel streams at the cost of cross-stream transaction integrity.

    Choose a mode

    Single-stream (Global Binlog) Multi-stream (Binlog-X)
    What it provides One global log stream merging binlogs from all data nodes (DNs) in transaction order Multiple parallel log streams with binlogs distributed across streams by a hash algorithm
    Transaction consistency Full transaction integrity and ordering guaranteed Transaction integrity is preserved within a stream; streams are independent
    Throughput scalability Bounded by single-stream throughput; becomes a bottleneck at large scale Greatly improved extensibility; resolves the single-point bottleneck of large-scale clusters
    Enabled by default Yes No — enable separately in the console
    Typical use case Downstream MySQL replication where consistent ordering matters (for example, financial transfers where the downstream must always read a consistent balance) High-throughput change data capture (CDC) pipelines at scale

    Single-stream mode

    Single-stream mode merges the raw binlogs of all DNs into one ordered global queue and strips internal distributed-transaction metadata. The result is a single log stream that a downstream MySQL subscriber consumes exactly as if it were a standalone MySQL instance.

    Single-stream mode is enabled by default when you purchase a PolarDB-X instance.

    How it works

    The CDC component runs as a master-slave pair. Both nodes replicate binlog files from each other to stay in sync. Downstream consumers track position by file name and position; these values do not change when a switchover occurs between the master and slave CDC nodes, so consumption continues without interruption.

    Distributed transactions are merged into the global stream only when the transaction policy is set to Timestamp Oracle (TSO). PolarDB-X uses TSO by default. If TSO is not in use, the stream provides eventual consistency rather than full transaction ordering.

    Modifying partition key values

    If you need to change the partition key value of a row, do so inside a TSO transaction. This ensures the DELETE event is recorded before the INSERT event in the binlog, preserving consistency for downstream consumers. Run one of the following:

    • An UPDATE statement that modifies the partition key value

    • A REPLACE statement that modifies the partition key value

    • An explicit transaction that runs DELETE, updates the partition key value, then runs INSERT

    Multi-stream mode

    Multi-stream mode distributes binlogs from all DNs across multiple independent log streams using a hash algorithm. Each stream is a complete, standalone binlog — you can run CHANGE MASTER and SHOW BINLOG EVENTS against any stream individually.

    Multi-stream mode resolves the single-point throughput bottleneck of large-scale clusters. The trade-off is that transaction integrity applies within a stream but not across streams.

    Multi-stream mode is disabled by default. Enable it in the console, then create one or more multi-stream groups. Each multi-stream group contains multiple log streams. Each group is isolated from others. Within a group, you configure the number of log streams and the splitting level.

    Before you create a multi-stream group

    The following decisions are irreversible after the group is created. Plan them before you proceed:

    • Number of log streams: We recommend that you configure the number of log streams to be greater than or equal to the number of DNs. You cannot adjust this number after creation. If you later need a different count, create a new multi-stream group and update downstream consumers accordingly.

    • Splitting level (service layer): The default splitting level for all databases and tables in the group cannot be changed after it is configured. Changing a splitting level causes the same binlog event to appear in different streams, leading to data inconsistency.

    • Splitting level (per database or table): If you want to separately configure a splitting level for a new table, configure the splitting level before data is written to the table. Per-table splitting levels cannot be set retroactively.

    To adjust the number of streams or splitting levels after creation, create a new multi-stream group to replace the original and update downstream consumers accordingly.

    Splitting levels

    A splitting level controls how binlog events are assigned to streams. Three levels are available.

    Database level (in sequence)

    Events are hashed by database name. All events for a given database go to the same stream in order.

    Throughput and consistency trade-off: Single-database throughput is bounded by one stream. Transactions that touch only one database retain full integrity. Cross-database transactions are split across streams and lose integrity guarantees.

    Suitable for instances with a large number of databases.

    DDL type Distribution
    CREATE DATABASE, DROP DATABASE Broadcast to all streams (because per-table splitting can route tables from the same database to different streams)
    All other DDL Unicast to a fixed stream

    Table level (in sequence)

    Events are hashed by table name. All events for a given table go to the same stream in order.

    Throughput and consistency trade-off: DML and DDL operations for a single table are always in sequence within one stream. Cross-table transactions may be split. If a large table concentrates all its events on one stream, configure a separate per-table splitting level for that table to avoid data skew.

    Additional behavior: Renaming a table is allowed. Events continue to be routed based on the original table name.

    Suitable for instances with a large number of tables where per-table ordering matters.

    DDL type Distribution
    CREATE DATABASE, DROP DATABASE Broadcast to all streams
    All other DDL Unicast to a fixed stream

    Row level (in sequence)

    Events are hashed by primary key value. All events for a given row go to the same stream in order.

    Throughput and consistency trade-off: Events are distributed across all streams — this is the highest-throughput option. Ordering is guaranteed only per row, not per table or database. Two caveats:

    • Tables without a primary key are not supported. Their binlogs are discarded.

    • UNIQUE constraint risk: If a table has a UNIQUE constraint and a unique key swap occurs (for example, reassigning a unique value from one row to another), the order of DELETE and INSERT at the destination is not guaranteed. If INSERT arrives before DELETE, a write conflict occurs. Use table-level splitting for tables where this pattern is possible.

    Suitable for workloads that need maximum parallelism and have no ordering requirement at the database or table level.

    DDL type Distribution
    All DDL Broadcast to all streams

    Configuration layers

    Splitting levels can be set at two layers:

    • Service layer: The default splitting level for all databases and tables in the group that have no per-object override.

    • Database and table layer: Overrides the service-layer default for a specific database or table.

    Plan both layers before creating the group. Modifying a layer after it is configured causes the same events to appear in multiple streams.

    Transparent consumption of binlogs

    The CDC component saves binlog files to local disk first and uploads them to remote storage — such as Object Storage Service (OSS) — in real time. Files typically remain on local disk for a short period and on remote storage for longer periods (for example, 15 days).

    The transparent consumption feature abstracts this storage difference. Downstream systems can read binlog files from remote storage without any changes to their consumption logic.

    Transparent consumption requires CDC V2.0.0 or later.