Ready?!?

Today we will talk about migrations, yaml files and CakePHP and in particular I'll introduce you to the latest shell I've written for CakePHP: YAMMY!

I've written YAMMY! a couple of weeks ago, but I just found the time to release it today. Anyway lets get into more details!

WHAT ARE MIGRATIONS?

Well migrations are what revision control systems (SVN or CVS) is for files but applied to database tables.

Migrations allow you to define changes to your database schema, making it possible to use a version control system to keep things synchronized with the actual code.

This has many uses, including:

1. Teams of developers – if one person makes a schema change, the other developers just need to update, and they can simply run a migration.
2. Production servers – use migrations when you roll out a new release to bring the database up to date as well.
3. Multiple machines – if you develop on both a desktop and a laptop, or in more than one location, migrations can help you keep them all synchronised.

MIGRATIONS IN CAKEPHP

Joel Moss brought migrations to CakePHP in 2006, with his excellent migration shell, that has now reached version 3.3. In order to get more confident with migrations in CakePHP, I suggest you a couple of tutorials:

• The Joy of Cake migrations - my first tutorial by Joel Moss
• How Table Migrations In CakePHP 1.2 Can Save Your Life (by Tim Koschuetzki)

As you might have discovered in order to run migrations in CakePHP 1.2, you need to add a few pices to your Cake application:

• Joel migration shell
• PEAR MDB2 (put it in app/vendors)
  
• the right MDB2 driver (the mysql_driver in my case)

You then need to configure your PATH environment variable in order to tell your server where the hell cake is located. These two screencats will help you sorting these out:

• Setting Up the CakePHP Console on *nix
• Setting Up the CakePHP Console on Windows

Now you are nearly ready to go with YAMMY! and to speed up your application development and project management.

YAMMY!: feed your migrations faster

The migration infrastructure described above needs the "right food" in order to work properly.

To use migrations you need to provide some files in YAML format telling the migration shell what to do. Writing a DB table structure in a yaml format is pretty boring and time consuming: YAMMY! enters into the game here.

YAMMY! provides a convenient and super fast way to feed your migrations converting your DB tables schema into a YAML format in few seconds.

YAMMY! requirements

Before I'll go into further details let's see what you need to use YAMMY!

1. download the Spyc class v.0.3 and put it in your app/vendors directory
2. download YAMMY! 1.0 and put it in your app/vendors/shells directory

YAMMY! in action

Now if you set the CakePHP console properly as described in the two screencasts above, you are ready to go!

Open your Shell/Console and move (cd ..) to your app directory (on my development machine I have all my projects in C:\www for example, lets say I'm working on a project called test, I'll them move to C:\www\test\app).

Once your Shell/Console points to your app directory type cake yammy

Great you entered YAMMY! in interactive mode and YAMMY! will ask you which tables you want to convert.

After answering a few questions (the DB connection you wanna use and which tables you want to convert to yaml files) YAMMY! will write a file in app/config/migrations with your DB schema converted to a YAML format, and you are ready to start your migrations wih the migration shell!

For a complete overview of all YAMMY! functionality type in your console cake yammy help.

YAMMY runs both in interactive and direct mode.

• just typing cake yammy you will go in interactive mode and YAMMY! will ask you a few questions
• if you type cake yammy all YAMMY! will convert all DB tables of the DB using your default connection settings
• if you type cake yammy tables table1 table2 table3 etc YAMMY! will check if those table exists and then convert just those table (i.e yammy users comments posts)

Don't worry, your DB tables will stay untouched, what YAMMY! does is simply to write their structure in a YAML format into a file in app/migrations.

YAMMY! file naming

The names of the files created by YAMMY! are authomagically called as the migrations shell expects, and therefore with progressive numbering.

If you run YAMMY! for the first time, and you ask it to write down the schema for the users table, YAMMY! will create a file called 001_users.yml.

If you then convert the comments table, YAMMY! will create a file called 002_comments.yml. Namely the file names created by YAMMY! use the following convention: progressiveNumber_tableName.yml.

And what about table data?

Yep! Be carefull, YAMMY! just burns down your table but not your table data (it will be an addition for version 2.0) .

Nevertheless you can always open and edit the .yml files generated by YAMMY! and add your custom INSERT, UPDATE or whatever queries.

Let's have a look at one example:

Lets convert the user table with YAMMY.

A 001_users.yml file is generated by YAMMY! with the following inside according to my users table schema:

#
# migration YAML file
#
---
UP: 
  create_table: 
    users: 
      name: 
        type: string
        default: false
        length: 100
        - not_null
      mail: 
        type: string
        default: false
        length: 50
        - not_null
      username: 
        type: string
        default: false
        length: 30
        - not_null
      - no_dates
DOWN: 
  drop_table: 
    - users

Now I wanna insert some data with a custom query like:

INSERT INTO `users` ( `id` , `name` , `mail` `username`)
VALUES (NULL , 'Daniel', 'me@me.com', 'cakeFreak');

I then open my 001_users.yml file and I modify it as follows:

#
# migration YAML file
#
---
UP: 
  create_table: 
    users: 
      name: 
        type: string
        default: false
        length: 100
        - not_null
      mail: 
        type: string
        default: false
        length: 50
        - not_null
      username: 
        type: string
        default: false
        length: 30
        - not_null
      - no_dates 
    
  query:
    - INSERT INTO users(id, name, mail, username) VALUES (NULL , 'Daniel', 'me@me.com', 'cakeFreak');
      
DOWN: 
  drop_table: 
    - users

I can then insert as many queries I want to manipulate my data or tables.

How can I use YAMMY! and migrations on virtual/dedicated server?!?

Well, set the right PATH to cake (a bit as described in the screencasts above) and proceed as I explained pointing your shell to the app/ directory.

How can I use YAMMY! and migrations on a shared server?!?

If you deploy your application on a shared hosting where you can't set the right PATH to cake, you better take a look at the workaround presented by John Reeves: the Shells Plugin.

YAMMY! benefits

What the benefits of using migrations and YAMMY! for your development cycle?!?

Well they help you to keep your development tidy and to speed up the all process.

If you then use a tool like Capistrano (read this post by Chris Hartjes) you can not only deploy your application faster but even run migrations remotely.

I hope that you will find YAMMY! usefull and that you will have more time to sunbath on the beach using it along with migrations!

Happy baking!

Daniel Vecchiato

Further resources:

• Automated PHP Deployment With Capistrano
• Capistrano + CakePHP deployment recipe
• Migrations in Ruby on Rails
• CakePHP Bakery

view/hide comments | add comment