Staged rollouts: when the change is the data
Recipe 11 staged an index. Expensive, but the deploy could build it anywhere, any time, so the finished package just declared the new shape and let the deploy convert whoever was left.
Now the change is Customer itself. Profile fields go to CustomerProfile, the address goes to CustomerAddress, and a Customer view takes the old name so every report and every query that reads it keeps working. That one’s different in a way that matters: the rows have to move. No table declaration copies rows. If the deploy drops Customer on a tenant nobody converted, the customers go with it.
So you stage it the same way, with one more part. Let’s take it a window at a time.
Every shape a tenant can be in
Section titled “Every shape a tenant can be in”From 2026.12.0 (until that release is out, the lab runs on a CLI built from main), the staged package declares three things, and each one is gated on what’s already deployed:
- The new tables, ungated.
CustomerProfileandCustomerAddressship to every tenant. They’re empty until a tenant is converted, and an empty table costs nothing. - The old table, gated on the old shape.
Customerstays in the package, so an unconverted tenant keeps it exactly as it is, but only where it’s still a base table:
"ShouldApplyExpression": "EXISTS (SELECT 1 FROM sys.tables WHERE name = 'Customer' AND schema_id = SCHEMA_ID('dbo'))"- The view, in a folder with the opposite gate. The template adds a
Customer Viewscript folder in theAfterTablesObjectsslot, so it runs once the new tables exist, withNOT EXISTSon the same question.
The two gates are each other’s negation. Every tenant gets exactly one Customer: the table where nobody’s converted it, the view where somebody has, and the view on a brand-new tenant that never had the table at all.
The DBA’s window
Section titled “The DBA’s window”A DBA converts t1 by hand: copy the rows into the two new tables, drop Customer, create the view. On SQL Server and PostgreSQL that’s one transaction, so it either all lands or none of it does. MySQL and MariaDB commit DDL as it runs, so their script copies only rows that aren’t there yet, and a re-run after a stop finishes the job.
Then a new customer signs up as t3. Redeploy the staged package, and the fleet comes back in three states from one package: t1 keeps its view, t2 keeps its table, and t3 starts life converted. t1 still answers SELECT COUNT(*) FROM Customer with 2. Through a view now, and no reader can tell.
Finishing a rollout the deploy can’t finish
Section titled “Finishing a rollout the deploy can’t finish”Recipe 11 finished by declaring the new shape and letting the deploy catch the stragglers. That works when the deploy can build the change. Here it can’t, so the finished package carries the conversion itself: the same script the DBA ran, in a Before folder gated on the old shape. It runs before the tables are compared, and only where Customer is still a table.
Preview it, and the straggler gets two lines that look like they disagree:
Would APPLY: .\finished\Templates\Main\Convert Customer\01-split-customer.sqlWARNING: [localhost,11433].[cookbook_r12_t2] Destructive change: table dbo.Customer dropped (about 2 rows). Name it in AcceptDestructive to record it as intended.Read the second one twice. A preview doesn’t run Before scripts, so it plans against t2 as it stands: a Customer table the package no longer declares, which the default DropTablesRemovedFromProduct would drop, customers and all. In the real deploy the conversion runs first, the table’s already gone when the tables are compared, and nothing is dropped. But that warning is exactly what you’d ship if you took the table out of the package and forgot the conversion. That’s the trap this recipe exists for.
Deploy, and t2 is a view with its two customers. Deploy again, and nothing happens: Customer is a view on every tenant now, so the conversion’s gate is false everywhere.
Check yourself: Halfway through the rollout, a teammate removes the Customer table file from the staged package to tidy it up. Nothing else changes. What does the next deploy do to t2, and what would have warned you?
t2 is unconverted, so its Customer is a base table the package no longer declares, and the view folder’s gate is false there. With DropTablesRemovedFromProduct on (the default), the deploy drops the table and its rows, and there’s no conversion to copy them first. A --WhatIf would have shown it: the drop statement, plus a Destructive change: table dbo.Customer dropped warning with the row estimate. Under DestructiveChangePolicy: fail, the same preview exits 2 and the drop never ships. The table stays declared, behind its gate, until the finished package carries the conversion.
Recipe 11 was about letting each piece temper on its own schedule. This one’s about the pieces where the metal itself moves. When you can’t just reshape a piece in place, you don’t pull the old one off the rack until the new one’s carrying the load. Stage the shapes, gate them on what’s deployed, and ship the conversion in the same release the old table leaves.
Got a split or a merge you’ve been putting off because the fleet’s too big to do in one night? Email me at forgebarrett@schemasmith.com. I read every one.
Until then, may every row you move arrive before the table it left is gone.
— Forge