summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/migration.rst
diff options
context:
space:
mode:
authorEric Roberts <eric@cryode.com>2012-12-12 14:02:11 +0100
committerEric Roberts <eric@cryode.com>2012-12-12 14:02:11 +0100
commitb9e35f21e1c70b6aa67c47e9244ed83195abc00a (patch)
tree64f82db362deeac48cc20d1d1afd80651f36f5a5 /user_guide_src/source/libraries/migration.rst
parent0b05705c52c3bca7f9b3aee657c888e8ad1ff422 (diff)
parent545a7c86701875e1412bcde316e9bcc76d9a23a0 (diff)
Merge branch 'refs/heads/develop' into feature/form_error_msgs
Conflicts: system/language/english/form_validation_lang.php user_guide_src/source/libraries/form_validation.rst Signed-off-by: Eric Roberts <eric@cryode.com>
Diffstat (limited to 'user_guide_src/source/libraries/migration.rst')
-rw-r--r--user_guide_src/source/libraries/migration.rst160
1 files changed, 159 insertions, 1 deletions
diff --git a/user_guide_src/source/libraries/migration.rst b/user_guide_src/source/libraries/migration.rst
index 5192f1f29..1a73fb78d 100644
--- a/user_guide_src/source/libraries/migration.rst
+++ b/user_guide_src/source/libraries/migration.rst
@@ -2,4 +2,162 @@
Migrations Class
################
-Coming soon. \ No newline at end of file
+Migrations are a convenient way for you to alter your database in a
+structured and organized manner. You could edit fragments of SQL by hand
+but you would then be responsible for telling other developers that they
+need to go and run them. You would also have to keep track of which changes
+need to be run against the production machines next time you deploy.
+
+The database table **migration** tracks which migrations have already been
+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_type']**
+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
+******************
+
+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 **20121031100537_add_blog.php**.::
+
+ <?php
+
+ defined('BASEPATH') OR exit('No direct script access allowed');
+
+ class Migration_Add_blog extends CI_Migration {
+
+ public function up()
+ {
+ $this->dbforge->add_field(array(
+ 'blog_id' => array(
+ 'type' => 'INT',
+ 'constraint' => 5,
+ 'unsigned' => TRUE,
+ 'auto_increment' => TRUE
+ ),
+ 'blog_title' => array(
+ 'type' => 'VARCHAR',
+ 'constraint' => '100',
+ ),
+ 'blog_description' => array(
+ 'type' => 'TEXT',
+ 'null' => TRUE,
+ ),
+ ));
+ $this->dbforge->add_key('blog_id', TRUE);
+ $this->dbforge->create_table('blog');
+ }
+
+ public function down()
+ {
+ $this->dbforge->drop_table('blog');
+ }
+ }
+
+Then in **application/config/migration.php** set **$config['migration_version'] = 1;**.
+
+*************
+Usage Example
+*************
+
+In this example some simple code is placed in **application/controllers/migrate.php**
+to update the schema.::
+
+ <?php
+
+ class Migrate extends CI_Controller
+ {
+ public function index()
+ {
+ $this->load->library('migration');
+
+ if ($this->migration->current() === FALSE)
+ {
+ show_error($this->migration->error_string());
+ }
+ }
+ }
+
+******************
+Function Reference
+******************
+
+$this->migration->current()
+============================
+
+The current migration is whatever is set for **$config['migration_version']** in
+**application/config/migration.php**.
+
+$this->migration->error_string()
+=================================
+
+This returns a string of errors while performing a migration.
+
+$this->migration->find_migrations()
+====================================
+
+An array of migration filenames are returned that are found in the **migration_path**
+property.
+
+$this->migration->latest()
+===========================
+
+This works much the same way as current() but instead of looking for
+the **$config['migration_version']** the Migration class will use the very
+newest migration found in the filesystem.
+
+$this->migration->version()
+============================
+
+Version can be used to roll back changes or step forwards programmatically to
+specific versions. It works just like current but ignores **$config['migration_version']**.::
+
+ $this->load->library('migration');
+
+ $this->migration->version(5);
+
+*********************
+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 schema
+ version number.
+**migration_auto_latest** FALSE TRUE / FALSE Enable or disable automatically
+ running migrations.
+**migration_type** 'timestamp' 'timestamp' / 'sequential' The type of numeric identifier used to name
+ migration files.
+========================== ====================== ========================== =============================================