Operations
DBReplay runs as a pipeline: capture, pre-process, dialect translation, replay, comparison, and report. Each stage reads what the previous stage recorded as fact — never a live system, and never a config file that might have changed since.
Pipeline stages
| Stage | Runs where | Job |
|---|---|---|
| Capture | Where the packets are — on or next to the source system | Passive recording of the real workload, plus a capture-side sanity check: drops, desync, session counts, volume, engine version. Running counters only, no second pass. |
| Pre-process | Replay-side | Classifies every captured statement against the target dialect and the source catalog extract; computes coverage and the fit-for-replay verdict. |
| Dialect translation | Replay-side | Converts statements that need it through a neutral intermediate form. Semantically minimal, never target-optimal — a rewrite that would help a real migration but changes results is out of scope here. |
| Replay | Next to the target | Reproduces captured order and concurrency, paced to the captured wall clock, connected as the same users as the source sessions. |
| Comparison | Post-pass, not inline | Hashes and compares every result set as a multiset against the source. Kept out of the timed path deliberately, so comparison work never perturbs the performance measurement. |
| Report | Generated from frozen, run-specific facts | A cross-tab of translated vs. matched, a statement-level timing comparison, and every precondition the report's numbers depend on, stated up front. |
Capture topologies
Capture goes where the packets are, not where the database is. A tap or SPAN host in front of the target, client-side capture, or — for sources where TLS 1.3 removes any other option — a platform-level clear-text trace facility. See TLS and Capture Topology for what each route requires and where each stops working.
| Vocabulary | Meaning |
|---|---|
| Discarded | Connections picked up mid-flight, clipped by capture start or end. Not an error — a window-length effect, and the most common reason a healthy-looking capture yields less replayable data than expected with pooled, long-lived connections. |
| Dropped | Connections the capture could not keep up with. An error, asserted as a precondition on every report. |
Capture-side sanity check
Runs continuously during capture, not only at the end — if drops start five minutes into a four-hour window, the capture is void and the rest of the window is wasted; better to find out immediately, while there's still time to fix it and re-book. It distinguishes three states: void, suspect, and ok to ship.
- Abort on anything that voids the data outright: drops, decoder desync, storage exhaustion.
- Warn, never abort, on anything affecting usefulness only — a high discard rate is common with pooled connections and is a window-length problem, not a fault.
- Truncate and mark, never silently discard. The sound prefix before a fault is still usable, and the diagnostics are needed either way.
Read-only pass, then transactional
Where the workload allows it, the read-only subset runs first: cheap, order-independent, and every failure isolated, so translation issues surface across broad coverage before the transactional run begins. Debugging inside a transactional run costs a full restore per fix, so flushing what can be found cheaply first pays for itself quickly.
Error handling during replay
Per-session abort with a full diagnostic bundle is the default, and it's overridable by statement error code where a customer wants failures to be surfaced rather than stopping the run. Either way, an aborted or a continuing-but-failed session counts as a replay fail for that session; the override changes behaviour, not the validity accounting. Aborted sessions are excluded from performance statistics rather than merely flagged, so a partial timing doesn't skew the numbers that matter.
Live status
A run's status is visible while it happens, overlaid on the capture's own curve and plotted against capture-relative time rather than wall clock, so the two are directly comparable. The single most useful chart is cumulative schedule lag — the target falling behind is both a performance finding and the mechanism that would otherwise silently corrupt a correctness result, so it's surfaced early and loudly rather than discovered at the end of a six-hour run.