NAME

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.

TERMINOLOGY

HOW TO

General Instructions

For all of these actions, the the database version stored in your Jifty configuration is significant. See the value stored in etc/config.yml at:

framework:
Database:
Version: 0.0.1

Make all your code changes using the version number you are going to use. Once you have finished updating your code and are ready to test, bump the version stored in etc/config.yml to match the new version you are going to use.

If you are writing tests as you go (shame on you if you aren't!), you should be able to run:

perl Makefile.PL
make
make test

to test the latest version and check for problems.

Once you are sure you've worked out the kinds, you may perform the actual upgrade by running:

bin/jifty schema --setup

This will take care of the work of adding any new columns and models, dropping old columns, and running any upgrade scripts you have scheduled.

Basic column and model operations

Adding a new model

Create your model just as you normally would:

bin/jifty model --name MyModel

Then, 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';

Dropping a column from a model

CAUTION: Be aware that all the data that was stored in this column will be destroyed at upgrade if you follow this procedure.

If you no longer need a particular column in your model, you can have it dropped by setting the till property on your column definition.

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, you need to make sure that your schema and upgrade script both cooperate in the process. Your schema will record changes to your model API and the upgrade script will tell Jifty about the rename.

The old column name needs to marked with till to notify Jifty that the column name no longer exists. The new column name needs to marked with since to notify Jifty that a column by the new name exists.

Migrating data

You can perform any action you want inside the since blocks of your upgrade script. In the case of data migration, you might want to convert your data from one form to another.

For example, let's say our users always gave us first_name and last_name before, but we've added a new column display_name which will normally contain their name in "last, first" format, but could be customized per-account. We want to go ahead and initialize this new column during the upgrade. In your upgrade script, you could add: