DBIx::Class::Migration::Tutorial - How to use DBIx::Class::Migration


This is a tutorial for the database migration and fixture generation tools described at the usage / api level at DBIx::Class::Migration::Script and DBIx::Class::Migration. Although reviewing those docs would be helpful, I would not consider it required for the tutorial. However, I would expect you are familiar with DBIx::Class and that you are aware of the dependent projects DBIx::Class::DeploymentHandler and DBIx::Class::Fixtures. Having some knowledge of SQL::Translator would also be valuable.

I also assume you are familiar with the general problems of creating database migrations, such as generating DDL diff files, etc. This of course assumes you have good working knowledge of DDL and SQL, as well as some general understanding of database administration.

If you are new to DBIx::Class I really recommend you perform that tutorial first, and review its documentation.

This tutorial identifies the problem we are trying to solve, walks though increasingly complicated examples using these tools, and offers some advice as to the limit of the tool's value. We will also give some examples of how to make your migrations play well with common web application development frameworks such as Catalyst and how to use them with testing tools such as Test::DBIx::Class

By the completion of the tutorial I would expect you to understand how to prepare and install migrations, create custom deployment steps (and modify the stubs created during the prepare phase) as well as perform standard development workflows for testing and roundtripping a database.

All code mentioned can be found the /examples/MusicBase directory contained in the distribution installation files. Additionally, we will use as a starting point a database as similar as possible to the one described in DBIx::Class::Manual::Example so that if you are still new to DBIx::Class you can review those docs and think of this tutorial as a natural progression in learning.


Dealing with change in your database can be a vexing problem. You need the ability to manage database versions (how your database changes over time). You need to be able to upgrade seamlessly from one version to another. You need to be able to manage database and system data, and how they change over time. Additionally you may need to be able to create subsets of data for testing, and the ability to reset the database to a given state at any time.

There are a lot of frameworks that claim to make this easy. Generally this is partially achieved by limiting the scope of changes allowed, and reducing your ability to take maximum advantage of your database features. I'm not going to make that claim, since DBIx::Class::Migration is part of the DBIx::Class software ecosystem, and since that is an ORM that maximized your ability to be flexible and model databases using best practices, we desire to follow that ethos. What I will try to claim is that we can make solving the problem of database change possible, standard, and managed. This should reduce your stress, enable you to be more productive and not fear the need to change your tables.

DBIx::Class::Migration is built on top of DBIx::Class::DeploymentHandler, which is a tool to create deployment files of full databases and database diffs and also DBIx::Class::Fixtures, which is a tool for serializing and restoring sets of information. You need to solve both problems in an synchronized manner if you want to escape the fear of change.


The following definitions are used to assist clarity of understand and are in scope for the remainder of the tutorial


An instance of a subclass of DBIx::Class::Schema


a database such as SQLite or MySQL, that is running and available to accept commands.

database sandbox

An automatically generated, developer controlled installation of your database. This is suitable for development, but not for a higher environment.


An integer which represents a snapshot of a schema or database that is frozen for use. Versions increment positively (1,2,...) and can differ between your schema and your database.

fixture configuration

DBIx::Class::Fixtures defined rule for serializing a subset of information from a database. Is linked to a version and produces "fixtures"


Subsets of information from your database, linked to a version, in the form of individual files.


SQL and Perl files associated with a given version, or an upgrade or downgrade between versions.


fixture configurations, fixtures and deployment files for a given version, and how to upgrade or downgrade to that version.


Here's the next steps in the tutorial. It goes without saying that you should have a good working installation of Perl, and a dedicated local::lib. Please see App::perlbrew for help setting up such a perl installation.

I also assume you have SQLite installed and parts of the advanced tutorial will assume you have MySQL available. Please see MySQL::Sandbox for some help in getting a development instance of MySQL running.

STEP 1: Setup Project Files

DBIx::Class::Migration::Tutorial::Setup shows you how to bootstrap a very basic DBIx::Class driven application.

STEP 2: First Migration, using dbic-migration and fixtures.

DBIx::Class::Migration::Tutorial::FirstMigration takes the basic application and prepare some migrations.

STEP 3: Creating upgrades and modify the database

DBIx::Class::Migration::Tutorial::SecondMigration Shows you how to start handling database change by creating a version 2 of the schema. We also create more complex fixtures and customize the migration.

STEP 4: Testing

DBIx::Class::Migration::Tutorial::Testing shows you how to write some simple test cases for your database.

STEP 5: Third Migration

DBIx::Class::Migration::Tutorial::ThirdMigration explores a more complicated migration and also reviews what to do if you need to run through a few iterations of a migration before you are ready to set it in stone.

STEP 6: Migrations for Additional Databases

DBIx::Class::Migration::Tutorial::AddMySQL. So far we've been building migrations for just one database: SQLite. Let's build migrations for MySQL

STEP 7: Using migrations with Catalyst

DBIx::Class::Migration::Tutorial::Catalyst shows you how to use and customize DBIx::Class::Migration with Catalyst for development and testing.

STEP 8: Conclusion

DBIx::Class::Migration::Tutorial::Conclusion reviews some key concepts.


DBIx::Class::Migration, DBIx::Class::Manual::Example, DBIx::Class::DeploymentHandler, and DBIx::Class::Fixtures.


See DBIx::Class::Migration for author information


See DBIx::Class::Migration for copyright and license information