Catalyst Advent - Day 13 - DBIx::Class as Catalyst Model

NOTE: This article was written in 2005. Make sure to check the Catalyst Wiki ( for updated information.

Our Database

This text will show you how to start using DBIx::Class as your model within Catalyst. Let's assume, we have a relational set of tables:

  shell> sqlite3 myapp.db
  SQLite version 3.2.1
  Enter ".help" for instructions
  sqlite> CREATE TABLE person (
     ...>     name     VARCHAR(100)
     ...> );
  sqlite> CREATE TABLE address (
     ...>     person   INTEGER REFERENCES person
     ...>     address  TEXT,
     ...> );
  sqlite> .q

which we want to access from our MyApp Catalyst application.

Setting up the models

We will cover the more convenient way to start with, and let our models be set up automatically. If you want to define your models and their relations manually, have a look at Catalyst::Model::DBIC::Plain. We'll concentrate on Catalyst::Model::DBIC.

We let a helper do most of the work for us:

  shell> script/ model DBIC DBIC \
   exists "/path/MyApp/script/../lib/MyApp/Model"
   exists "/path/MyApp/script/../t"
  created "/path/MyApp/Model/"
  created "/path/MyApp/Model/DBIC"
  created "/path/MyApp/Model/DBIC/"
  created "/path/MyApp/Model/DBIC/"
  created "/path/MyApp/Model/DBIC/"
   exists "/path/MyApp/script/../t"
  created "/path/MyApp/script/../t/model_DBIC-Address.t"
   exists "/path/MyApp/script/../t"
  created "/path/MyApp/script/../t/model_DBIC-Person.t"
   exists "/path/MyApp/script/../t"
  created "/path/MyApp/script/../t/model_DBIC-SqliteSequence.t"

The base class that does the setting-up part of the job is set up as well as stub files of our modules to extend and the testing environment.

Table and Relationship Autodetection

If you start your Cat Application up, you can see the loaded tables and model components in your debug output:

  shell> script/
  [Tue Dec 13 01:20:59 2005] [catalyst] [debug] Loaded 
  tables "address person sqlite_sequence"
  | Class                              | Type     |
  | MyApp::Model::DBIC                 | instance |
  | MyApp::Model::DBIC::Address        | class    |
  | MyApp::Model::DBIC::Person         | class    |
  | MyApp::Model::DBIC::SqliteSequence | class    |
  | MyApp::Model::DBIC::_db            | class    |

And your models are ready to use! If you change the database schema, your models will also change at startup. However, Catalyst will not touch your stub model files.

Using the Models

You can create new objects:

  my $person = $c->model( 'DBIC::Person' )->create({
      name => 'Jon Doe',

Or add related objects:

  my $adress = $person->add_to_addresses({
      address => 'We wish we knew.',

Search and retrieve from the database:

  my $person = $c->model( 'DBIC::Person' )->find(1);
  my $address_iterator = $c->model( 'DBIC::Address' )
    ->search( { address => { like => '%Tokyo%' } } );

More Information

You can find the documentation of Catalyst::Model::DBIC and its helper at

For information concerning DBIx::Class please visit the documentation and Intro on CPAN:

or its own Wiki

and of course, you can find support on and