NAME

Jifty::Manual::Upgrading

DESCRIPTION

Jifty provides a way for you to upgrade the database schema and data of your application between versions. If all you are doing is adding new models or columns to existing models Jifty will do the upgrade almost automatically. If more extensive changes are required you need to write some code to tell Jifty what to do.

HOW TO

New models and columns

Adding a new model

When adding a new model to your application you need to tell Jifty at which version of your application the model was created. To do this add a since sub to your new model class.

 sub since { 0.0.5 }

Adding a new column to an existing model

When you have an existing model and decide that you need to add another column to it you also need to tell Jifty about this. This is done by using since as well. However, the since goes into the column definition itself.

 column created_by =>
    refers_to Wifty::Model::User, 
    since '0.0.20';

data migration and schema changes

If a file called Upgrade.pm exists in your application it will be run by jifty schema --setup.

Upgrade.pm can be used to make any schema changes or to manipulate your applications data.

At the very least your Upgrade.pm should contain the following:

 package MyApp::Upgrade;

 use base qw(Jifty::Upgrade);
 use Jifty::Upgrade qw( since rename );

 since '0.6.1' => sub {
    ....
 };

The since function is where you do all the work. Each since will be run in version order until the application is up to date.

Renaming a column

To rename a column, simply call rename inside your since code block:

    use MyApp::Model::User;

    since '0.6.1' => sub {
        rename(
            table   => 'MyApp::Model::User', 
            column  => 'zip', 
            to      => 'postcode'
        );
    };

Migrating data