lib/DBIx/Class/Manual/Cookbook.pod

   1 =head1 NAME
   2
   3 DBIx::Class::Manual::Cookbook - Miscellaneous recipes
   4
   5 =head1 RECIPES
   6
   7 =head2 Complex searches
   8
   9 Sometimes you need to formulate a query using specific operators:
  10
  11   my @albums = MyApp::DB::Album->search({
  12     artist => { 'like', '%Lamb%' },
  13     title  => { 'like', '%Fear of Fours%' },
  14   });
  15
  16 This results in something like the following C<WHERE> clause:
  17
  18   WHERE artist LIKE '%Lamb%' AND title LIKE '%Fear of Fours%'
  19
  20 Other queries might require slightly more complex logic:
  21
  22   my @albums = MyApp::DB::Album->search({
  23     -or => [
  24       -and => [
  25         artist => { 'like', '%Smashing Pumpkins%' },
  26         title  => 'Siamese Dream',
  27       ],
  28       artist => 'Starchildren',
  29     ],
  30   });
  31
  32 This results in the following C<WHERE> clause:
  33
  34   WHERE ( artist LIKE '%Smashing Pumpkins%' AND title = 'Siamese Dream' )
  35     OR artist = 'Starchildren'
  36
  37 For more information on generating complex queries, see
  38 L<SQL::Abstract/WHERE CLAUSES>.
  39
  40 =head2 Disconnecting cleanly
  41
  42 If you find yourself quitting an app with Control-C a lot during
  43 development, you might like to put the following signal handler in
  44 your main database class to make sure it disconnects cleanly:
  45
  46   $SIG{INT} = sub {
  47     __PACKAGE__->storage->dbh->disconnect;
  48   };
  49
  50 =head2 Using joins and prefetch
  51
  52 See L<DBIx::Class::ResultSet/ATTRIBUTES>.
  53
  54 =head2 Transactions
  55
  56 As of version 0.04001, there is improved transaction support in
  57 L<DBIx::Class::Storage::DBI>.  Here is an example of the recommended
  58 way to use it:
  59
  60   my $genus = Genus->find(12);
  61   eval {
  62     MyDB->txn_begin;
  63     $genus->add_to_species({ name => 'troglodyte' });
  64     $genus->wings(2);
  65     $genus->update;
  66     cromulate($genus); # Can have a nested transation
  67     MyDB->txn_commit;
  68   };
  69   if ($@) {
  70     # Rollback might fail, too
  71     eval {
  72       MyDB->txn_rollback
  73     };
  74   }
  75
  76 Currently, a nested commit will do nothing and a nested rollback will
  77 die.  The code at each level must be sure to call rollback in the case
  78 of an error, to ensure that the rollback will propagate to the top
  79 level and be issued.  Support for savepoints and for true nested
  80 transactions (for databases that support them) will hopefully be added
  81 in the future.
  82
  83 =head2 Many-to-many relationships
  84
  85 This is not as easy as it could be, but it's possible.  Here's an
  86 example to illustrate:
  87
  88   # Set up inherited connection information
  89   package MyApp::DBIC;
  90   use base qw/DBIx::Class/;
  91
  92   __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/);
  93   __PACKAGE__->connection(...);
  94
  95   # Set up a class for the 'authors' table
  96   package MyApp::DBIC::Author;
  97   use base qw/MyApp::DBIC/;
  98
  99   __PACKAGE__->table('authors');
 100   __PACKAGE__->add_columns(qw/authID first_name last_name/);
 101   __PACKAGE__->set_primary_key(qw/authID/);
 102
 103   # Define relationship to the link table
 104   __PACKAGE__->has_many('b2a' => 'MyApp::DBIC::Book2Author', 'authID');
 105
 106   # Create the accessor for books from the Author class
 107   sub books {
 108     my ($self) = @_;
 109     return MyApp::DBIC::Book->search(
 110       { 'b2a.authID' => $self->authID }, # WHERE clause
 111       { join => 'b2a' } # join condition (part of search attrs)
 112       # 'b2a' refers to the relationship named earlier in the Author class.
 113       # 'b2a.authID' refers to the authID column of the b2a relationship,
 114       # which becomes accessible in the search by being joined.
 115     );
 116   }
 117
 118   # Define the link table class
 119   package MyApp::DBIC::Book2Author;
 120   use base qw/MyApp::DBIC/;
 121
 122   __PACKAGE__->table('book2author');
 123   __PACKAGE__->add_columns(qw/bookID authID/);
 124   __PACKAGE__->set_primary_key(qw/bookID authID/);
 125
 126   __PACKAGE__->belongs_to('authID' => 'MyApp::DBIC::Author');
 127   __PACKAGE__->belongs_to('bookID' => 'MyApp::DBIC::Book');
 128
 129   package MyApp::DBIC::Book;
 130   use base qw/MyApp::DBIC/;
 131
 132   __PACKAGE__->table('books');
 133   __PACKAGE__->add_columns(qw/bookID title edition isbn publisher year/);
 134   __PACKAGE__->set_primary_key(qw/bookID/);
 135
 136   __PACKAGE__->has_many('b2a' => 'MyApp::DBIC::Book2Author', 'bookID');
 137
 138
 139   # Returns an author record where the bookID field of the
 140   # book2author table equals the bookID of the books (using the
 141   # bookID relationship table)
 142   sub authors {
 143     my ($self) = @_;
 144     return MyApp::DBIC::Author->search(
 145       { 'b2a.bookID' => $self->bookID }, # WHERE clause
 146       { join => 'b2a' } # JOIN condition
 147     );
 148   }
 149
 150 =head2 Setting default values
 151
 152 It's as simple as overriding the C<new> method.  Note the use of
 153 C<next::method>.
 154
 155   sub new {
 156     my ( $class, $attrs ) = @_;
 157
 158     $attrs->{foo} = 'bar' unless defined $attrs->{foo};
 159
 160     $class->next::method($attrs);
 161   }
 162
 163 =head2 Stringification
 164
 165 Employ the standard stringification technique by using the C<overload>
 166 module.  Replace C<foo> with the column/method of your choice.
 167
 168   use overload '""' => 'foo', fallback => 1;
 169
 170 =cut