Migrations are not sequential

migrations-are-trees.md

Migrations are trees.

Migration #1:

create table user(
  id text,
  name text,
  password bytea
);

Migration #2:

create table todo_item(
  content text,
  user_id text
);

Migration #3:

alter table user add column region text;

In this example, script #3 depends on #1, but the order that #2 runs on does not matter since it doesn't depend on any other scripts.

Reason why this is important is because relying on a specific sequence to run the scripts is prone to mistakes when someone else tries to merge a script with the same number as yours.

Alembic is by far the most popular migration tool in Python and uses this approach. It would seem that it generates a random id for each script to use as a reference.