# Database migrations in plain words

> A migration is a scripted change to the shape of a database, run once and kept with the code. Why existing rows and the order of deploys matter, and how to change a column safely.

Source: https://hintvo.com/blog/database-migrations-in-plain-words | Last updated: November 20, 2026 | Reviewed: 2026-11-20

A migration is a scripted change to the shape of a database: a new table, a new column, a renamed field. It is written once, kept in the repository with the code, and run exactly once on each database, so that the code and the data always agree about the shape.

## Why not change the database by hand

- Every environment has to get the same change: your laptop, the test server, production.
- The change has to be reviewed like code.
- Six months later, someone has to be able to see what was changed and why.

## What a migration looks like

```sql
-- 0042_add_idempotency_key_to_orders.sql
ALTER TABLE orders ADD COLUMN idempotency_key TEXT;
CREATE UNIQUE INDEX orders_idempotency_key ON orders (idempotency_key);
```

The migration tool keeps a list of which migrations have already run, and runs only the new ones, in order.

## The part people forget: the rows that already exist

A new column on an empty table is easy. On a table with ten million rows, the same change raises questions. What value do the old rows get? Can the column be required if the old rows have nothing in it? How long does the change lock the table?

## The order of deploys

During a deploy, old code and new code run side by side for a while. A migration that is safe for only one of them breaks the other. So a change that removes or renames something is done in steps:

1. Add the new column. Old code ignores it.
2. Deploy code that writes to both columns and reads the new one.
3. Copy the old data across.
4. Deploy code that no longer uses the old column.
5. Remove the old column.

It is more steps, and none of them can take the site down.

## Questions you will hear in a meeting

- Is this migration safe to run while the old code is still serving requests?
- How long will it lock the table?
- Can we roll it back, and what happens to data written in between?
- Who runs it, and when?

## In an interview

When you add a field in a system design round or a take-home review, say how the existing rows are handled. Mentioning the migration without being asked is a small sign of real experience.

> **Where Hintvo fits:** when a term like this comes up in a call, the In plain words card explains it in one sentence, in the context of your project. When someone asks how your own code handles it, the answer names the file and line.

## Related

- [Sprint planning: estimate from what the change touches](https://hintvo.com/blog/sprint-planning-estimates-from-the-code.md): How do I give a realistic estimate in sprint planning for code I have not read?
- [Database indexes in plain words](https://hintvo.com/blog/database-indexes-in-plain-words.md): What is a database index, in plain words?
- [Design reviews: ten questions worth asking](https://hintvo.com/blog/design-review-questions-worth-asking.md): What questions should I ask in a design review?
