Unified Read/Write Database→CQRS with Separate Read Projections
Duration Estimate
1–3 months
Migration Stages
6
Blocking Prerequisites
2
Confidence
StrongReadiness Checklist(2 blocking, 4 advisory)
Team at senior maturity level
This migration requires senior engineering maturity. The team should have hands-on experience with the relevant technologies and proven ability to execute complex system changes safely.
Guidance: Build team skills through learning modules before attempting this migration.
Production observability baseline established
Comprehensive metrics, logs, and traces must be in place before the migration starts. You need a clear baseline to detect regressions during and after each migration stage.
Guidance: Instrument key metrics (latency p99, error rate, throughput, resource utilization) on all affected components.
Rollback plan documented and tested
Rollback feasibility for this migration is 'complex'. Rollback is possible but may be complex, document the exact rollback steps and test them in a non-production environment.
Guidance: Run a full dry-run in a staging environment that mirrors production load characteristics.
'elasticsearch' provisioned and validated in target environment
'elasticsearch' must be available, configured, and load-tested in the target environment before the migration stage that introduces it.
Guidance: Deploy 'elasticsearch' with production-equivalent configuration. Run a smoke test under representative load.
'redis' provisioned and validated in target environment
'redis' must be available, configured, and load-tested in the target environment before the migration stage that introduces it.
Guidance: Deploy 'redis' with production-equivalent configuration. Run a smoke test under representative load.
Migration trigger condition confirmed
Confirm that the actual trigger for this migration is present. Common triggers: Complex aggregation queries compete with OLTP writes for database CPU and I/O; Read latency SLAs cannot be met by adding indexes without increasing write amplification; Multiple read patterns (search, dashboard, API) require fundamentally different query shapes.
Guidance: Validate the trigger with production metrics or benchmarks before committing to the migration timeline.
Migration Stages
Catalog all current read query patterns. Group by shape. Identify which patterns would benefit from a separate projection. Identify which patterns require strong read-after-write consistency and must stay on the write store.
Key tasks
- ·Catalog all current read query patterns. Group by shape. Identify which patterns would benefit from a separate projection. Identify which patterns require strong read-after-write consistency and must stay on the write store.
- ·Validate rollback capability at this stage boundary before proceeding.
Exit criteria
- ✓'Read Pattern Audit' validated in production with no regression in key metrics
Rollback: possible at this stage
Deploy read store infrastructure (Elasticsearch, Redis, read replica schema). Set up projection lag monitoring. Define projection rebuild procedures.
Key tasks
- ·Deploy read store infrastructure (Elasticsearch, Redis, read replica schema). Set up projection lag monitoring. Define projection rebuild procedures.
- ·Validate rollback capability at this stage boundary before proceeding.
Exit criteria
- ✓'Projection Store Setup' validated in production with no regression in key metrics
Rollback: possible at this stage
Build initial projection by reading from the write store and populating the read store. Validate data consistency. Measure projection population throughput.
Key tasks
- ·Build initial projection by reading from the write store and populating the read store. Validate data consistency. Measure projection population throughput.
- ·Validate rollback capability at this stage boundary before proceeding.
Exit criteria
- ✓'Projection Population: Initial Sync' validated in production with no regression in key metrics
Rollback: possible at this stage
Application reads from both write store and projection in parallel. Compare results. Identify consistency gaps and projection correctness issues before switching read traffic.
Key tasks
- ·Application reads from both write store and projection in parallel. Compare results. Identify consistency gaps and projection correctness issues before switching read traffic.
- ·Validate rollback capability at this stage boundary before proceeding.
Exit criteria
- ✓'Dual Read' validated in production with no regression in key metrics
Rollback: possible at this stage
Gradually migrate read traffic from write store to projection store. Route non-consistency-sensitive reads to projection first. Retain write store reads for immediate-post-write scenarios.
Key tasks
- ·Gradually migrate read traffic from write store to projection store. Route non-consistency-sensitive reads to projection first. Retain write store reads for immediate-post-write scenarios.
- ·Validate rollback capability at this stage boundary before proceeding.
Exit criteria
- ✓'Read Traffic Migration' validated in production with no regression in key metrics
Rollback: possible at this stage
Remove direct read queries from the write path. Write store now handles commands only. Implement projection update pipeline (CDC or domain events).
Key tasks
- ·Remove direct read queries from the write path. Write store now handles commands only. Implement projection update pipeline (CDC or domain events).
- ·No rollback available after this stage, confirm all exit criteria before proceeding.
Exit criteria
- ✓'Write Path Decoupling' validated in production with no regression in key metrics
Rollback: not available after this stage
Rollback Decision Points
After stage 5
Trigger: Any of the following in the 30 minutes after completing stage 5: p99 latency increases >50% from baseline, error rate exceeds 1%, or data consistency checks fail.
Procedure: Revert stage 5 changes. Rollback is complex, follow the documented rollback procedure for 'direct-db-to-cqrs'. Engage senior engineering support.
Recovery: 1–4 hours (complex rollback)
After stage 6
Trigger: Final validation: confirm all success criteria are met within 24 hours of migration completion. If any success criterion fails, trigger rollback or remediation.
Procedure: If success criteria are not met within 24 hours, escalate to the architecture team. Decide between full rollback, partial rollback, or targeted remediation based on scope.
Recovery: 24–72 hours for full assessment and remediation
Success Criteria
- ✓Target state 'CQRS with Separate Read Projections' is stable in production for 72+ hours with no regressions.
- ✓p99 latency on all affected services is within acceptable range (≤110% of pre-migration baseline).
- ✓Error rate is at or below pre-migration baseline.
- ✓New components (elasticsearch, redis) are fully operational and monitored.
This migration playbook is derived from structured architecture knowledge. Duration estimates and risk levels are structural approximations based on documented migration complexity and operational risk, not measured execution data. Validate all stages against your specific system constraints before executing.