Vendor migrations rank among the most stressful engineering projects: the old system is still serving production traffic, the new system isn't ready yet, and any mistake can cause downtime, data loss, or billing failures. Most teams approach migrations as a big-bang cutover, which is why so many end in late-night incidents.
The correct approach is incremental migration with verifiable rollback at each stage. This guide provides the framework.
The Migration Principle: Never Cut Over, Gradually Shift
The fundamental error in vendor migration planning is treating the migration as a single event. "We'll cut over to the new system on Saturday night" is how incidents happen.
The correct model: 1. Run old and new systems in parallel 2. Shift a small percentage of traffic to the new system 3. Verify correctness and performance at that percentage 4. Increase the percentage gradually (5% → 20% → 50% → 80% → 100%) 5. Maintain rollback capability at every stage 6. Decommission the old system only after 30+ days of stable 100% on new
This approach turns a high-risk event into a series of low-risk, verifiable steps.
Pattern 1: Database Migration
Migrating from one database system to another (MySQL → PostgreSQL, self-hosted → RDS, Oracle → Aurora) is among the most common and highest-risk migrations.
Phase 1: Schema compatibility Convert the schema to the target system. Test all application queries against the new schema. This is pure validation work — no traffic shifts yet.
Phase 2: Data synchronization Set up change data capture (CDC) or dual-write to keep both databases in sync: - AWS DMS (Database Migration Service): Managed CDC for continuous replication from source to target while both are live - Debezium: Open-source CDC for Kafka-based pipelines - Application-layer dual-write: Write to both databases in the application code, with the old as primary
This phase is complete when the new database is within seconds of the old database's state at all times.
Phase 3: Read traffic shift Route read traffic (SELECT queries) to the new database. Read replicas are stateless — any error can be corrected by routing reads back to the old database. Shift reads gradually (10% → 50% → 100%) while validating query performance.
Phase 4: Write traffic shift Shift writes to the new database while keeping CDC flowing to the old database (reversed direction now). This maintains rollback capability — if the new database has issues, revert writes to the old one.
Phase 5: Cutover and cleanup After 30+ days of stable operation on the new database, remove the old database and CDC synchronization.
Critical requirement throughout: Monitoring on both databases (query latency, error rate, replication lag) with automated alerts. The shift percentages above are meaningless without visibility into how each system is performing.
Pattern 2: Payment Processor Migration
Migrating between payment processors (Stripe → Braintree, legacy processor → Stripe) is particularly sensitive because live payment failures are immediately visible to customers and have direct revenue impact.
The stored card challenge: Migrated payment tokens are processor-specific. Stripe tokens can't be used with Braintree. Cards must be re-tokenized on the new processor.
Migration approaches:
Option A (Re-tokenize on next charge): Don't migrate stored cards. Let old payment tokens expire naturally. When a customer's next charge is attempted, if the old token fails (because the old processor is decommissioned), prompt re-entry of card details. This spreads the re-tokenization across your customer base over time. Works well for SaaS with regular billing cycles.
Option B (Processor network tokenization): Some processors support card network tokens (managed by Visa/Mastercard, not the processor) that are portable across processors. If both your old and new processor support network tokenization, migration of stored cards is possible without customer re-entry.
Option C (Parallel processing during transition): Run both processors simultaneously. New customers go to the new processor. Existing customers stay on the old processor for one billing cycle, then re-enroll on the new one at renewal.
The dual-write approach for webhooks: Configure both processors to send webhooks to your system during migration. Event deduplication logic prevents double-processing. This ensures no payment events are missed during the transition.
Pattern 3: Email / Communications Platform Migration
Migrating from one email service provider to another (SendGrid, Mailgun, Postmark, SES) is lower risk than database or payment migration but has subtleties.
DNS record management: Sending domains require SPF, DKIM, and DMARC DNS records. Adding new records for the new provider before removing old provider records is the correct sequence. Cutting records in the wrong order causes email deliverability failures.
IP warm-up: New sending IPs need to establish reputation with email providers. Ramping up volume on new IPs over 2-4 weeks (not immediately shifting all volume) prevents deliverability problems.
Template migration: Export all templates from the old platform, convert to the new platform's template syntax, and test each template for rendering correctness before routing traffic.
Webhook event handling: If your application processes email events (bounces, opens, clicks) via webhooks, update to the new provider's webhook format. Dual-webhook configuration during migration.
Pattern 4: Cloud Provider Migration
Cloud provider migrations (AWS → GCP, on-premises → AWS) are the most complex vendor migrations. The same gradual-shift principle applies, but at infrastructure scale.
The strangler fig approach: Migrate services one by one. Route specific services to the new cloud while keeping others on the old provider. The strangler fig applies at the service level — each individual service migration is a bounded project with its own rollback plan.
Data residency first: The hardest part of cloud migration is data. Move database workloads after application workloads — applications can run on the new cloud and point to the old cloud's databases during transition.
Global load balancer as traffic shifter: Use a global load balancer (Cloudflare, AWS Global Accelerator, GCP's global LB) to shift traffic percentages between providers. This gives you percentage-based traffic control throughout the migration.
Cost management during dual-run: Running on two cloud providers simultaneously doubles infrastructure costs for the duration. Plan this cost explicitly. The 3-6 months of dual-run cost should be included in the migration budget.
Rollback Planning: The Non-Negotiable
Every migration phase needs an explicit rollback plan defined before the phase begins:
- What metrics indicate rollback is required? (error rate threshold, latency threshold)
- Who has authority to trigger a rollback?
- How long does rollback take?
- How is data consistency maintained during rollback?
The rollback plan must be tested, not just written. Do a practice rollback on a staging environment before production migration begins.
Rutagon leads complex vendor migrations for engineering teams that need expertise in risk management and execution. Contact us to discuss your migration strategy.
Frequently Asked Questions
How long should a database migration take?
Timeline depends on data volume and complexity. A 100 GB database migration can be completed in 2-4 weeks of elapsed project time (1 week setup, 1-2 weeks parallel running and validation, 1 week cutover). A 10 TB database with complex relationships and custom functions takes 2-4 months. The limiting factor is usually the validation period (ensuring correctness) rather than the technical transfer time.
What's the most common migration mistake?
Underestimating the complexity of edge cases. Every migration reveals use cases that don't fit the standard migration pattern: obscure data types, custom functions, legacy integrations that weren't documented, or application behavior that depends on undocumented database behavior. Plan for a 30-50% buffer on timeline for edge case resolution.
Should we migrate or rebuild?
Migrations preserve existing functionality; rebuilds enable architectural improvements. Migrate if the existing system's logic is correct and the problem is purely the underlying technology. Rebuild if the business logic itself needs to change, or if the complexity of migration approaches the complexity of a rebuild. When in doubt, migrate first to get off the legacy system, then refactor the working system incrementally.
How do you handle migration during a period of active feature development?
Don't freeze feature development for migrations. Instead, establish a "migration tax" policy: all new features must be compatible with both old and new systems during the migration window. This adds some overhead to feature development but keeps the business moving. Clearly communicate the migration timeline to product teams so they can plan accordingly.
What does a vendor migration engagement with an external team typically include?
A vendor migration engagement typically includes: initial assessment and risk identification, migration architecture design, project plan with rollback checkpoints, hands-on implementation support for complex phases (data synchronization, dual-write implementation), go/no-go criteria definition, and post-migration validation. Most engagements run 4-12 weeks depending on complexity.