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

FreeBSD Manual Pages


home | help

       DBIx::Class::Migration::Tutorial::Catalyst - Using a web	framework

       By the end of this section, you will learn some strategies for using
       migrations with web development and for testing.

       This is not a Catalyst tutorial.	 You should be familar with the
       Catalyst	web development	framework, and have read the Catalyst::Manual.
       Although	we will	build a	minimal	Catalyst application we	are focused on
       database	integration as well as exploring some strategies for testing
       and would not consider this application to represent overall best

       Reviewing the documentation for Catalyst::Test would be valuable, as
       well as Catalyst::Plugin::ConfigLoader for a refresher on the idea of
       localized and enviroment	specific configurations.

Bootstrap a basic Catalyst application
       Update you "dist.ini" file:

	   name	   = DBIx-Class-Migration
	   author  = John Napiorkowski <>
	   license = Perl_5
	   copyright_holder = John Napiorkowski
	   copyright_year   = 2012
	   abstract = Tutorial Application for DBIx-Class-Migration

	   version = 0.001

	   Moose = 0
	   MooseX::MethodAttributes = 0
	   DBIx::Class = 0
	   DBIx::Class::Migration = 0
	   Catalyst = 0
	   Catalyst::Devel = 0
	   Catalyst::Plugin::ConfigLoader = 0
	   Catalyst::Model::DBIC::Schema = 0
	   Catalyst::Action::RenderView	= 0
	   Catalyst::View::TT =	0
	   Plack = 0

	   [Prereqs / TestRequires]
	   Test::DBIx::Class = 0
	   Test::Most =	0

       You should see we've added two dependencies related to Catalyst.	 Now
       install them with cpanm:

	   dzil	listdeps | cpanm

       Next, bootstrap a Catalyst application.	I know you can use the commandline tool, but for our simple	application let's just
       create a	few files manually:

	   touch app.psgi
	   touch lib/MusicBase/
	   mkdir lib/MusicBase/Web
	   mkdir lib/MusicBase/Web/Controller
	   mkdir lib/MusicBase/Web/Model
	   mkdir lib/MusicBase/Web/View
	   touch lib/MusicBase/Web/Controller/
	   touch lib/MusicBase/Web/Model/
	   touch lib/MusicBase/Web/View/
	   mkdir share/etc
	   touch share/etc/
	   mkdir share/html
	   touch share/html/

       If you prefer to	use a helper, you can also try
       <> it
       generates part of the files creates but is closer to	the
       normal Dist::Zilla stuff.

       Now open	"lib/MusicBase/" and change it to	look like this:

	   package MusicBase::Web;

	   use Moose;
	   use Catalyst	qw/

	   extends 'Catalyst';

	   our $VERSION	= '0.01';

	     'Plugin::ConfigLoader' => {
	       file => __PACKAGE__->path_to('share', 'etc'),


       This is a pretty	plain and straight Catalyst application	class.	The
       only thing I've done differently	from default is	I've placed our
       configuration files in "share/etc", rather than in the application root
       (the directory that contains your "dist.ini" file).  I think this is a
       bit more	forward	looking, and since we already have the "share"
       directory, why not use it?

       For your	Model, we'll use "Catalyst::Model::DBIC::Schema" to provide a
       bit of thin glue	between	you Catalyst web application and your


	   package MusicBase::Web::Model::Schema;

	   use Moose;
	   extends 'Catalyst::Model::DBIC::Schema';


       As is typical for Catalyst models, there's not a	lot going on here,
       just the	minimum	useful glue to make Catalyst aware of your Schema.

       Let's add the View now.	Open "lib/MusicBase/Web/View/" and

	   package MusicBase::Web::View::HTML;
	   use base  'Catalyst::View::TT';


       We'll need a bit	of configuration to finish the job of hooking the two
       together	so open	"share/etc/" in	your text editor and
       make it look like this:

	     name => 'MusicBase::Web',
	     default_view => 'HTML',
	     disable_component_resolution_regex_fallback => 1,
	     'Controller::Root'	=> {
	       namespace => '',
	     'Model::Schema' =>	{
	       traits => ['FromMigration'],
	       schema_class => 'MusicBase::Schema',
	       install_if_needed => {
		 default_fixture_sets => ['all_tables']},
	     'View::HTML' => {
	       INCLUDE_PATH => [ '__path_to(share,html)__' ],
	       TEMPLATE_EXTENSION => '.tt',

       I know many of the "Catalyst" examples use "Config::General" or YAML
       for configuration information.  I tend to use Perl configuration	files
       because of the extra flexibility.

       I'm setting a few things	here, but for our discussion the most
       important one is	the "Model::Schema" section, where I point our model
       to the SQLite database we've been using all along.  Since we just want
       Catalyst	to use our database sandbox, the easiest way to	do this	is to
       use the "FromMigration" trait, which you	get for	free when you install
       DBIx::Class::Migration.	You can	review the documentation at

       The configuration given would use the SQLite sandbox.  What if you
       wanted to switch	to using the MySQL sandbox instead?  The
       "Model::Schema" parameters would	look like so:

	   'Model::Schema' => {
	     traits => ['FromMigration'],
	     schema_class => 'MusicBase::Schema',
	     extra_migration_args => {
	       db_sandbox_class	=> 'DBIx::Class::Migration::MySQLSandbox'},
	     install_if_needed => {
	       default_fixture_sets => ['all_tables']},

       In any case, you	hopefully noticed that we also run some	setup code to
       install the database and	populate some fixtures,	if they	are missing.

       NOTE: If	you use	the "FromMigration" trait, we will automatically start
       and stop	the database if	needed (and you	are using a database like
       MySQL or	Postgresql that	needs starting and stopping).  This startup
       and teardown can	impact the startup time	of you application.

       NOTE: If	you already had	a database setup, and are not using the
       database	sandbox	feature	(as you	won't when in a	production server, or
       if you are using	some shared hosting setups, for	example) you should
       setup your "connect_info" as you	normally would in a Catalyst

       Let's setup a trivial controller	that pulls a few rows out of the
       database	and just outputs this to a web page.

	   package MusicBase::Web::Controller::Root;

	   use Moose;
	   use MooseX::MethodAttributes;

	   extends 'Catalyst::Controller';

	   sub index :Path :Args(0) {
	     my	($self,	$ctx) =	@_;
	     my	@artists = $ctx->model('Schema::Artist')
	       ->search({},{ result_class =>
		 'DBIx::Class::ResultClass::HashRefInflator' })

	     $ctx->stash(artists => \@artists);

	   sub end : ActionClass('RenderView') {}


       Here we want to just get	all the	Artists	and send them to our View.
       Since in	MVC it is considered correct to	inform a View of a Model in a
       Read Only manner	(in other words, your View should not be able to
       modify the Model) I generally use the
       DBIx::Class::ResultClass::HashRefInflator result	class which will
       flatten your results to an array	of hashrefs, rather than return	a list
       of result objects.  Besides making it impossible	for your template
       authors to accidentally modify the model, you get a nice	speed bump
       since inflating an array	of hashrefs is much faster than	creating all
       those result objects.

       Usually I create	a resultset method in my base resultset	class, and
       have all	my custom resultsets inherit from that.	 Something like:

	   package MusicBase::Schema::ResultSet;
	   use base 'DBIx::Class::ResultSet;

	   sub all_as_array {
	     shift->search({},{	result_class =>
		 'DBIx::Class::ResultClass::HashRefInflator' })

	   sub all_as_arrayref { [shift->all_as_array] }

       I would have "MusicBase::Schema::ResultSet::Artist" inherit from
       "MusicBase::Schema::ResultSet" instead of DBIx::Class::ResultSet	as it
       does now.  Then I could have written:

	   sub index :Path :Args(0) {
	     my	($self,	$ctx) =	@_;
	     $ctx->stash( artists =>
	       $ctx->model('Schema::Artist')->all_as_arrayref );

       This is a common	enough pattern for me that it is worth the trouble to
       create the base class.  Additionally, if	you have lots of DBIx::Class
       components to load it helps to create a central base class, since that
       speeds things up	at load	time.

       And here's the template for the webpage:	"share/html/"

	       <link rel="stylesheet"
		 type="text/css" rel="Stylesheet">
	     <body class="container">
	       <h1>Artist List</h1>
	       [% FOR artist IN	artists	%]
		 <p>[% %]</p>
	       [% END %]

       We'll use Twitter's Bootstrap CSS to make things	look neat. Lastly you
       need to edit "app.psgi" as follows:

	   use MusicBase::Web;

       So now we can start our Catalyst	application!

	   plackup -Ilib

Integrating DBIx::Class::Migration and Catalyst.
       There's two main	places to where	Catalyst and DBIx::Class::Migration
       can cooperate: Running migrations and Running Tests.

   Running Migrations
       Although	you can	just use dbic-migration	directly with you Catalyst
       application, since Catalyst already does	a great	job of managing
       configuration, let's learn how to subclass
       DBIx::Class::Migration::Script and customize it for your	application.
       That way	you don't need to set "ENV" or pass option flags to the
       "dbic-migration"	commandline tool (and easily make a mistake and
       upgrade the wrong database :) ).

	   touch lib/MusicBase/Schema/

       And then	open "lib/MusicBase/Schema/" in your editor
       and change it to	look like this:

	   package MusicBase::Schema::MigrationScript;

	   use Moose;
	   use MusicBase::Web;

	   extends 'DBIx::Class::Migration::Script';

	   sub defaults	{
	     schema => MusicBase::Web->model('Schema')->schema,


       Basically you've	made a subclass	of DBIx::Class::Migration::Script but
       you are setting the "schema" to always be whatever Catalyst thinks it
       is.  Now	you can	use Catalysts built in configuration management	to
       decide what database you	are running migrations on.  For	example	you
       can run this straight out (remember to remove the ENV var
       DBIC_MIGRATION_SCHEMA_CLASS, if you have	it set now for running the

	   $ perl -Ilib	lib/MusicBase/Schema/	status
	   Schema is 3
	   Deployed database is	3

       And you can reset the data from fixtures, dump new ones,	etc.  Plus, if
       you created an enviroment specific configuration	(such as if you	have a
       file "share/etc/" that points	to your	QA datase) you
       can leverage you	Catalyst based configuration to	make your life a bit
       easier.	For example:

	     lib/MusicBase/Schema/ status

       Would grab the connected	schema for your	qa enviroment specific
       configuration and give you the status on	that (assuming you can ping it
       from your logged	in terminal).  This integration	is very	useful since
       you can use whatever your Catalyst application thinks is	the current
       database	as the target of the migration.	 You can use other bits	of
       configuration info as well, such	as a custom "target_dir" etc.

       Alternative: If subclasing DBIx::Class::Migration::Script seems like an
       overly heavy handed solution, or	running	the *.pm file like a script
       just weirds you out, you	can simply create a script like	the following,
       which would work	identically:

       For example, something in "script/my-dbic-migration"

	   #!/usr/bin/env perl

	   use MusicBase::Web;
	   use DBIx::Class::Migration::Script;

	       schema => MusicBase::Web->model('Schema')->schema);

       And then	use it like:

	   perl	-Ilib script/my-dbic-migration status

       NOTE: In	this case you need to invoke the perl interp with "-Ilib" so
       that we can find	"MusicBase::Web"

       If you have a bunch of files in "/script" or if you need	to be able to
       run your	custom migration tool after installation, this could be	a good

   Running Tests
       We've seen how using tools like Test::DBIx::Class together with
       DBIx::Class::Migration can really simplify your unit level testing
       effort.	Using them you don't need to spend a lot of time setting up
       dedicated testing databases and managing	configuration sets (that need
       to change over time).  However if you want to write tests that check
       your actual web pages (for example you want to test things like if a
       page shows the correct results and if web forms work) you need to
       manage that a bit differently.  Here's what I do:

       First, create a enviroment specific configuration for testing:

	   touch share/etc/

       Then open "share/etc/" and add the following:

	     'Model::Schema' =>	{
	       traits => ['FromMigration'],
	       schema_class => 'MusicBase::Schema',
	       extra_migration_args => {
		 db_sandbox_builder_class => 'DBIx::Class::Migration::TempDirSandboxBuilder',
		 db_sandbox_class => 'DBIx::Class::Migration::MySQLSandbox'},
	       install_if_needed => {
		 default_fixture_sets => ['all_tables']},

       So what is going	to happen here is if you start the application
       pointing	to this	configuration (with
       "CATALYST_CONFIG_LOCAL_SUFFIX"=test) when the application runs it will
       automatically create a clean new	database and populate it with the
       "all_tables" fixture set.  Just for fun,	we will	create a test instance
       of Mysql.  Please note this will	be a temporary sandbox,	and will be
       deleted when your Catalyst application exits.  It is not	the same as
       the MySQL sandbox we created in "share/musicbase-schema/*".

       This looks similar to the first configuration file we did, where	we use
       the "FromMigration" trait to hookup your	migration deployments.
       However,	instead	of running our tests on	the database sandbox in
       "/share"	(which you don't want to so since that's not going to be a
       reliable	and consistent database	for testing) we	use the	following bit:

	   db_sandbox_builder_class => 'DBIx::Class::Migration::TempDirSandboxBuilder',

       To instruct the sandbox builder to put the sandbox into a temporary
       directory instead of "/share".  What will happen	here is	that (similar
       to the way that we saw with Test::DBIx::Class) we build up a database
       from scratch, populate it with known fixtures, run tests, and then tear
       it down at the end.  This way you get clean and repeatable tests.  The
       downside	is that	the buildup / teardown can add time to the tests,
       athough you should be able to run your test cases in parallel (using
       "prove -j9 ...",	to run up to nine tests	at once) to offset this	issue.

       Let's write a test case:

	   touch t/web.t

       And open	"t/web.t" in your editor:

	   #!/usr/bin/env perl

	   use Test::Most;
	   use Catalyst::Test 'MusicBase::Web';

	   ok my $content  = get('/'),
	     'got some content';

	   like	$content, qr/Michael Jackson/,
	     'Found Michael Jackson';


       Finally run your	test:

	   CATALYST_CONFIG_LOCAL_SUFFIX=test prove -lvr	t/web.t

       You know	from when we did the original demo data	script that "Michael
       Jackson"	was one	of the artist, so we'd expect to find him in the
       <$content> from the Root	controller (since that's just a	list of	all
       the Artist names).  So you'd probably want a bit	more testing on	this
       page, but this should give you the idea.

       Since the above test builds and breaks down a full MySQL	sandbox, it
       might not run instantly,	just FYI.

       That's it for some ideas	on using migrations with a web development
       framework like Catalyst.	 If you	are using Catalyst you can take
       advantage of its	great configuration management tools to	make it	even
       easier to manage	your migrations.  You also now have some strategies
       for making it easy to test.

       Proceed to DBIx::Class::Migration::Tutorial::Conclusion

       See DBIx::Class::Migration for author information

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

perl v5.32.1			 DBIx::Class::Migration::Tutorial::Catalyst(3)

NAME | GOAL | Bootstrap a basic Catalyst application | Integrating DBIx::Class::Migration and Catalyst. | SUMMARY | NEXT STEPS | AUTHOR | COPYRIGHT & LICENSE

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

home | help