NOTE: This article was written in 2005. Make sure to check the Catalyst Wiki (http://dev.catalyst.perl.org/wiki) for updated information.

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 (
     ...>     id       INTEGER PRIMARY KEY AUTOINCREMENT,
     ...>     name     VARCHAR(100)
     ...> );
  sqlite> CREATE TABLE address (
     ...>     id       INTEGER PRIMARY KEY AUTOINCREMENT,
     ...>     person   INTEGER REFERENCES person
     ...>     address  TEXT,
     ...> );
  sqlite> .q

which we want to access from our MyApp Catalyst application.

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/myapp_create.pl model DBIC DBIC \
         dbi:SQLite:/path/to/myapp.db
   exists "/path/MyApp/script/../lib/MyApp/Model"
   exists "/path/MyApp/script/../t"
  created "/path/MyApp/Model/DBIC.pm"
  created "/path/MyApp/Model/DBIC"
  created "/path/MyApp/Model/DBIC/Address.pm"
  created "/path/MyApp/Model/DBIC/Person.pm"
  created "/path/MyApp/Model/DBIC/SqliteSequence.pm"
   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 DBIC.pm 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.

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

  shell> script/myapp_server.pl
  ...
  [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.

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%' } } );

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

https://metacpan.org/release/Catalyst-Model-DBIC

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

https://metacpan.org/release/DBIx-Class https://metacpan.org/release/DBIx-Classlib/DBIx/Class/Manual/Intro.pod

or its own Wiki

http://dbix-class.shadowcatsystems.co.uk/

and of course, you can find support on irc.perl.org#catalyst and irc.perl.org#dbix-class.

--phaylon