A bit of a rewrite of the guide for Minion Migrations.
This commit is contained in:
parent
e0a26722ad
commit
ad6fb8f6c2
|
@ -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',
|
||||
)
|
||||
)
|
||||
);
|
|
@ -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.
|
|
@ -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;
|
||||
|
|
|
@ -1,4 +1,3 @@
|
|||
## [Minion Migrations]()
|
||||
- [Generating Migrations](generating)
|
||||
- [Running Migrations](running)
|
||||
|
||||
- [Generating](generating)
|
||||
- [Running](running)
|
||||
|
|
|
@ -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.
|
||||
|
|
Loading…
Reference in New Issue