1# Migrations
2
3## Migration Filename Format
4
5A single logical migration is represented as two separate migration files, one
6to migrate "up" to the specified version from the previous version, and a second
7to migrate back "down" to the previous version. These migrations can be provided
8by any one of the supported [migration sources](./README.md#migration-sources).
9
10The ordering and direction of the migration files is determined by the filenames
11used for them. `migrate` expects the filenames of migrations to have the format:
12
13 {version}_{title}.up.{extension}
14 {version}_{title}.down.{extension}
15
16The `title` of each migration is unused, and is only for readability. Similarly,
17the `extension` of the migration files is not checked by the library, and should
18be an appropriate format for the database in use (`.sql` for SQL variants, for
19instance).
20
21Versions of migrations may be represented as any 64 bit unsigned integer.
22All migrations are applied upward in order of increasing version number, and
23downward by decreasing version number.
24
25Common versioning schemes include incrementing integers:
26
27 1_initialize_schema.down.sql
28 1_initialize_schema.up.sql
29 2_add_table.down.sql
30 2_add_table.up.sql
31 ...
32
33Or timestamps at an appropriate resolution:
34
35 1500360784_initialize_schema.down.sql
36 1500360784_initialize_schema.up.sql
37 1500445949_add_table.down.sql
38 1500445949_add_table.up.sql
39 ...
40
41But any scheme resulting in distinct, incrementing integers as versions is valid.
42
43It is suggested that the version number of corresponding `up` and `down` migration
44files be equivalent for clarity, but they are allowed to differ so long as the
45relative ordering of the migrations is preserved.
46
47The migration files are permitted to be "empty", in the event that a migration
48is a no-op or is irreversible. It is recommended to still include both migration
49files by making the whole migration file consist of a comment.
50If your database does not support comments, then deleting the migration file will also work.
51Note, an actual empty file (e.g. a 0 byte file) may cause issues with your database since migrate
52will attempt to run an empty query. In this case, deleting the migration file will also work.
53For the rational of this behavior see:
54[#244 (comment)](https://github.com/golang-migrate/migrate/issues/244#issuecomment-510758270)
55
56## Migration Content Format
57
58The format of the migration files themselves varies between database systems.
59Different databases have different semantics around schema changes and when and
60how they are allowed to occur
61(for instance, [if schema changes can occur within a transaction](https://wiki.postgresql.org/wiki/Transactional_DDL_in_PostgreSQL:_A_Competitive_Analysis)).
62
63As such, the `migrate` library has little to no checking around the format of
64migration sources. The migration files are generally processed directly by the
65drivers as raw operations.
66
67## Reversibility of Migrations
68
69Best practice for writing schema migration is that all migrations should be
70reversible. It should in theory be possible for run migrations down and back up
71through any and all versions with the state being fully cleaned and recreated
72by doing so.
73
74By adhering to this recommended practice, development and deployment of new code
75is cleaner and easier (cleaning database state for a new feature should be as
76easy as migrating down to a prior version, and back up to the latest).
77
78As opposed to some other migration libraries, `migrate` represents up and down
79migrations as separate files. This prevents any non-standard file syntax from
80being introduced which may result in unintended behavior or errors, depending
81on what database is processing the file.
82
83While it is technically possible for an up or down migration to exist on its own
84without an equivalently versioned counterpart, it is strongly recommended to
85always include a down migration which cleans up the state of the corresponding
86up migration.
View as plain text