FAQ Material
Craig Jones
// Craig
--- Practical Usage Questions ---
Q. Is it okay to skip ("burn") patch numbers?
Yes. That's not a problem. Say for example, you want to reverse the order of patches 10 and 14. Simply rename 10 to be 15 (or whatever the next unassigned patch number is), and leave 10 unused. There's no need to adjust higher numbered patches to fill in the gap. In fact, that's usually impossible.
Q. How many changes should I put in a single patch file?As many as make sense to go together, depending on the patch types (sql, java, xml), and depending on the dependency order. For example, a large project that creates three new data tables plus one new config table and obsoletes one old table might have four patches as follows:
- patch_00121_myproject_schema.sql - creates the 4 new tables
- patch_00122_myproject_config_data.xml - initializes the one config table
- patch_00122_myproject_transfer.java - moves data from the one old data table into the 3 new data tables
- patch_00124_myproject_cleanup.sql - drops the old, obsolete table
Q. Is it okay to truncate the patches table?
No. There is a special record with a patch_level value of 0. That
record is used to lock the whole patch table. It is created automatically the first time AutoPatch runs and it must exist for
AutoPatch to continue running. You can delete all other rows, but be
sure to leave that record alone.
--- Theoretical & Implementation Questions ---
Q. How does AutoPatch know what patches to apply?There
is a one-column table in the database called patches. It has one
row for every patch that has been applied. When the app fires up,
AutoPatch makes a list of all available patches and compares that list to
the table.
For OrderedMigrationRunnerStrategy (the default strategy), all patches with patch numbers higher than the highest patch number in the table are executed, and then those patch numbers are added to the table.
For MissingPatchMigrationRunnerStrategy, all patches that have yet to be applied, regardless of whether they are higher or lower than any numbers already in the table, are executed, and then those patch numbers are added to the table.