Getting Started

Getting started in as few steps as possible.

If you are using Composer, then:

• Add a dependency to ruckusing/ruckusing-migrations to your composer.json
• Run php composer.phar update

If you are not using Composer, then:

• Grab the code from GitHub (git clone or a zip)
• Verify runtime requirements
  • PHP5
  • Optional, but recommended, the [http://phpunit.de/ PHPUnit framework] for running the Unit Tests.
• When running the commands below, substitute the location at which you placed the code for vendor/ruckusing/ruckusing-migrations
• When running the commands below, use php main.php in the root of the ruckus code, instead of the ./bin/ruckus.php.bat command

In the root of your codebase, run:

cp vendor/ruckusing/ruckusing-migrations/config/database.inc.php ruckusing.conf.php

Edit "ruckusing_base.conf.php" and fill in the development key with your DB credentials (and change 'ruckusing_base' to dirname(__FILE__) . DIRECTORY_SEPARATOR . 'vendor/ruckusing/ruckusing-migrations')

• All commands in the framework are prefixed with ./bin/ruckus.php.bat followed by the exact task name and then followed by any additional arguments.
  • Examples:

     ./bin/ruckus.php.bat db:setup

     ./bin/ruckus.php.bat db:version

     ./bin/ruckus.php.bat db:migrate

• Initialize your database with the schema_info table so it can start tracking the current version. This can be done by issuing the following command:

    ./bin/ruckus.php.bat db:setup 

Create your first migration

Issue the command:

    ./bin/ruckus.php.bat db:generate create_users_table

The second argument is user-specific and is an underscored delimited list of words which describe your migration in human parseable terms. Examples might be add_index_to_cities_table or create_orders_table or rename_expertise_column_in_users, etc. The framework does not care what the file is called, it is just for your sanity.

Every time the generator runs it creates a timestamped file of the current time. For example the above generator might create a file like db/migrate/20101103105103_CreateUsersTable.php The filename (and class name) is a camel-cased string of the same argument you issued to the command.

Then open up the newly generated file in your favorite text-editor.

The class has two methods, up() and down(). The up() method is where you perform actions to be executed as you run migrations that go up the chain of migrations - that is, all migrations that have NOT been executed against your copy of the database that are based in increasing timestamped order. The down() method is where you execute actions that should be performed as you go down the chain. In most cases in the down() method you would want to undo what you did in the up() method. That is if you create a new table in the up() method then you would want to drop it in the down() method.

In a perfect world you would be able to seamlessly issue up and down migration calls and your RDBMS would be in perfect sync. That is, you dont want to create a table in a given up() method but then not drop it because if you were to do a full up/down cycle then your RDBMS would not allow you to create the same table twice.

Execute your migrations

    ./bin/ruckus.php.bat db:migrate

This command will execute all migrations available, report the output and update your schema info table to the appropriate version.

For a complete example of the migration systems in action, see [CompleteExamples]