Database Migration Guide

This is an original planning guide. It is not a vendor manual, an official standard, or legal advice. Example addresses use documentation ranges. Review every command before you paste it.

A migration is a rehearsal you finished

A migration moves a database, or moves it forward a version, while you can still go back. The planner drafts the steps. The downtime estimator turns a restore time and a catch-up time into a window. Both are drafts. The number that matters is the one you measured on a copy.

The backup guide comes first. If you cannot restore, you cannot migrate. The paths guide is the dialect conversion when the engine changes. This page is the order: copy, rehearse, measure, then a later cutover.

Character set, version, and extensions are written at the top. A rehearsal that hides a failing extension until cutover night is a rehearsal you did not read. One failed object is the result. You stop and name it.

You do not migrate by pointing the application at the new database halfway through a test. The application cutover is its own step, after the copy has matched a count you chose.

A lab source, a lab target, one counted table

Restore or copy the lab onto the target. If you are only rehearsing the method, a small lab database is enough. Write the version on each side. Convert one table if the engines differ, using the paths guide's converter as a draft you read.

Count the table on both sides. Pick a column that must survive, such as a date or an amount you invented. They match. Write the minutes the copy took.

Give that measurement to the estimator. The ticket now has a measured number and, if you also typed a guess, the guess is labelled. The window you will ask for is the measured one plus the time to point the application, which you have not done yet.

Leave the application where it is. Rollback of the rehearsal is discarding the target lab. Production is still the source of truth.

A change you can finish

The cutover is a later ticket that names the backup, the measured minutes, and the person who may abort. This window is the rehearsal.

Rollback of a future cutover is the tested backup and the old application setting, written now so the later ticket does not invent them.

Confirm a restore works, or stop.
Write versions, character sets, and extensions.
Copy the lab to a target lab.
Count one table on both sides.
Record the minutes.
Feed the measured number to the estimator.
Do not point the application at the target.

Mistakes that outlive the command

a database migration fails in the same few ways. Each one looks finished on the day you type it. The list is here so the ticket can forbid them before the window, not so you can recognise them in an incident review.

A cutover with no rehearsal.
No backup restore behind the plan.
A guessed downtime sold as a measurement.
Versions left unread.
A converter draft run on production unread.
The application repointed during the test.
Two engines changed and the application changed in one night, unrehearsed.
A failed object ignored because the count of another table matched.
Customer samples pasted into the migration note.
No abort person.

Decisions to write down before the window

One decision for a database migration: A restore has been proven, or this work stops. Versions and character sets are written. The rehearsal used a lab or a copy. One table count matches. Minutes are measured. Guesses are labelled. The application still points at the old place. The paths guide owns dialect conversion. An abort person is named for the future cutover. Rollback is the backup plus the old setting. One database is in this rehearsal. And failed objects are listed, not hidden.

The hour you stop

Write the database name, the host, and the clock time before you change anything for a database migration. If this database is serving people and you do not have a copy, this hour is a plan. A plan you can read tomorrow is a success. A change you cannot undo is not.

Use a lab or a restored copy. The rows you read are rows you are allowed to hold. You do not point a client at a database, a cluster, or an account you do not administer. The tools on this site run in the browser. They do not log in, and they do not scan.

prompt-for-this is a reminder that a secret is missing. It is not a password, a token, or a key you save. The real secret stays in the password store. If a connection string, a log, or a ticket still contains a live secret, stop and rotate it. Then delete the copy.

One change. A config line, an index, a grant, and a restore do not share a window. If two things move and the outcome is wrong, you will not know which one did it. The rollback is the previous file or the backup you already tested.

A second person reads the scope aloud: which host, which database, which account. If they cannot find it in the ticket, the ticket is not ready. Silence is not agreement.

The lab listens on localhost. 127.0.0.1 is the address you bind until a firewall story exists. example.com is not your host. A generated file that listens on every address is a file you edit before it runs.

Do not run a statement you cannot undo. A delete or a drop without a backup and a where-clause you have read is the mistake this page is here to prevent. Read the statement. Count the rows it will touch. Then decide.

Keep the previous config and the previous dump. A generator draft is not the previous file. The previous file is what you put back if the new one is wrong. You practised the reload with a second session open when the change can lock you out.

If a step fails twice, stop. The failure is the result. Adding a command from a forum beside a half-applied config produces a database nobody can explain. Rebuild the lab from the copy you kept.

When the checks pass, the next database waits until someone else can repeat the proof from the notes. a database migration is done for this window when the proof is written, not when the client printed a prompt.

This page is a planning guide. It is not a vendor manual, not an official standard, and not legal advice. If an auditor must see the decision, they see the ticket and the evidence, not this paragraph.

Hand the finished note to the neighbouring guide that owns the next step, and leave this database alone until that guide has its own window.

Migration checks before anyone schedules the cutover

Confirm this before you call the change done: The restore test is dated. Both versions are in the ticket. The target is a lab or a named copy. The table count matches. A meaningful column survived. Minutes were measured. The application was not repointed. Failed objects are listed. No personal sample is in the note. The abort person is named. A second person read the count. The cutover is not tonight. The hostname in the prompt matches the hostname in the ticket for a database migration. The result line includes the time and the person, not only the command. You can point at the rollback value without searching a chat history. And done is a sentence a second person can repeat: the proof for a database migration happened, and the next host is not started early. If one of those fails, stop.

Tools for this guide

These tools run in the browser on this site. They do not log into your machines.

Guides in this cluster

These supporting pages belong to this pillar.

Companion: Cloud: Cloud Migration Strategies (7 Rs).