New DB2 Automagic primary key collecting
[dbsrgits/DBIx-Class.git] / 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