DBIx::C...utorial(3)

🌸 NAME 🌸

Hey bestie, this is DBIx::Class::Migration::Tutorial — the user-contributed Perl doc that teaches you How to use DBIx::Class::Migration. The header abbreviates it as DBIx::C...utorial(3) on both sides, if you were wondering about the funky ellipsis. 💅

✨ SYNOPSIS ✨

Okay so this is the tutorial for the database migration and fixture-generation tools whose usage/API-level docs live in DBIx::Class::Migration::Script and DBIx::Class::Migration. Reading those first is helpful but not required, bestie. You should, however, be familiar with DBIx::Class, and aware of the dependent projects DBIx::Class::DeploymentHandler and DBIx::Class::Fixtures. Some knowledge of SQL::Translator would also be valuable.

I'm also assuming you know the general problems around creating database migrations — stuff like generating DDL diff files, etc. That obviously assumes a good working knowledge of DDL and SQL, plus some general understanding of database administration.

If DBIx::Class is new to you, I really recommend doing that tutorial first and reviewing its documentation. For real.

This tutorial names the problem we're solving, walks through increasingly complicated examples using these tools, and gives some advice about the limit of the tool's value. We also include examples of making your migrations play nicely with common web application development frameworks like Catalyst, and how to use them with testing tools like Test::DBIx::Class.

By the end, I'd expect you to understand how to prepare and install migrations, create custom deployment steps (and modify the stubs created during the prepare phase), and perform standard development workflows for testing and roundtripping a database. 🫶

All code mentioned can be found in the "/examples/MusicBase" directory contained in the distribution installation files. Also, we'll use as a starting point a database as similar as possible to the one described in DBIx::Class::Manual::Example, so if you're 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. Periodt. You need to manage database versions (how your database changes over time). You need to upgrade seamlessly from one version to another. You need to manage database and system data, and how they change over time. You may also need to create subsets of data for testing, and the ability to reset the database to a given state at any time.

Lots of frameworks claim to make this easy. Usually that's 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, because DBIx::Class::Migration is part of the DBIx::Class software ecosystem, and since that's an ORM that maximized your ability to be flexible and model databases using best practices, we want 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. That should reduce your stress, enable you to be more productive, and keep you from fearing the need to change your tables. 💖

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

🌸 DEFINITIONS 🌸

The following definitions help keep things clear and are in scope for the rest 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 that 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

A rule defined by DBIx::Class::Fixtures for serializing a subset of information from a database. It's 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 what's next 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 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 prepares 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're 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 💜

Go peek at 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.

Okay bye bestie 💖 — this page comes from perl v5.42.0, dated 2020-06-03, and the footer labels it DBIx::C...utorial(3); mwah 💋.