diff --git a/config/userguide.php b/config/userguide.php new file mode 100755 index 0000000..db85f99 --- /dev/null +++ b/config/userguide.php @@ -0,0 +1,23 @@ + array( + + // This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename' + 'minion-migrations' => array( + + // Whether this modules userguide pages should be shown + 'enabled' => TRUE, + + // The name that should show up on the userguide index page + 'name' => 'Minion Migrations', + + // A short description of this module, shown on the index page + 'description' => "Migration tasks for Kohana's Minion CLI framework.", + + // Copyright message, shown in the footer for this module + 'copyright' => '© 2008–2012 Kohana Team', + ) + ) +); \ No newline at end of file diff --git a/guide/minion-migrations/generating.md b/guide/minion-migrations/generating.md new file mode 100755 index 0000000..0f94e17 --- /dev/null +++ b/guide/minion-migrations/generating.md @@ -0,0 +1,24 @@ +# New Migrations + +Every set of modifications to the database schema should be done through a new Migration. + +The task for this is `migrations:new`, and its full documentation is available with the usual help command: + + php index.php migrations:new --help + +The `migrations:new` task takes three parameters: *group*, *location*, and *description*. +A new file will be created, containing the skeleton of a child class of [Minion_Migration_Base] +that must be fleshed out with code to perform the migration (and its reversal). + +## Group + +Groups provide a means to run particular sets of Migrations separately. +Every Migration must be in a group. + +For modules' Migrations, the group name is usually the same as the module name (or at least prefixed with it). + +## Description + +The description is optional, and if provided will be turned into a normalised suffix +for the Migration class's file (e.g. `20130529140938_initial-installation.php`) +and also shown in the output of the `status` and `run` tasks. diff --git a/guide/minion-migrations/index.md b/guide/minion-migrations/index.md index 42c2cbd..e2a23af 100644 --- a/guide/minion-migrations/index.md +++ b/guide/minion-migrations/index.md @@ -1,8 +1,33 @@ # Minion Migrations -## Migrations? But I'm not leaving the country! +*Migrations? But I'm not leaving the country!* -The term "Migrations" is used to describe the movement from one location to another. -In the context of databases it refers to managing differences between schemas. In essence, it's version control for databases. +The term "migration" is used to describe the movement from one location to another. +In the context of databases it refers to managing differences between schemas. +In essence, it's version control for databases, and this module makes it easy to roll back to earlier versions at any time. -When you make a change to your schema you store a copy of the SQL you ran in a migration file, along with SQL that will revert the changes you made. +Every set of changes to the database schema is carried out from a Migration, +which is just a class that extends [Minion_Migration_Base]. +These Migration classes each contain an `up()` and `down()` method, +which do the work of applying changes to the database schema and undoing these changes, respectively. + +Once a Migration has been released (i.e. has possibly been run on a production system) it should not be modified. +Instead, new Migrations must be created. + +## Metadata table + +The first time a Migration is run, a special table (by default called `minion_migrations`) is created +in which to store information about which Migrations have been applied. + +The table name can be customised with the `minion/migration.table` [configuration value](../kohana/files/config). + +The table definition is as follows: + + CREATE TABLE `` ( + `timestamp` varchar(14) NOT NULL, + `description` varchar(100) NOT NULL, + `group` varchar(100) NOT NULL, + `applied` tinyint(1) DEFAULT '0', + PRIMARY KEY (`timestamp`,`group`), + UNIQUE KEY `MIGRATION_ID` (`timestamp`,`description`) + ) ENGINE=MyISAM DEFAULT CHARSET=utf8; diff --git a/guide/minion-migrations/menu.md b/guide/minion-migrations/menu.md index e20bf0a..1776b5a 100644 --- a/guide/minion-migrations/menu.md +++ b/guide/minion-migrations/menu.md @@ -1,4 +1,3 @@ ## [Minion Migrations]() -- [Generating Migrations](generating) -- [Running Migrations](running) - +- [Generating](generating) +- [Running](running) diff --git a/guide/minion-migrations/running.md b/guide/minion-migrations/running.md index a1dc172..34aefde 100644 --- a/guide/minion-migrations/running.md +++ b/guide/minion-migrations/running.md @@ -1,36 +1,50 @@ # Running Migrations -## Going up +The reference documentation for running migrations can be viewed in the usual way: + + php index.php migrations:run --help + +## Find out where you are + +At any time, the current status of completed and pending migrations can be found with: + + php index.php migrations:status + +There are no options for `status` (other than `--help`). + +## Go up To migrate your schema to the latest possible version run the command: - ./minion db:migrate + php index.php migrations:run --up -This command is synonomous with +This will run all migrations that haven't yet been applied. - ./minion db:migrate --migrate-up +## Go down -Which will run all migrations that haven't yet been applied to the schema, bringing it back in sync with the migrations in the filesystem. +To reverse all migrations (i.e. to delete all the tables in your schema) run this command: -## Going down + php index.php migrations:run --down -To unapply all migrations (i.e. to delete all the tables in your schema) run this command: +Note that this will actually only go down as far as the *lowest migration* +[configuration value](../kohana/files/config) (defined by `minion/migration.lowest_migration`). - ./minion db:migrate --migrate-down +## Go over there -## Going over there +If you want to a specific version of your schema then you can use the `--to` switch, +which accepts either a migration's timestamp or a relative pointer to a migration. +This must be used with the `--group` switch. -If you want to a specific version of your schema then you can use the `--migrate-to` switch, which accepts either a migration's timestamp or a relative pointer to a migration. - - // Migrate the schema 5 versions down - --migrate-to=-5 - - // Migrate the schema 10 versions up - --migrate-to=+5 - - // Migrate to a specific version - --migrate-to=201102190811 + # Migrate the schema 5 versions down + --to=-5 + + # Migrate the schema 10 versions up: + --to=+10 + + # Migrate to a specific version + --to=201102190811 ## Look before you leap -If you want to see what SQL is going to be executed by the migrate task then simply pass the `--dry-run` switch and the SQL will be printed to the console instead of being executed. +If you want to see what a Migration is going to do then you can use the `--dry-run` switch +and the SQL will be printed to the console instead of being executed.