github.com/sujit-baniya/migrate@v0.0.4/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", in the event that a migration
    48  is a no-op or is irreversible. It is recommended to still include both migration
    49  files by making the whole migration file consist of a comment.
    50  If your database does not support comments, then deleting the migration file will also work.
    51  Note, an actual empty file (e.g. a 0 byte file) may cause issues with your database since migrate
    52  will attempt to run an empty query. In this case, deleting the migration file will also work.
    53  For 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  
    58  The format of the migration files themselves varies between database systems.
    59  Different databases have different semantics around schema changes and when and
    60  how 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  
    63  As such, the `migrate` library has little to no checking around the format of
    64  migration sources.  The migration files are generally processed directly by the
    65  drivers as raw operations.
    66  
    67  ## Reversibility of Migrations
    68  
    69  Best practice for writing schema migration is that all migrations should be
    70  reversible.  It should in theory be possible for run migrations down and back up
    71  through any and all versions with the state being fully cleaned and recreated
    72  by doing so.
    73  
    74  By adhering to this recommended practice, development and deployment of new code
    75  is cleaner and easier (cleaning database state for a new feature should be as
    76  easy as migrating down to a prior version, and back up to the latest).
    77  
    78  As opposed to some other migration libraries, `migrate` represents up and down
    79  migrations as separate files.  This prevents any non-standard file syntax from
    80  being introduced which may result in unintended behavior or errors, depending
    81  on what database is processing the file.
    82  
    83  While it is technically possible for an up or down migration to exist on its own
    84  without an equivalently versioned counterpart, it is strongly recommended to
    85  always include a down migration which cleans up the state of the corresponding
    86  up migration.