lib/DBIx/Class/Manual/Cookbook.pod

   1 =head1 NAME
   2
   3 DBIx::Class::Manual::Cookbook - Misc recipes
   4
   5 =head1 DESCRIPTION
   6
   7 Things that could be handy
   8
   9 =head1 RECIPES
  10
  11 =head2 Disconnecting cleanly
  12
  13 If you find yourself quitting an app with Control-C a lot during development,
  14 you might like to put the following signal handler in your main database
  15 class to make sure it disconnects cleanly:
  16
  17     $SIG{INT} = sub {
  18         __PACKAGE__->storage->dbh->disconnect;
  19     };
  20
  21 =head2 Using joins and prefetch
  22
  23 See L<DBIx::Class::ResultSet/Attributes>.
  24
  25 =head2 Transactions
  26
  27 As of version 0.04001, there is improved transaction support in
  28 L<DBIx::Class::Storage::DBI>. Here is an example of the recommended way to use it:
  29
  30     my $obj = Genus->find(12);
  31     eval {
  32         MyDB->txn_begin;
  33         $obj->add_to_species({ name => 'troglodyte' });
  34         $obj->wings(2);
  35         $obj->update;
  36         cromulate($obj); # can have a nested transation
  37         MyDB->txn_commit;
  38     };
  39     if ($@) { eval { MyDB->txn_rollback } } # rollback might fail, too
  40
  41 Currently, a nested commit will do nothing and a nested rollback will die.
  42 The code at each level must be sure to call rollback in the case of an error,
  43 to ensure that the rollback will propagate to the top level and be issued.
  44 Support for savepoints and for true nested transactions (for databases that
  45 support them) will hopefully be added in the future.
  46
  47 =head2 Many-to-many relationships
  48
  49 This is not as easy as it could be, but it's possible. Here's an example to
  50 illustrate:
  51
  52         # Set up inherited connection information
  53         package MyApp::DBIC;
  54         use base qw/DBIx::Class/;
  55
  56         __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/);
  57         __PACKAGE__->connection(...);
  58
  59         # Set up a class for the 'authors' table
  60         package MyApp::DBIC::Author;
  61         use base qw/MyApp::DBIC/;
  62
  63         __PACKAGE__->table('authors');
  64         __PACKAGE__->add_columns(qw/authID first_name last_name/);
  65         __PACKAGE__->set_primary_key(qw/authID/);
  66
  67         # Define relationship to the link table
  68         __PACKAGE__->has_many('b2a' => 'MyApp::DBIC::Book2Author', 'authID');
  69
  70         # Create the accessor for books from the ::Author class
  71         sub books {
  72           my ($self) = @_;
  73           return MyApp::DBIC::Book->search(
  74                 { 'b2a.authID' => $self->authID }, # WHERE clause
  75                 { join => 'b2a' } # join condition (part of search attrs)
  76             # 'b2a' refers to the relationship named earlier in the Author class.
  77                 # 'b2a.authID' refers to the authID column of the b2a relationship,
  78                 # which becomes accessible in the search by being joined.
  79           );
  80         }
  81
  82         # define the link table class
  83         package MyApp::DBIC::Book2Author;
  84         use base qw/MyApp::DBIC/;
  85
  86         __PACKAGE__->table('book2author');
  87         __PACKAGE__->add_columns(qw/bookID authID/);
  88         __PACKAGE__->set_primary_key(qw/bookID authID/);
  89
  90         __PACKAGE__->belongs_to('authID' => 'MyApp::DBIC::Author');
  91         __PACKAGE__->belongs_to('bookID' => 'MyApp::DBIC::Book');
  92
  93         package MyApp::DBIC::Book;
  94         use base qw/MyApp::DBIC/;
  95
  96         __PACKAGE__->table('books');
  97         __PACKAGE__->add_columns(qw/bookID title edition isbn publisher year/);
  98         __PACKAGE__->set_primary_key(qw/bookID/);
  99
 100         __PACKAGE__->has_many('b2a' => 'MyApp::DBIC::Book2Author', 'bookID');
 101
 102         sub authors {
 103          my ($self) = @_;
 104          return MyApp::DBIC::Author->search(
 105            { 'b2a.bookID' => $self->bookID }, # WHERE clause
 106            { join => 'b2a' }); # join condition (part of search attrs)
 107         }
 108
 109         # So the above search returns an author record where the bookID field of the
 110         # book2author table equals the bookID of the books (using the bookID
 111         # relationship table
 112
 113 =head2 Setting default values
 114
 115 It's as simple as overriding the C<new> method. Note the use of C<next::method>.
 116
 117     sub new {
 118         my( $class, $attrs ) = @_;
 119
 120         $attrs->{ foo } = 'bar' unless defined $attrs->{ foo };
 121
 122         $class->next::method( $attrs );
 123     }
 124
 125 =head2 Stringification
 126
 127 Deploy the standard stringification technique by using the C<overload> module. Replace
 128 C<foo> with the column/method of your choice.
 129
 130     use overload '""' => 'foo', fallback => 1;
 131
 132 =back