A bit of a rewrite of the guide for Minion Migrations.

This commit is contained in:
Sam Wilson 2013-05-30 08:35:29 +08:00
parent e0a26722ad
commit ad6fb8f6c2
5 changed files with 112 additions and 27 deletions

23
config/userguide.php Executable file
View File

@ -0,0 +1,23 @@
<?php defined('SYSPATH') OR die('No direct script access.');
return array(
// Leave this alone
'modules' => 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' => '&copy; 20082012 Kohana Team',
)
)
);

View File

@ -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.

View File

@ -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 `<table_name>` (
`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;

View File

@ -1,4 +1,3 @@
## [Minion Migrations]()
- [Generating Migrations](generating)
- [Running Migrations](running)
- [Generating](generating)
- [Running](running)

View File

@ -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.