Building the Technical Case for a Migration

What a Technical Case Actually Is

A technical case is not an argument for migrating. It is an honest account of what migrating would involve, written so that a sceptical reader can check every claim in it. That sounds like a small distinction and it decides whether the document survives contact with its first serious critic.

The practical test: hand it to the person most opposed to the project. If they can attack the conclusion without being able to attack the inputs, you have written a case. If they can dismiss the inputs, you have written a pitch.

Part One — A Measured Inventory

Everything downstream depends on this being counted rather than recalled, and the gap between the two is routinely large. Schemas accumulate objects nobody has thought about in years: tables that are no longer written to, packages superseded but never dropped, indexes built for a report that was retired.

Count objects by type, rows per table, data volume, PL/SQL lines by routine, jobs, sequences, triggers, views and synonyms. One caution that matters: the row counts in the data dictionary are optimiser statistics, not counts. They can be stale by orders of magnitude or simply zero on a table that was never analysed. If a number is load-bearing in your case, count it properly.

-- The estimate: fast, and only as fresh as the last statistics gather
SELECT table_name, num_rows, last_analyzed
FROM   all_tables
WHERE  owner = 'APP'
ORDER  BY num_rows DESC NULLS LAST;

-- The number you quote in the document
SELECT COUNT(*) FROM app.orders;

Part Two — Complexity, Scored Per Object

A total object count tells a reader almost nothing, because the distribution is what determines effort. A thousand tables of simple columns are less work than forty packages using collection types, autonomous transactions and dynamic SQL.

Score each object for conversion difficulty and present the shape: how many convert mechanically, how many need review, how many need rewriting, and which specific ones are in the last group. Naming the hard remainder is the single most credible thing in the document, because it shows you looked for the problems rather than around them.

If you quote an automation rate, be precise about what it measures. A figure for how many objects a tool classifies as convertible is a different claim from how many produce code that compiles and behaves identically, and conflating the two is the most common way these documents lose their footing.

Part Three — An Explicit Scope Boundary

Say what you are not migrating and why. This is usually the largest and least discussed lever in the whole project: an object you decide not to carry costs nothing to convert, nothing to test and nothing to maintain.

Dead tables, superseded packages, reports nobody runs, archive data that belongs in cold storage rather than a live schema. Each exclusion needs a named owner who agreed to it, because the one category of exclusion that reliably comes back is the one nobody confirmed.

Part Four — A Risk Register With Consequences

A risk register listing "data loss" and "performance issues" is decoration. A useful one names a specific mechanism, the consequence in business terms, the mitigation, and who owns it. The discipline of writing the mechanism is what surfaces the risks you had not thought about.

Mechanism                        Consequence                  Mitigation
-------------------------------  ---------------------------  --------------------------
Sequences left behind the        First inserts collide with   Reconcile every sequence
migrated data                    existing keys                past max(column), verified

Date vs timestamp semantics      Reports disagree with        Per-column type review on
differ across the boundary       historical figures           every temporal column

A partial load reports           Records silently absent      Count both sides; treat a
success                                                       mismatch as a failure

Converted PL/SQL not reviewed    Month-end fails at           Human sign-off gate on
                                 month-end                    every flagged routine

Part Five — Commit to a Standard of Proof

Write the verification plan before anyone is invested in the project succeeding. This is the part of the document with the longest shelf life, because by the time you are mid-cutover there is pressure to accept weaker evidence, and a standard agreed in advance is much harder to erode.

Be specific about the levels and what each proves. Row counts catch whole-table failures and nothing subtler. Checksums catch content divergence. Per-partition fingerprints prove byte equality. State which tables get which level, and state that a mismatch stops the cutover rather than generating a warning somebody triages later.

Part Six — The Position You Can Fall Back To

Every case needs a paragraph on turning back: the decision point, the condition that triggers it, the owner, and the state of the business afterwards. For a change-data-capture cutover this is usually a strong section, because the source stays authoritative until someone approves the switch.

If your approach has no clean fallback, the case has to say so plainly. Discovering it during the cutover window is considerably worse than arguing about it now.

What to Leave Out

Anything resting on a number you cannot derive from your own environment. Vendor efficiency multipliers, generic savings percentages, industry-average productivity gains. These are the first things a critic attacks and they are indefensible by construction, because the number was chosen by someone with an interest in the answer.

Separate cleanly what you measured, what you assumed, and what you do not know. A document with three defensible figures and an openly marked unknown is far more durable than one with twenty figures of mixed provenance.

Write Down What Would Change Your Mind

The strongest section in a technical case is the one most people omit: the conditions under which the recommendation would be wrong. If the hard-object count turns out to be three times the estimate, if a dependency you cannot replace has no equivalent, if the team that owns the application cannot take the change this year.

Naming your own weak points makes the case harder to dismantle rather than easier, because it removes the pleasure of finding them for you. It also means that if one of those conditions does appear, you have already agreed in advance what it implies.