Jifty::Upgrade(3pm) User Contributed Perl Documentation Jifty::Upgrade(3pm)NAME
Jifty::Upgrade - Superclass for schema/data upgrades to Jifty applications
SYNOPSIS
package MyApp::Upgrade;
use base qw/ Jifty::Upgrade /;
use Jifty::Upgrade qw/ since rename /;
since '0.7.4' => sub {
# Rename a column
rename table => 'cthulus', name => 'description',
to => 'mind_numbingly_horrible_word_picture';
};
since '0.6.1' => sub {
my @sizes = ('Huge', 'Gigantic', 'Monstrous', 'Really Big');
my @appearances = ('Horrible', 'Disgusting', 'Frightening', 'Evil');
# populate new columns with some random stuff
my $cthulus = MyApp::Model::CthuluCollection->new;
while (my $cthulu = $cthulus->next) {
$cthulu->set_size($sizes[ int(rand(@sizes)) ]);
$cthulu->set_appearance($appearances[ int(rand(@appearances)) ]);
}
};
DESCRIPTION
"Jifty::Upgrade" is an abstract base class to use to customize schema and data upgrades that happen.
since VERSION SUB
"since" is meant to be called by subclasses of "Jifty::Upgrade". Calling it signifies that SUB should be run when upgrading to version
VERSION, after tables and columns are added, but before tables and columns are removed. If multiple subroutines are given for the same
version, they are run in order that they were set up.
versions
Returns the list of versions that have been registered; this is called by the Jifty::Script::Schema tool to determine what to do while
upgrading.
upgrade_to VERSION
Runs the subroutine that has been registered for the given version; if no subroutine was registered, returns a no-op subroutine.
rename table => CLASS, [column => COLUMN,] to => NAME
Used in upgrade subroutines, this executes the necessary SQL to rename the table, or column in the table, to a new name.
SEE ALSO
Jifty::Manual::Upgrading
perl v5.14.2 2010-12-08 Jifty::Upgrade(3pm)
Check Out this Related Man Page
Jifty::Manual::Upgrading(3pm) User Contributed Perl Documentation Jifty::Manual::Upgrading(3pm)NAME
Jifty::Manual::Upgrading - How-to change your application database over time
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
Be sure you know the following terms before reading this document:
o "schema" in Jifty::Manual::Glossary
o "schema version" in Jifty::Manual::Glossary
o "database version" in Jifty::Manual::Glossary
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.
column extra_info
type is 'text',
label is 'Extra info',
till '0.0.13';
The version you use for "till" is the version the drop is effective. In the example above, the "extra_info" column will be available in
version 0.0.12, but not in version 0.0.13.
This column will be dropped from the schema at the next upgrade, which will destroy all data stored in that column.
TODO Dropping a model
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, 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.
Here we are renaming "zip" to "postcode":
column zip =>
type is 'text',
label is 'ZIP code',
till '0.6.1';
column postcode =>
type is 'text',
label is 'Postal code',
since '0.6.1';
Notice that both "since" and "till" have the same version number set. This is the version number the change will take place.
Before you upgrade, though, you must tell Jifty that a rename is happening here, which is done in your upgrade script:
use MyApp::Upgrade;
use base qw(Jifty::Upgrade);
use Jifty::Upgrade qw( since rename );
since '0.6.1' => sub {
rename(
table => 'MyApp::Model::User',
column => 'zip',
to => 'postcode'
);
};
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:
since '0.2.4' => sub {
my $users = MyApp::Model::UserCollection->new(
current_user => Jifty->app_class('CurrentUser')->superuser
);
$users->unlimit;
while (my $user = $users->next) {
# error checks may save you from hours of debugging
my ($status, $msg) = $user->set_display_name(
join(', ', $user->last_name, $user->first_name)
);
Jifty->log->error("Couldn't change user record: $msg")
unless $status;
}
};
Note that collection created using super user to pass ACL checks and other restrictions, if your models are protected from super user then
you may have problems. See also Jifty::Manual::AccessControl.
SEE ALSO
Jifty::Upgrade, Jifty::Script::Schema, Jifty::Manual::Models, Jifty::Manual::Tutorial, Jifty::Manual::Glossary
perl v5.14.2 2010-09-25 Jifty::Manual::Upgrading(3pm)