summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--application/config/migration.php18
-rw-r--r--system/language/english/migration_lang.php1
-rw-r--r--system/libraries/Migration.php230
-rw-r--r--user_guide_src/source/changelog.rst4
-rw-r--r--user_guide_src/source/libraries/migration.rst84
5 files changed, 208 insertions, 129 deletions
diff --git a/application/config/migration.php b/application/config/migration.php
index 7645ade7c..476da1b8e 100644
--- a/application/config/migration.php
+++ b/application/config/migration.php
@@ -39,6 +39,24 @@ $config['migration_enabled'] = FALSE;
/*
|--------------------------------------------------------------------------
+| Migration Style
+|--------------------------------------------------------------------------
+|
+| Migration file names may be based on a sequential identifier or on
+| a timestamp. Options are:
+|
+| 'sequential' = Default migration naming (001_add_blog.php)
+| 'timestamp' = Timestamp migration naming (20121031104401_add_blog.php)
+| Use timestamp format YYYYMMDDHHIISS.
+|
+| If this configuration value is missing the Migration library defaults
+| to 'sequential' for backward compatibility.
+|
+*/
+$config['migration_style'] = 'timestamp';
+
+/*
+|--------------------------------------------------------------------------
| Migrations table
|--------------------------------------------------------------------------
|
diff --git a/system/language/english/migration_lang.php b/system/language/english/migration_lang.php
index 714a1e304..689a72952 100644
--- a/system/language/english/migration_lang.php
+++ b/system/language/english/migration_lang.php
@@ -28,6 +28,7 @@ defined('BASEPATH') OR exit('No direct script access allowed');
$lang['migration_none_found'] = 'No migrations were found.';
$lang['migration_not_found'] = 'No migration could be found with the version number: %d.';
+$lang['migration_sequence_gap'] = 'There is a gap in the migration sequence near version number: %d.';
$lang['migration_multiple_version'] = 'There are multiple migrations with the same version number: %d.';
$lang['migration_class_doesnt_exist'] = 'The migration class "%s" could not be found.';
$lang['migration_missing_up_method'] = 'The migration class "%s" is missing an "up" method.';
diff --git a/system/libraries/Migration.php b/system/libraries/Migration.php
index 06f2f562c..275aeb048 100644
--- a/system/libraries/Migration.php
+++ b/system/libraries/Migration.php
@@ -46,6 +46,13 @@ class CI_Migration {
* @var bool
*/
protected $_migration_enabled = FALSE;
+
+ /**
+ * Migration numbering style
+ *
+ * @var bool
+ */
+ protected $_migration_style = 'sequential';
/**
* Path to migration classes
@@ -74,6 +81,13 @@ class CI_Migration {
* @var bool
*/
protected $_migration_auto_latest = FALSE;
+
+ /**
+ * Migration basename regex
+ *
+ * @var bool
+ */
+ protected $_migration_regex = NULL;
/**
* Error message
@@ -126,12 +140,21 @@ class CI_Migration {
{
show_error('Migrations configuration file (migration.php) must have "migration_table" set.');
}
+
+ // Migration basename regex
+ $this->_migration_regex = $this->_migration_style === 'timestamp' ? '/^\d{14}_(\w+)$/' : '/^\d{3}_(\w+)$/';
+
+ // Make sure a valid migration numbering style was set.
+ if ( ! in_array($this->_migration_style, array('sequential', 'timestamp')))
+ {
+ show_error('An invalid migration numbering style was specified: '.$this->_migration_style);
+ }
// If the migrations table is missing, make it
if ( ! $this->db->table_exists($this->_migration_table))
{
$this->dbforge->add_field(array(
- 'version' => array('type' => 'INT', 'constraint' => 3),
+ 'version' => array('type' => 'BIGINT', 'constraint' => 20),
));
$this->dbforge->create_table($this->_migration_table, TRUE);
@@ -159,113 +182,80 @@ class CI_Migration {
*/
public function version($target_version)
{
- $start = $current_version = $this->_get_version();
- $stop = $target_version;
-
+ $current_version = (int) $this->_get_version();
+ $target_version = (int) $target_version;
+
+ $migrations = $this->find_migrations();
+
+ if ($target_version > 0 AND ! isset($migrations[$target_version]))
+ {
+ $this->_error_string = sprintf($this->lang->line('migration_not_found'), $target_version);
+ return FALSE;
+ }
+
if ($target_version > $current_version)
{
// Moving Up
- ++$start;
- ++$stop;
- $step = 1;
+ $method = 'up';
}
else
{
- // Moving Down
- $step = -1;
+ // Moving Down, apply in reverse order
+ $method = 'down';
+ krsort($migrations);
}
- $method = $step === 1 ? 'up' : 'down';
- $migrations = array();
-
- // We now prepare to actually DO the migrations
- // But first let's make sure that everything is the way it should be
- for ($i = $start; $i != $stop; $i += $step)
+ if (empty($migrations))
{
- $f = glob(sprintf($this->_migration_path.'%03d_*.php', $i));
+ return TRUE;
+ }
+
+ $previous = FALSE;
- // Only one migration per step is permitted
- if (count($f) > 1)
+ // Validate all available migrations, and run the ones within our target range
+ foreach ($migrations as $number => $file)
+ {
+ // Check for sequence gaps
+ if ($this->_migration_style === 'sequential' AND $previous !== FALSE AND abs($number - $previous) > 1)
{
- $this->_error_string = sprintf($this->lang->line('migration_multiple_version'), $i);
+ $this->_error_string = sprintf($this->lang->line('migration_sequence_gap'), $number);
return FALSE;
}
+
+ include $file;
+ $class = 'Migration_'.ucfirst(strtolower($this->_get_migration_name(basename($file, '.php'))));
- // Migration step not found
- if (count($f) === 0)
+ // Validate the migration file structure
+ if ( ! class_exists($class))
{
- // If trying to migrate up to a version greater than the last
- // existing one, migrate to the last one.
- if ($step === 1)
- {
- break;
- }
-
- // If trying to migrate down but we're missing a step,
- // something must definitely be wrong.
- $this->_error_string = sprintf($this->lang->line('migration_not_found'), $i);
+ $this->_error_string = sprintf($this->lang->line('migration_class_doesnt_exist'), $class);
return FALSE;
}
-
- $file = basename($f[0]);
- $name = basename($f[0], '.php');
-
- // Filename validations
- if (preg_match('/^\d{3}_(\w+)$/', $name, $match))
- {
- $match[1] = strtolower($match[1]);
-
- // Cannot repeat a migration at different steps
- if (in_array($match[1], $migrations))
- {
- $this->_error_string = sprintf($this->lang->line('migration_multiple_version'), $match[1]);
- return FALSE;
- }
-
- include $f[0];
- $class = 'Migration_'.ucfirst($match[1]);
-
- if ( ! class_exists($class))
- {
- $this->_error_string = sprintf($this->lang->line('migration_class_doesnt_exist'), $class);
- return FALSE;
- }
-
- if ( ! is_callable(array($class, $method)))
- {
- $this->_error_string = sprintf($this->lang->line('migration_missing_'.$method.'_method'), $class);
- return FALSE;
- }
-
- $migrations[] = $match[1];
- }
- else
+ elseif ( ! is_callable(array($class, $method)))
{
- $this->_error_string = sprintf($this->lang->line('migration_invalid_filename'), $file);
+ $this->_error_string = sprintf($this->lang->line('migration_missing_'.$method.'_method'), $class);
return FALSE;
}
+
+ $previous = $number;
+
+ // Run migrations that are inside the target range
+ if (
+ ($method === 'up' AND $number > $current_version AND $number <= $target_version) OR
+ ($method === 'down' AND $number <= $current_version AND $number > $target_version)
+ ) {
+ log_message('debug', 'Migrating '.$method.' from version '.$current_version.' to version '.$number);
+ call_user_func(array(new $class, $method));
+ $current_version = $number;
+ $this->_update_version($current_version);
+ }
}
-
- log_message('debug', 'Current migration: '.$current_version);
-
- $version = $i + ($step === 1 ? -1 : 0);
-
- // If there is nothing to do so quit
- if ($migrations === array())
- {
- return TRUE;
- }
-
- log_message('debug', 'Migrating from '.$method.' to version '.$version);
-
- // Loop through the migrations
- foreach ($migrations AS $migration)
+
+ // This is necessary when moving down, since the the last migration applied
+ // will be the down() method for the next migration up from the target
+ if ($current_version <> $target_version)
{
- // Run the migration class
- $class = 'Migration_'.ucfirst(strtolower($migration));
- call_user_func(array(new $class, $method));
-
- $current_version += $step;
+ $current_version = $target_version;
$this->_update_version($current_version);
}
@@ -283,17 +273,19 @@ class CI_Migration {
*/
public function latest()
{
- if ( ! $migrations = $this->find_migrations())
+ $migrations = $this->find_migrations();
+
+ if (empty($migrations))
{
$this->_error_string = $this->lang->line('migration_none_found');
return FALSE;
}
$last_migration = basename(end($migrations));
-
+
// Calculate the last migration step from existing migration
// filenames and procceed to the standard version migration
- return $this->version((int) $last_migration);
+ return $this->version($this->_get_migration_number($last_migration));
}
// --------------------------------------------------------------------
@@ -327,22 +319,60 @@ class CI_Migration {
*
* @return array list of migration file paths sorted by version
*/
- protected function find_migrations()
+ public function find_migrations()
{
+ $migrations = array();
+
// Load all *_*.php files in the migrations path
- $files = glob($this->_migration_path.'*_*.php');
-
- for ($i = 0, $c = count($files); $i < $c; $i++)
+ foreach (glob($this->_migration_path.'*_*.php') as $file)
{
- // Mark wrongly formatted files as false for later filtering
- if ( ! preg_match('/^\d{3}_(\w+)$/', basename($files[$i], '.php')))
+ $name = basename($file, '.php');
+
+ // Filter out non-migration files
+ if (preg_match($this->_migration_regex, $name))
{
- $files[$i] = FALSE;
+ $number = $this->_get_migration_number($name);
+
+ // There cannot be duplicate migration numbers
+ if (isset($migrations[$number]))
+ {
+ $this->_error_string = sprintf($this->lang->line('migration_multiple_version'), $number);
+ show_error($this->_error_string);
+ }
+
+ $migrations[$number] = $file;
}
}
- sort($files);
- return $files;
+ ksort($migrations);
+ return $migrations;
+ }
+
+ // --------------------------------------------------------------------
+
+ /**
+ * Extracts the migration number from a filename
+ *
+ * @return int Numeric portion of a migration filename
+ */
+ protected function _get_migration_number($migration)
+ {
+ $parts = explode('_', $migration);
+ return (int) $parts[0];
+ }
+
+ // --------------------------------------------------------------------
+
+ /**
+ * Extracts the migration class name from a filename
+ *
+ * @return string text portion of a migration filename
+ */
+ protected function _get_migration_name($migration)
+ {
+ $parts = explode('_', $migration);
+ array_shift($parts);
+ return implode('_', $parts);
}
// --------------------------------------------------------------------
@@ -366,10 +396,10 @@ class CI_Migration {
* @param int Migration reached
* @return void Outputs a report of the migration
*/
- protected function _update_version($migrations)
+ protected function _update_version($migration)
{
return $this->db->update($this->_migration_table, array(
- 'version' => $migrations
+ 'version' => $migration
));
}
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index 1a80f76a3..707d8b3ea 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -40,6 +40,7 @@ Release Date: Not Released
- Updated support for csv files in mimes.php.
- Added some more doctypes.
- Added Romanian, Greek, Vietnamese and Cyrilic characters in *application/config/foreign_characters.php*.
+ - Added Romanian, Greek and Vietnamese characters in *foreign_characters.php*.
- Changed logger to only chmod when file is first created.
- Removed previously deprecated SHA1 Library.
- Removed previously deprecated use of ``$autoload['core']`` in *application/config/autoload.php*.
@@ -249,6 +250,9 @@ Release Date: Not Released
- Removed previously deprecated ``sha1()`` method.
- Changed :doc:`Language Library <libraries/language>` method ``load()`` to filter the language name with ``ctype_digit()``.
- :doc:`Profiler Library <general/profiling>` now also displays database object names.
+ - :doc:`Migration Library <libraries/migration>` changes include:
+ - Added support for timestamp-based migrations (enabled by default)
+ - Added ``$config['migration_style']`` to allow switching between sequential migrations and timestamp migrations
- Core
diff --git a/user_guide_src/source/libraries/migration.rst b/user_guide_src/source/libraries/migration.rst
index cb7d96a6d..246396171 100644
--- a/user_guide_src/source/libraries/migration.rst
+++ b/user_guide_src/source/libraries/migration.rst
@@ -13,17 +13,40 @@ run so all you have to do is update your application files and
call **$this->migrate->current()** to work out which migrations should be run.
The current version is found in **config/migration.php**.
+********************
+Migration file names
+********************
+
+Each Migration is run in numeric order forward or backwards depending on the
+method taken. Two numbering styles are available:
+
+* **Sequential:** each migration is numbered in sequence, starting with **001**.
+ Each number must be three digits, and there must not be any gaps in the
+ sequence. (This was the numbering scheme prior to CodeIgniter 3.0.)
+* **Timestamp:** each migration is numbered using the timestamp when the migration
+ was created, in **YYYYMMDDHHIISS** format (e.g. **20121031100537**). This
+ helps prevent numbering conflicts when working in a team environment, and is
+ the preferred scheme in CodeIgniter 3.0 and later.
+
+The desired style may be selected using the **$config['migration_style']**
+setting in your **migration.php** config file.
+
+Regardless of which numbering style you choose to use, prefix your migration
+files with the migration number followed by an underscore and a descriptive
+name for the migration. For example:
+
+* **001_add_blog.php** (sequential numbering)
+* **20121031100537_add_blog.php** (timestamp numbering)
+
******************
Create a Migration
******************
-
-.. note:: Each Migration is run in numerical order forward or backwards
- depending on the method taken. Use a prefix of 3 numbers followed by an
- underscore for the filename of your migration.
This will be the first migration for a new site which has a blog. All
migrations go in the folder **application/migrations/** and have names such
-as: **001_add_blog.php**.::
+as **20121031100537_add_blog.php**.::
+
+ <?php
defined('BASEPATH') OR exit('No direct script access allowed');
@@ -47,7 +70,7 @@ as: **001_add_blog.php**.::
'null' => TRUE,
),
));
-
+ $this->dbforge->add_key('blog_id', TRUE);
$this->dbforge->create_table('blog');
}
@@ -55,6 +78,7 @@ as: **001_add_blog.php**.::
{
$this->dbforge->drop_table('blog');
}
+ }
Then in **application/config/migration.php** set **$config['migration_version'] = 1;**.
@@ -65,25 +89,25 @@ Usage Example
In this example some simple code is placed in **application/controllers/migrate.php**
to update the schema.::
- $this->load->library('migration');
-
- if ( ! $this->migration->current())
+ <?php
+
+ class Migrate extends CI_Controller
{
- show_error($this->migration->error_string());
+ public function index()
+ {
+ $this->load->library('migration');
+
+ if ($this->migration->current() === FALSE)
+ {
+ show_error($this->migration->error_string());
+ }
+ }
}
******************
Function Reference
******************
-There are five available methods for the Migration class:
-
-- $this->migration->current();
-- $this->migration->error_string();
-- $this->migration->find_migrations();
-- $this->migration->latest();
-- $this->migration->version();
-
$this->migration->current()
============================
@@ -124,14 +148,16 @@ Migration Preferences
The following is a table of all the config options for migrations.
-========================== ====================== ============= =============================================
-Preference Default Options Description
-========================== ====================== ============= =============================================
-**migration_enabled** FALSE TRUE / FALSE Enable or disable migrations.
-**migration_path** APPPATH.'migrations/' None The path to your migrations folder.
-**migration_version** 0 None The current version your database should use.
-**migration_table** migrations None The table name for storing the shema
- version number.
-**migration_auto_latest** FALSE TRUE / FALSE Enable or disable automatically
- running migrations.
-========================== ====================== ============= =============================================
+========================== ====================== ========================== =============================================
+Preference Default Options Description
+========================== ====================== ========================== =============================================
+**migration_enabled** FALSE TRUE / FALSE Enable or disable migrations.
+**migration_path** APPPATH.'migrations/' None The path to your migrations folder.
+**migration_version** 0 None The current version your database should use.
+**migration_table** migrations None The table name for storing the schema
+ version number.
+**migration_auto_latest** FALSE TRUE / FALSE Enable or disable automatically
+ running migrations.
+**migration_style** 'timestamp' 'timestamp' / 'sequential' The type of numeric identifier used to name
+ migration files.
+========================== ====================== ========================== =============================================