Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DBIx::Class::MigrationUsertContributed PerlDBIx::Class::Migration::Tutorial(3)

       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

       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

       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

       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

       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

   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

   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

   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

perl v5.32.1			  2019-03-2DBIx::Class::Migration::Tutorial(3)


Want to link to this manual page? Use this URL:

home | help