How RocketMQ Transactional Messages Ensure Distributed Data Consistency

Normal messages cannot guarantee atomicity between a producer's transaction and message sending, leading to data inconsistency. RocketMQ adds two‑phase commit transactional messages to ensure eventual consistency in distributed scenarios.

1. Basic Concepts

Half Message : The producer first stores a “half message” in the broker, invisible to consumers. The broker waits for the producer to confirm the transaction (commit or rollback). Transactional messages have three possible states:

TransactionStatus.CommitTransaction : Commit the transaction, allowing consumers to consume the message.

TransactionStatus.RollbackTransaction : Roll back the transaction, the message is deleted and cannot be used.

TransactionStatus.Unknown : Intermediate state; the broker must query the producer to determine the final status.

Transaction status check : If the producer does not confirm in time, the broker periodically checks the producer’s transaction status and decides whether to commit or roll back the half message.

API : RocketMQ provides two key interfaces— TransactionMQProducer and TransactionListener —used to send transactional messages and handle local transaction logic.

Storage and reliability : Transactional messages are stored in a dedicated queue on the broker, with transaction status logs ensuring high availability and consistency. Compared with ordinary messages, transactional messages add a half‑message phase and status‑check mechanism to guarantee eventual consistency in distributed environments.

2. Implementation of Transactional Messages

The following diagram shows the implementation principle of RocketMQ transactional messages:

First phase : Service A’s producer sends a half message to RocketMQ. The broker persists the message and returns an ACK, indicating successful sending. The message is stored but invisible to consumers.

Service A then executes its local business logic and determines, based on the local transaction result, whether to commit or roll back in the second phase.

Second phase :

(1) If Service A’s local transaction succeeds, the broker marks the half message as a complete, consumable message.

(2) If Service A’s local transaction fails, the broker deletes the half message, preventing delivery.

(3) To ensure consistency, RocketMQ periodically performs a status‑check on half messages whose final state is unknown. The broker queries the producer, which then reports the final transaction outcome, and the broker commits or rolls back accordingly.

Summary :

RocketMQ transactional messages guarantee consistency between local transactions and message delivery; only when the local transaction succeeds is the message delivered to consumers.

If the broker does not receive a second‑phase confirmation or receives an unknown state, it uses the status‑check mechanism to decide the final outcome.

Transactional messages have a timeout (default 4 hours); if the broker cannot obtain a final state within this period, the half message is rolled back.

They provide eventual consistency but not strict real‑time consistency, making them unsuitable for latency‑critical scenarios.

Long transaction execution times can affect overall throughput, and consumers must implement idempotent handling.