Copyright (c) 2006-2008 Martin Kreidenweis
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
sfPropelMigrationsLightPlugin
Easily change the database structure without losing any data.
What it is
Migrations are a cool thing that I first saw in [RoR]. They allow you to change the database structure between application revisions without losing data, in essence "a system that automates the process of keeping the schema just as flexible as the code basis as soon as your application enters maintanance or production". Have a look at their http://media.rubyonrails.org/video/migrations.mov screencast to see what it is all about.
This plugins is called "light", because it doesn't do any RDBMS-abstraction. So you'll have to manually write SQL code. It currently works quite alright for me, though. And you don't have to write all the SQL code manually of course. Actually you'll just make a diff of the schema.sql file created by propel and copy'n'paste the right parts of it in a new migration file.
I think something more general is planned for Propel 2.0.
Installation
To install just use the symfony task:
symfony plugin-install http://plugins.symfony-project.com/sfPropelMigrationsLightPlugin
You also can install manually by downloading the attached file or checking out from the SVN repository.
Usage
step one -- create migration
The plugin provides an init-migration task. So run php symfony init-migration migration_name. This will generate a new migration class stub in the migrations directory. The migration name is purely informational. I doesn't have to be unique.
Then put code into the up() and down() methods.
The up() code should bring the DB structure to the new version. The down() method should revert what was done in up().
To do that you can use the parent class' (sfMigration) methods, e.g. executeSQL(). Have a look at the source code to see what else there is.
This might look like that in a simple case:
<?php
class Migration001 extends sfMigration
{
public function up()
{
$this->executeSQL("ALTER TABLE foo ADD COLUMN `bar` INTEGER default 0 NOT NULL");
}
public function down()
{
$this->executeSQL("ALTER TABLE foo DROP COLUMN `bar`");
}
}
For the special case of your first migration, the plugin will write the migration for you, using all *.sql files that have been automatically generated by Propel.
step two -- run the migration
To actually update the database you have to run the migrate task.
That will execute all the migrations from the current DB version up to the latest existing migration. (A automatically created table "schema_info" saves the current DB version in the DB itself.)
You have to pass the migrate task an application parameter. Otherwise it won't be able to find the database configuration.
To upgrade or downgrade to a specific DB version call the migrate script with the version as a parameter, e.g. php symfony migrate frontend 42
You'll have to run that task on your production server after every release that contains database structure changes.
(So put a call to it in your upgrade script if you have one.)
There's no harm done by calling the migrate task even if no migrations have been added. It just won't do anything.
More Information
Migrations are wrapped in transactions. So if one command in a migration fails, all the other stuff should theoretically be rolled back.
Unfortunately this doesn't work with DDL at least in MySQL!
You can use Propel objects in your migrations. But generally you should avoid doing that! They always expect the database to have the latest schema version. That means if you e.g. add a column in a later migration the migration code using Propel objects won't work any more.
There is a sfMigration::diag() method you can use in migrations to output messages to the user. Currently it's practically just a wrapper for echo. But you should use it nonetheless as it might be integrated with the task system or logging at a later time.
Fixture Loading
There is some basic support for fixture loading. This brings some problems as fixture loading uses Propel objects. So use it carefully.
Fixture loading works like that:
You add a folder "fixtures" to your migrations directory. In there you can put subdirectories named after the migration number, e.g. "042".
Then, in Migration042::up() you'd write $this->loadFixtures(); at some point and it will load all the YAML files in the "042" directory.
Changelog
2008-07-11 | 1.1.0 (Kris.Wallsmith)
- Added symfony 1.1 tasks
- Added auto-generation of first migration
- Added
->loadSql() method to run SQL from a file
- Coding standards fixes
2008-05-23 | 1.0.1
- develop7: fixed syntax error in sfMigration::addColumn()
2007-10-12 | 0.5.0 Beta
Finally released as a plugin. This is my first plugin, hope everything works...
Comments welcome. :)
2007-09-07
- Migrations are now wrapped in transactions
- Basic support for fixture loading
- Some coding style corrections
- A new diag() function in the migration base class to output information to the command line.
