Merge pull request #1771 from pickupman/user_guide-migrations

Add documation to user guide for Migrations class

1 files changed, 133 insertions, 1 deletions

diff --git a/user_guide_src/source/libraries/migration.rst b/user_guide_src/source/libraries/migration.rst
index 5192f1f29..cb7d96a6d 100644
--- a/user_guide_src/source/libraries/migration.rst
+++ b/user_guide_src/source/libraries/migration.rst
@@ -2,4 +2,136 @@
 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**.
+
+******************
+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**.::
+
+	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->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.::
+
+	$this->load->library('migration');
+
+	if ( ! $this->migration->current())
+	{
+		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()
+============================
+
+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 shema
+                                                                version number.
+**migration_auto_latest**  FALSE                  TRUE / FALSE  Enable or disable automatically 
+                                                                running migrations.
+========================== ====================== ============= =============================================