github.com/kruftik/go-migrate@v3.5.4+incompatible/MIGRATIONS.md (about) 1 # Migrations 2 3 ## Migration Filename Format 4 5 A single logical migration is represented as two separate migration files, one 6 to migrate "up" to the specified version from the previous version, and a second 7 to migrate back "down" to the previous version. These migrations can be provided 8 by any one of the supported [migration sources](./README.md#migration-sources). 9 10 The ordering and direction of the migration files is determined by the filenames 11 used for them. `migrate` expects the filenames of migrations to have the format: 12 13 {version}_{title}.up.{extension} 14 {version}_{title}.down.{extension} 15 16 The `title` of each migration is unused, and is only for readability. Similarly, 17 the `extension` of the migration files is not checked by the library, and should 18 be an appropriate format for the database in use (`.sql` for SQL variants, for 19 instance). 20 21 Versions of migrations may be represented as any 64 bit unsigned integer. 22 All migrations are applied upward in order of increasing version number, and 23 downward by decreasing version number. 24 25 Common 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 33 Or 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 41 But any scheme resulting in distinct, incrementing integers as versions is valid. 42 43 It is suggested that the version number of corresponding `up` and `down` migration 44 files be equivalent for clarity, but they are allowed to differ so long as the 45 relative ordering of the migrations is preserved. 46 47 The migration files are permitted to be empty, so in the event that a migration 48 is a no-op or is irreversible, it is recommended to still include both migration 49 files, and either leaving them empty or adding a comment as appropriate. 50 51 ## Migration Content Format 52 53 The format of the migration files themselves varies between database systems. 54 Different databases have different semantics around schema changes and when and 55 how they are allowed to occur 56 (for instance, [if schema changes can occur within a transaction](https://wiki.postgresql.org/wiki/Transactional_DDL_in_PostgreSQL:_A_Competitive_Analysis)). 57 58 As such, the `migrate` library has little to no checking around the format of 59 migration sources. The migration files are generally processed directly by the 60 drivers as raw operations. 61 62 ## Reversibility of Migrations 63 64 Best practice for writing schema migration is that all migrations should be 65 reversible. It should in theory be possible for run migrations down and back up 66 through any and all versions with the state being fully cleaned and recreated 67 by doing so. 68 69 By adhering to this recommended practice, development and deployment of new code 70 is cleaner and easier (cleaning database state for a new feature should be as 71 easy as migrating down to a prior version, and back up to the latest). 72 73 As opposed to some other migration libraries, `migrate` represents up and down 74 migrations as separate files. This prevents any non-standard file syntax from 75 being introduced which may result in unintended behavior or errors, depending 76 on what database is processing the file. 77 78 While it is technically possible for an up or down migration to exist on its own 79 without an equivalently versioned counterpart, it is strongly recommended to 80 always include a down migration which cleans up the state of the corresponding 81 up migration.