Data Warehouse Migration Plan Template
Three documents and four sheets that compare every migrated model's output against its old version, because a changed number is the failure mode, not a crash.
Free download · No account needed
Every page-one result for a data warehouse migration plan is organized by calendar phase: discovery, design, execution, testing, cutover, each with a generic checklist item like row count parity or schema validation. N-iX, one of the more validation-literate results, reports that validation alone has consumed 25 to 60 percent of total project effort on its own engagements. None of the five page-one results compares a specific model's output against its own history, ties a divergence to the consumer who would notice it, or separates a bug from an intentional change.
The standard tool for this comparison already exists. dbt Labs' own audit_helper package states its purpose plainly: quality assurance, asserting that a refactored model reaches the same output as the original. It runs one model at a time, by hand, in a development session, comparing two queries. Nothing in it ties a result to a consumer, decides whether a divergence is a bug or an intentional change, or gates a cutover date on the answer, which is what this pack adds across every model in the migration.
Cordwood Outfitters, an illustrative e-commerce retailer, ran this comparison across all 42 models in its move from Redshift to dbt-on-Snowflake: 35 passed clean, 7 diverged beyond tolerance, 5 bugs and 2 intentional redefinitions. The costliest bug sat in Weekly Revenue by Channel, which feeds the board deck directly: a rewritten join silently dropped 1,710 unattributed orders, understating trailing 90-day revenue by 99,180 dollars, 2.34 percent, caught and fixed before cutover. The pipeline documentation pack covers what a running pipeline should already test; this one covers what changes underneath it during a migration.
What's in the pack
Migration Plan
Sequences every model by dependency order, raw and staging first, then intermediate, then mart and reporting last, tagged as a platform move, a rebuild, or an intentional refactor.
Validation Approach
Why a clean run is not evidence, the comparison method and tolerance actually used, and the worked example showing exactly how one bug reached a board deck.
Consumer Comms
The notices sent for the two intentional changes, stating the old and new definition, the effect on historical reporting, and who needs to know before they notice on their own.
Model Mapping
One row per model, old location beside new, the change type, and its parity status, the inventory everything else in the pack is built from.
Output Parity Checks
Old output compared against new over a real historical window for every model in scope, with the variance, the threshold, and the root cause of every flagged row.
Consumer Impact Register
Every model connected to what actually reads it, ranked by how directly and expensively a wrong number would be noticed, so urgency is not guessed.
Cutover Checklist
Gates go-live per model on a clean parity check or a documented, communicated change, never on a deadline alone.
How to use it
- 1
Send what's in scope
The models actually moving, however you have them, a dbt project, a table list, or just names, plus anything you know about who reads each one.
- 2
Get the Migration Plan
River sequences every model by dependency order and tags each as a platform move, a rebuild, or an intentional refactor in the Model Mapping.
- 3
Run the comparison
Once old and new versions are both reachable, River checks each model's output against its history and flags anything past tolerance in Output Parity Checks.
- 4
Sort and communicate
Every flagged model gets fixed as a bug or documented as an intentional change, with Consumer Comms drafted for whoever reads that number.
Frequently asked questions
Is this template free?
Yes, no account or card needed to download it. Edit with AI is the optional half, where River reads your models and runs the comparison against real history. Every other pack sits in the template library.
What format are the downloaded files?
Three documents as Word files and four sheets as CSVs, zipped together. The sheets ship with Cordwood Outfitters' illustrative rows in place, so the parity threshold and the bug-versus-intentional split are visible before you replace them with your own models.
How is this different from a generic migration checklist?
Generic checklists validate by calendar phase, one row-count-parity checkbox for the whole project. This pack validates model by model, against real historical data, and forces every divergence into one of two named outcomes: a bug fixed before cutover, or an intentional change documented to its consumer.
We can't run old and new models side by side yet. Can we still start?
Yes. The Migration Plan and Model Mapping do not need both versions running. Output Parity Checks needs both reachable, which is why the pack assumes a parallel run period, six weeks in the worked example, before any model cuts over.
How does it decide if a difference is a bug or something we meant to change?
It does not decide alone. A flagged divergence gets sorted by your team into one of two paths: a bug, fixed in the new model before cutover, or an intentional change, written down and sent to its consumers. A metric's new agreed meaning belongs in the data dictionary afterward.
Does this replace the pipeline documentation pack?
No, they cover different moments. The pipeline documentation pack documents what a running pipeline already tests. This pack validates what changes underneath it during a move or a rebuild, before anything downstream depends on the new version.
Our warehouse can't leave our network. Can we still use this?
Yes. A private AI workspace runs the pack inside your own tenancy, so model definitions, query history and consumer names never cross a boundary your data governance has not approved. The comparison, the registers and the cutover gate work exactly as described here.
Find out which of your models would change a number nobody meant to change
Take the documents and sheets blank, or open this exact pack in River and send it the models actually in scope.
Edit with AI