[Jifty-commit] r2846 - in jifty/trunk: .

jifty-commit at lists.jifty.org jifty-commit at lists.jifty.org
Mon Feb 26 13:24:12 EST 2007


Author: sterling
Date: Mon Feb 26 13:24:12 2007
New Revision: 2846

Modified:
   jifty/trunk/   (props changed)
   jifty/trunk/lib/Jifty/Manual/Glossary.pod
   jifty/trunk/lib/Jifty/Manual/Upgrading.pod

Log:
updated the upgrading manual and added a few extra glossary items

Modified: jifty/trunk/lib/Jifty/Manual/Glossary.pod
==============================================================================
--- jifty/trunk/lib/Jifty/Manual/Glossary.pod	(original)
+++ jifty/trunk/lib/Jifty/Manual/Glossary.pod	Mon Feb 26 13:24:12 2007
@@ -1,6 +1,6 @@
 =head1 NAME
 
-Jifty::Manual::Glossary
+Jifty::Manual::Glossary - The Jifty dictionary
 
 =head1 GLOSSARY
 
@@ -42,6 +42,10 @@
 canonicalizer could translate a user-typed date into a date object or a
 SQL-formatted date string.  See L<Jifty::Action>.
 
+=item collection
+
+A B</collection> is a class representing all or a subset of the records stored in the database regarding a particular L</model>. See L<Jifty::Collection>.
+
 =item constructor
 
 A property of a L</parameter>; the action B<must> have an argument value for
@@ -60,6 +64,10 @@
 so they are often useful to keep track of tangents that the user went on.  See
 L<Jifty::Continuation>.
 
+=item database version
+
+The B<database version> is the L</schema version> last installed or updated in the application's database. In general, the database version will always match the schema version. The exception is when Jifty is updated to a new schema version, your application updates to a new schema version, or a plugin updates to a new schema version. When this happens, you must L</update> your database so that the database versions and schema versions match before running your application.
+
 =item form field
 
 A widget which the browser renders.  These are generally useful to ask the user
@@ -88,6 +96,10 @@
 A property of a L</parameter>; the user must enter a value for the action to
 validate.  This is the simplest level of L<validation|/validate>.
 
+=item model
+
+Jifty uses L<Jifty::DBI> to store its data (though might use other storage tools at some later time). The B<model> defines the L</schema> and provides a package for creating, reading, updating, and deleting records stored in the database. The model is generally a subclass of L<Jifty::Record>. Access multiple items from a model is performed through a L</collection>.
+
 =item moniker
 
 Every instance of a L<Jifty::Action> has a B<moniker>.  A moniker is
@@ -127,6 +139,34 @@
 success or failure, and further detail about why or how.  It can also contain
 arbitrary "content".  See L<Jifty::Result>.
 
+=item schema
+
+The B<schema> for a L</model> represents the structure of the data stored in an individual item in that model's L</collection>. See L<Jifty::DBI::Schema>.
+
+=item schema version
+
+The B<schema version> is a number in L<version> object used to determine which L</database version> your application code is expecting to use. There are three places where the schema version is important: 
+
+=over
+
+=item 1.
+
+I<Jifty application version>. The Jifty application stores some details in the database.
+
+=item 2.
+
+I<Your database version>. Your application keeps a database version recorded in the configuration. See L<Jifty::Config>.
+
+=item 3.
+
+I<Plugin versions>. Each plugin has a version associated with it affecting whatever C</model>s it uses.
+
+=back 
+
+If any of these versions differs from their respective L</database version>s, then you need to run the L<Jifty::Script::Schema|schema setup script> to L</upgrade> to the latest schema version. 
+
+Contrast with L</database version>.
+
 =item sticky
 
 A property of L</form field>s.  If a field is "sticky," values that the user
@@ -134,6 +174,10 @@
 user type them again.  Most L</action>s have form fields which are sticky on
 failure, so the user can update the information and try again.
 
+=item upgrade
+
+Generally, your Jifty application will change over time. Most of these changes will be simple changes to behavior or appearance. When changes are made to the L</schema> structure of your database, you may need to perform an B<upgrade>. An B<upgrade> is the process by which you rename columns, initialize data, or otherwise update information that needs to be updated when a change to the database needs to be made. See L<Jifty::Upgrade>, L<Jifty::Manual::Upgrading>, and L<Jifty::Script::Schema>.
+
 =item validate
 
 To check that the provided value of an L</argument> is a possible value for it

Modified: jifty/trunk/lib/Jifty/Manual/Upgrading.pod
==============================================================================
--- jifty/trunk/lib/Jifty/Manual/Upgrading.pod	(original)
+++ jifty/trunk/lib/Jifty/Manual/Upgrading.pod	Mon Feb 26 13:24:12 2007
@@ -1,6 +1,6 @@
 =head1 NAME
 
-Jifty::Manual::Upgrading
+Jifty::Manual::Upgrading - How-to change your application database over time
 
 =head2 DESCRIPTION
 
@@ -10,15 +10,62 @@
 almost automatically.  If more extensive changes are required you need
 to write some code to tell Jifty what to do.
 
+=head1 TERMINOLOGY
+
+Be sure you know the following terms before reading this document:
+
+=over
+
+=item *
+
+L<Jifty::Manual::Glossary/schema>
+
+=item *
+
+L<Jifty::Manual::Glossary/schema version>
+
+=item *
+
+L<Jifty::Manual::Glossary/database version>
+
+=back
+
 =head1 HOW TO
 
-=head2 New models and columns
+=head2 General Instructions
+
+For all of these actions, the the database version stored in your Jifty configuration is significant. See the value stored in F<etc/config.yml> at:
+
+  framework:
+    Database:
+      Version: 0.0.1
+
+Make all your code changes using the version number I<you are going to use>. Once you have finished updating your code and are ready to test, bump the version stored in F<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.
+
+=head2 Basic column and model operations
 
 =head3 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.
+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 }
 
@@ -33,7 +80,24 @@
     refers_to Wifty::Model::User, 
     since '0.0.20';
 
-=head2 data migration and schema changes
+=head3 Dropping a column from a model
+
+B<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 C<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 C<till> is the version the drop is effective. In the example above, the C<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, I<which will destroy all data stored in that column.>
+
+=head3 TODO Dropping a model
+
+=head2 Data migration and schema changes
 
 If a file called F<Upgrade.pm> exists in your application it will be
 run by C<jifty schema --setup>.
@@ -57,16 +121,58 @@
 
 =head3 Renaming a column
 
-To rename a column, simply call C<rename> inside your C<since> code block:
+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 C<till> to notify Jifty that the column name no longer exists. The new column name needs to marked with C<since> to notify Jifty that a column by the new name exists. 
 
-    use MyApp::Model::User;
+Here we are renaming C<zip> to C<postcode>:
 
-    since '0.6.1' => sub {
-        rename(
-            table   => 'MyApp::Model::User', 
-            column  => '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 C<since> and C<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'
+     );
+ };
 
 =head3 Migrating data
+
+You can perform any action you want inside the C<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 C<first_name> and C<last_name> before, but we've added a new column C<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;
+      $users->unlimit;
+
+      while (my $user = $users->next) {
+          $user->set_display_name(
+              join(', ', $user->last_name, $user->first_name)
+          );
+      }
+  };
+
+=head1 SEE ALSO
+
+L<Jifty::Upgrade>, L<Jifty::Script::Schema>, L<Jifty::Manual::Models>, L<Jifty::Manual::Tutorial>, L<Jifty::Manual::Glossary>
+
+=cut


More information about the Jifty-commit mailing list