Distributed acceleration
How relay works
Learn how relay agents ship, acknowledge and resend changes, and how they recover from a broken link or a failed agent.
A relayed pipeline has two halves. The capture half reads the source and writes the changes into a local spool. The relay ships that spool to the apply half, which stores it in its own spool and applies it to the target. This page explains what happens on the link between them.
The two halves
| Capture agent | Apply agent | |
|---|---|---|
| Runs | Near the source | Near the target |
| Reads | The source, through its log broker where the capture mode uses one | What the capture agent ships |
| Writes | Its local spool | Its own spool, then the target |
| Network role | Dials the apply agent | Listens on the relay port |
| Needs | The source connector and access to the source | The target connector, access to the target and its credentials |
The control plane pairs the two agents, chooses the endpoint and issues each agent its own relay identity. You choose only the apply agent and, if needed, the port and host. See Setting up relay agents.
Packets and compression
The capture agent ships changes from its spool in compressed packets. How hard it compresses follows how far behind the relay is, with nothing to set:
- Caught up. Changes ship as soon as they arrive, with fast compression, because latency is what counts.
- Behind. Packets fill up and are compressed harder, so catching up takes fewer bytes per change. The agent eases off when compression would slow the link down.
A group of changes that must commit together, such as a source transaction, is never split. A relay can ship a group of up to 64 MiB after compression; a larger one stops the relay.
The capture agent keeps many packets in flight without waiting for each acknowledgement, so the link's round-trip time is paid once for the whole window instead of once per packet. The apply agent acknowledges a packet only after it is safely on its own disk, and the capture agent keeps every packet in its spool until then, so a packet lost in transit is sent again.
Initial loads cross the same link, compressed in parallel by the load workers.
Resume after a broken link
Reconnecting is automatic. The capture agent dials the apply agent again, asks how much of the stream the apply agent has stored, and resends from there. The apply agent discards anything it already holds, so nothing is applied twice. A link that silently drops every packet is detected within about a minute.
While the link is down, the capture agent keeps capturing into its spool, so the spool grows by the source's change volume for as long as the outage lasts. A SQL Server DirectLog source also keeps its log from the position the target last committed, so the source log grows during the outage too. See Source log retention.
When an agent fails
Each half fails over like any pipeline. See Agents.
- The apply agent stops. The capture agent keeps capturing into its spool and dials until the apply agent, or its standby, answers. It then resends what the apply side doesn't hold. The capture half doesn't restart.
- The capture agent stops. When it, or its standby, starts the capture again, it reads the source again from the position the target committed. If the apply agent doesn't answer within 5 minutes, the start fails with an error.
- An old capture agent comes back. Once a standby has taken over the capture, the apply agent refuses the old capture agent with
relay_capture_epoch_superseded, so two capture agents never write into one apply spool.
One capture, several apply agents
A pipeline can relay different targets to different apply agents. The capture agent then ships its one spool to each apply agent separately, and each apply agent progresses at its own pace. Targets that the same apply agent applies share one relay pairing and one endpoint.
Security
- Transport. The relay runs only over TLS 1.3 with mutual authentication. A connection that negotiates anything else is refused before any data moves.
- Identities. Each agent generates its relay private key itself and sends only the public key to the control plane, which returns a certificate for the agent's role. The key never leaves the agent.
- Pinning. Each side accepts only the exact certificate of its paired peer, not a certificate authority. A firewall that decrypts TLS between the agents breaks the relay; see Proxies and TLS inspection.
- Renewal. Agents renew their relay certificates automatically, without breaking the link.
- Audit. The apply agent records every accepted, resumed, refused and closed relay connection in
relay-audit.jsonlunder<data-dir>/spool/relay/. The log holds identities and decisions, never keys or row data.
