-
Notifications
You must be signed in to change notification settings - Fork 28
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #42 from samwilson/guide
An update to the guide
- Loading branch information
Showing
5 changed files
with
133 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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' => '© 2008–2012 Kohana Team', | ||
) | ||
) | ||
); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
# Minion Migrations | ||
|
||
*Migrations? But I'm not leaving the country!* | ||
|
||
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. | ||
|
||
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; |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
## [Minion Migrations]() | ||
- [Generating](generating) | ||
- [Running](running) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
# Running Migrations | ||
|
||
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: | ||
|
||
php index.php migrations:run --up | ||
|
||
This will run all migrations that haven't yet been applied. | ||
|
||
## Go down | ||
|
||
To reverse all migrations (i.e. to delete all the tables in your schema) run this command: | ||
|
||
php index.php migrations:run --down | ||
|
||
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`). | ||
|
||
## Go 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. | ||
|
||
# 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 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. |