Migrate safely with a gradual rollout
How to move traffic to a new service, database or payment provider with checks at every step.

The pattern
A migration is a release that cannot be tested fully before it ships. The way to make it safe is to move a little traffic at a time and compare the old and new systems on real requests.
Step 1: shadow
Send every request to the old system as normal. Also send a copy to the new one and discard its response. Compare results, and log every mismatch. This costs nothing in user risk.
Step 2: canary
Serve real responses from the new system to staff, then to 1% of users. Hold at each step until guardrails have been steady for a full cycle of your traffic, usually a day.
const target = kerf.flag("billing-provider", user, "old");
const res = target === "new"
? await newProvider.charge(order)
: await oldProvider.charge(order);Step 3: ramp
- Go from 1% to 10%, 25%, 50% and 100%.
- Pause automatically on any guardrail breach.
- Keep the old system warm until you reach 100% and have held there for a week.
Step 4: finish
Remove the flag, delete the old path and close the ticket. Leaving both paths in place is how a migration becomes permanent.
Rollback
Test the rollback before you start. Flip the flag to old for a minute during the shadow phase and confirm that traffic returns cleanly.
More playbooks

Run your first checkout test
A step by step plan for testing a checkout change without risking revenue.

Test your pricing page
How to test plan layout, anchoring and copy on a pricing page without changing what anyone pays.

Improve onboarding activation
A playbook for finding your activation event and running a steady series of onboarding tests.