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

=head2 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 (
     ...>     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 C<MyApp> Catalyst application.

=head2 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 C<Catalyst::Model::DBIC::Plain>. We'll concentrate
on C<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 C<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.

=head2 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/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. 

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

=head2 More Information

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

L<http://search.cpan.org/dist/Catalyst-Model-DBIC/>

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

L<http://search.cpan.org/dist/DBIx-Class/>
L<http://search.cpan.org/dist/DBIx-Class/lib/DBIx/Class/Manual/Intro.pod>

or its own Wiki

L<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