NAME
DBIx::Class::Migration::Tutorial - How to use DBIx::Class::Migration
SYNOPSIS
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.
INTRODUCTION
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.
DEFINITIONS
The following definitions are used to assist clarity of understand and are in scope for the remainder of the tutorial
schema
An instance of a subclass of DBIx::Class::Schema
database
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.
version
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"
fixtures
Subsets of information from your database, linked to a version, in the form of individual files.
migration
SQL and Perl files associated with a given version, or an upgrade or downgrade between versions.
deployment
fixture configurations, fixtures and deployment files for a given version, and how to upgrade or downgrade to that version.
NEXT STEPS: TABLE OF CONTENTS
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.
SEE ALSO
DBIx::Class::Migration, DBIx::Class::Manual::Example, DBIx::Class::DeploymentHandler, and DBIx::Class::Fixtures.
AUTHOR
See DBIx::Class::Migration for author information
COPYRIGHT & LICENSE
See DBIx::Class::Migration for copyright and license information