Tasks available out-of-the-box

Introduction

One of the cool things about the framework is its support for writing arbitrary tasks. As a matter of fact, the primary purpose of the framework, migrations, is just a plain task.

Tasks available out of the box

The framework ships with some convenient tasks out of the box. All tasks are executed by running the main.php script followed by specifying the actual task name.

Task: initializing the database for migration support

A basic task to initialize your DB for migrations is available. One should always run this task when first starting out.

Task name: db:setup

Usage:

    php main.php db:setup

Which outputs something like:

    Started: 2007-09-03 9:34pm PDT

    [db:setup]: 
            Creating table: schema_info
            Done.

    Finished: 2007-09-03 9:34pm PDT

This task will create a schema_info table in your DB with a single column, version which is used to keep track of the current version of your DB.

Task: running migrations

The primary purpose of the framework is to run migrations, and the execution of migrations is all handled by just a regular ol' task.

Task name: db:migrate

Usage:

    php main.php db:migrate

Options: A VERSION parameter can be specified to go up (or down) to a specific version, based on the current version. If not specified, all migrations greater than the current database version will be executed.

Example A: The database is fresh and empty, assuming there are 5 actual migrations, but only the first two should be run.

    php main.php db:migrate VERSION=20101006114707

Which would generate output like:

    ...snip...

    [db:migrate]: 
            Migrating UP to: 20101006114707 (current version: 0)

    ...snip...

Example B: The current version of the DB is 20101006114707 and we want to go down to 20100921114643

    php main.php db:migrate VERSION=20100921114643

Which would generate output like:

    ...snip...

    [db:migrate]: 
            Migrating DOWN to: 20100921114643 (current version: 20101006114707)

    ...snip...

Example C: You can also use relative number of revisions (positive migrate up, negative migrate down).

    php main.php db:migrate VERSION=-2

Task: determing the current DB version

It is always possible to ask the framework (really the DB) what version it is currently at.

Task name: db:version

Usage:

    php main.php db:version

Which would generate output similar to:

    ...snip...

    [db:version]: 
            Current version: 2

    ...snip...

Task: getting the current state of migrations

With this taks you'll get an overview of the already executed migrations and which will be executed when running db:migrate

Task name: db:status

Usage:

    php main.php db:status

Which would generate output similar to:

    ...snip...

    [db:status]: 

            ===================== APPLIED ======================= 
                Test12 [ 20110615090336 ]
            
            ===================== NOT APPLIED ======================= 
                CreateUsersTable [ 20110615093413 ]
            
    ...snip...

Task: dumping the current schema

It can be beneficial to get a dump of the DB in raw SQL format which represents the current version. Note: This dump only contains the actual schema (e.g. the DML needed to reconstruct the DB), but not any actual data. In MySQL terms, this task would not be the same as running the mysqldump command (which by defaults does include any data in the tables).

Task name: db:schema

Usage:

    php main.php db:schema

This task generates a file called db/schema.txt which contains the raw SQL needed to re-generate the schema.

NOTE: This task delegates to the adapter for your RDBMS so the contents of db/schema.txt are likely to be very RDBMS specific.

Writing custom tasks

All tasks follow a basic naming and structure convention. It is this structure and their placement in the lib/tasks directory which allows the framework to automatically find the tasks and register them for use.

Naming Conventions

In a nutshell, task names are pseudo-namespaced. The tasks that come with the framework are namespaced to "db" (e.g. the tasks are "db:migrate", "db:setup", etc).

Based on this structure, the task file names are the namespace portion upper-cased, followed by the remainder, with its first letter capitalized. And then the file name is prefixed with class.

Examples include:

• db:migrate is named class.Ruckusing_DB_Migrate.php
• db:setup is named class.Ruckusing_DB_Setup.php

Interface implementation

All tasks must implement the lib/classes/task/class.Ruckusing_ITask.php interface (named appropriately enough ITask), which currently just has one method: execute().

Your execute() method can do whatever you want.

Objects made available to your task

The framework will automatically make available an object representing the RDBMS adapter object via the adapter private property. For example:

    $result = $this->adapter-> ... 

Running your tasks

If you named your task according to the above conventions and wrote your task to implement the ITask interface and placed the task file in lib/tasks then your task will automatically be made available and thereby executable via the main.php wrapper.

For example lets say you wrote a task file with a name of class.Ruckusing_FS_Hello.php, placed it in the lib/tasks directory, then it would be available via:

    php main.php fs:hello