* Replaced eq_bind() implementation to use Test::Deep::eq_deeply().
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Manual / Cookbook.pod
1 =head1 NAME 
2
3 DBIx::Class::Manual::Cookbook - Miscellaneous recipes
4
5 =head1 SEARCHING
6
7 =head2 Paged results
8
9 When you expect a large number of results, you can ask L<DBIx::Class> for a
10 paged resultset, which will fetch only a defined number of records at a time:
11
12   my $rs = $schema->resultset('Artist')->search(
13     undef,
14     {
15       page => 1,  # page to return (defaults to 1)
16       rows => 10, # number of results per page
17     },
18   );
19
20   return $rs->all(); # all records for page 1
21
22 The C<page> attribute does not have to be specified in your search:
23
24   my $rs = $schema->resultset('Artist')->search(
25     undef,
26     {
27       rows => 10,
28     }
29   );
30
31   return $rs->page(1); # DBIx::Class::ResultSet containing first 10 records
32
33 In either of the above cases, you can get a L<Data::Page> object for the
34 resultset (suitable for use in e.g. a template) using the C<pager> method:
35
36   return $rs->pager();
37
38 =head2 Complex WHERE clauses
39
40 Sometimes you need to formulate a query using specific operators:
41
42   my @albums = $schema->resultset('Album')->search({
43     artist => { 'like', '%Lamb%' },
44     title  => { 'like', '%Fear of Fours%' },
45   });
46
47 This results in something like the following C<WHERE> clause:
48
49   WHERE artist LIKE '%Lamb%' AND title LIKE '%Fear of Fours%'
50
51 Other queries might require slightly more complex logic:
52
53   my @albums = $schema->resultset('Album')->search({
54     -or => [
55       -and => [
56         artist => { 'like', '%Smashing Pumpkins%' },
57         title  => 'Siamese Dream',
58       ],
59       artist => 'Starchildren',
60     ],
61   });
62
63 This results in the following C<WHERE> clause:
64
65   WHERE ( artist LIKE '%Smashing Pumpkins%' AND title = 'Siamese Dream' )
66     OR artist = 'Starchildren'
67
68 For more information on generating complex queries, see
69 L<SQL::Abstract/WHERE CLAUSES>.
70
71 =head2 Retrieve one and only one row from a resultset
72
73 Sometimes you need only the first "top" row of a resultset. While this can be
74 easily done with L<< $rs->first|DBIx::Class::ResultSet/first >>, it is suboptimal,
75 as a full blown cursor for the resultset will be created and then immediately
76 destroyed after fetching the first row object. 
77 L<< $rs->single|DBIx::Class::ResultSet/single >> is
78 designed specifically for this case - it will grab the first returned result
79 without even instantiating a cursor. 
80
81 Before replacing all your calls to C<first()> with C<single()> please observe the 
82 following CAVEATS:
83
84 =over
85
86 =item *
87 While single() takes a search condition just like search() does, it does
88 _not_ accept search attributes. However one can always chain a single() to
89 a search():
90
91   my $top_cd = $cd_rs -> search({}, { order_by => 'rating' }) -> single;
92
93
94 =item *
95 Since single() is the engine behind find(), it is designed to fetch a
96 single row per database query. Thus a warning will be issued when the
97 underlying SELECT returns more than one row. Sometimes however this usage
98 is valid: i.e. we have an arbitrary number of cd's but only one of them is
99 at the top of the charts at any given time. If you know what you are doing,
100 you can silence the warning by explicitly limiting the resultset size:
101
102   my $top_cd = $cd_rs -> search ({}, { order_by => 'rating', rows => 1 }) -> single;
103
104 =back
105
106 =head2 Arbitrary SQL through a custom ResultSource
107
108 Sometimes you have to run arbitrary SQL because your query is too complex
109 (e.g. it contains Unions, Sub-Selects, Stored Procedures, etc.) or has to
110 be optimized for your database in a special way, but you still want to 
111 get the results as a L<DBIx::Class::ResultSet>. 
112 The recommended way to accomplish this is by defining a separate ResultSource 
113 for your query. You can then inject complete SQL statements using a scalar 
114 reference (this is a feature of L<SQL::Abstract>).
115
116 Say you want to run a complex custom query on your user data, here's what
117 you have to add to your User class:
118
119   package My::Schema::User;
120   
121   use base qw/DBIx::Class/;
122   
123   # ->load_components, ->table, ->add_columns, etc.
124
125   # Make a new ResultSource based on the User class
126   my $source = __PACKAGE__->result_source_instance();
127   my $new_source = $source->new( $source );
128   $new_source->source_name( 'UserFriendsComplex' );
129   
130   # Hand in your query as a scalar reference
131   # It will be added as a sub-select after FROM,
132   # so pay attention to the surrounding brackets!
133   $new_source->name( \<<SQL );
134   ( SELECT u.* FROM user u 
135   INNER JOIN user_friends f ON u.id = f.user_id 
136   WHERE f.friend_user_id = ?
137   UNION 
138   SELECT u.* FROM user u 
139   INNER JOIN user_friends f ON u.id = f.friend_user_id 
140   WHERE f.user_id = ? )
141   SQL 
142
143   # Finally, register your new ResultSource with your Schema
144   My::Schema->register_source( 'UserFriendsComplex' => $new_source );
145
146 Next, you can execute your complex query using bind parameters like this:
147
148   my $friends = [ $schema->resultset( 'UserFriendsComplex' )->search( {}, 
149     {
150       bind  => [ 12345, 12345 ]
151     }
152   ) ];
153   
154 ... and you'll get back a perfect L<DBIx::Class::ResultSet>.
155
156 =head2 Using specific columns
157
158 When you only want specific columns from a table, you can use
159 C<columns> to specify which ones you need. This is useful to avoid
160 loading columns with large amounts of data that you aren't about to
161 use anyway:
162
163   my $rs = $schema->resultset('Artist')->search(
164     undef,
165     {
166       columns => [qw/ name /]
167     }
168   );
169
170   # Equivalent SQL:
171   # SELECT artist.name FROM artist
172
173 This is a shortcut for C<select> and C<as>, see below. C<columns>
174 cannot be used together with C<select> and C<as>.
175
176 =head2 Using database functions or stored procedures
177
178 The combination of C<select> and C<as> can be used to return the result of a
179 database function or stored procedure as a column value. You use C<select> to
180 specify the source for your column value (e.g. a column name, function, or
181 stored procedure name). You then use C<as> to set the column name you will use
182 to access the returned value:
183
184   my $rs = $schema->resultset('Artist')->search(
185     {},
186     {
187       select => [ 'name', { LENGTH => 'name' } ],
188       as     => [qw/ name name_length /],
189     }
190   );
191
192   # Equivalent SQL:
193   # SELECT name name, LENGTH( name )
194   # FROM artist
195
196 Note that the C< as > attribute has absolutely nothing to with the sql
197 syntax C< SELECT foo AS bar > (see the documentation in
198 L<DBIx::Class::ResultSet/ATTRIBUTES>).  If your alias exists as a
199 column in your base class (i.e. it was added with C<add_columns>), you
200 just access it as normal. Our C<Artist> class has a C<name> column, so
201 we just use the C<name> accessor:
202
203   my $artist = $rs->first();
204   my $name = $artist->name();
205
206 If on the other hand the alias does not correspond to an existing column, you
207 have to fetch the value using the C<get_column> accessor:
208
209   my $name_length = $artist->get_column('name_length');
210
211 If you don't like using C<get_column>, you can always create an accessor for
212 any of your aliases using either of these:
213
214   # Define accessor manually:
215   sub name_length { shift->get_column('name_length'); }
216     
217   # Or use DBIx::Class::AccessorGroup:
218   __PACKAGE__->mk_group_accessors('column' => 'name_length');
219
220 =head2 SELECT DISTINCT with multiple columns
221
222   my $rs = $schema->resultset('Foo')->search(
223     {},
224     {
225       select => [
226         { distinct => [ $source->columns ] }
227       ],
228       as => [ $source->columns ] # remember 'as' is not the same as SQL AS :-)
229     }
230   );
231
232 =head2 SELECT COUNT(DISTINCT colname)
233
234   my $rs = $schema->resultset('Foo')->search(
235     {},
236     {
237       select => [
238         { count => { distinct => 'colname' } }
239       ],
240       as => [ 'count' ]
241     }
242   );
243
244   my $count = $rs->next->get_column('count');
245
246 =head2 Grouping results
247
248 L<DBIx::Class> supports C<GROUP BY> as follows:
249
250   my $rs = $schema->resultset('Artist')->search(
251     {},
252     {
253       join     => [qw/ cds /],
254       select   => [ 'name', { count => 'cds.id' } ],
255       as       => [qw/ name cd_count /],
256       group_by => [qw/ name /]
257     }
258   );
259
260   # Equivalent SQL:
261   # SELECT name, COUNT( cd.id ) FROM artist
262   # LEFT JOIN cd ON artist.id = cd.artist
263   # GROUP BY name
264
265 Please see L<DBIx::Class::ResultSet/ATTRIBUTES> documentation if you
266 are in any way unsure about the use of the attributes above (C< join
267 >, C< select >, C< as > and C< group_by >).
268
269 =head2 Predefined searches
270
271 You can write your own L<DBIx::Class::ResultSet> class by inheriting from it
272 and define often used searches as methods:
273
274   package My::DBIC::ResultSet::CD;
275   use strict;
276   use warnings;
277   use base 'DBIx::Class::ResultSet';
278
279   sub search_cds_ordered {
280       my ($self) = @_;
281
282       return $self->search(
283           {},
284           { order_by => 'name DESC' },
285       );
286   }
287
288   1;
289
290 To use your resultset, first tell DBIx::Class to create an instance of it
291 for you, in your My::DBIC::Schema::CD class:
292
293   # class definition as normal
294   __PACKAGE__->load_components(qw/ Core /);
295   __PACKAGE__->table('cd');
296
297   # tell DBIC to use the custom ResultSet class
298   __PACKAGE__->resultset_class('My::DBIC::ResultSet::CD');
299
300 Note that C<resultset_class> must be called after C<load_components> and C<table>, or you will get errors about missing methods.
301
302 Then call your new method in your code:
303
304    my $ordered_cds = $schema->resultset('CD')->search_cds_ordered();
305
306 =head2 Using SQL functions on the left hand side of a comparison
307
308 Using SQL functions on the left hand side of a comparison is generally
309 not a good idea since it requires a scan of the entire table.  However,
310 it can be accomplished with C<DBIx::Class> when necessary.
311
312 If you do not have quoting on, simply include the function in your search
313 specification as you would any column:
314
315   $rs->search({ 'YEAR(date_of_birth)' => 1979 });
316
317 With quoting on, or for a more portable solution, use the C<where>
318 attribute:
319
320   $rs->search({}, { where => \'YEAR(date_of_birth) = 1979' });
321
322 =begin hidden
323
324 (When the bind args ordering bug is fixed, this technique will be better
325 and can replace the one above.)
326
327 With quoting on, or for a more portable solution, use the C<where> and
328 C<bind> attributes:
329
330   $rs->search({}, {
331       where => \'YEAR(date_of_birth) = ?',
332       bind  => [ 1979 ]
333   });
334
335 =end hidden
336
337 =head1 JOINS AND PREFETCHING
338
339 =head2 Using joins and prefetch
340
341 You can use the C<join> attribute to allow searching on, or sorting your
342 results by, one or more columns in a related table. To return all CDs matching
343 a particular artist name:
344
345   my $rs = $schema->resultset('CD')->search(
346     {
347       'artist.name' => 'Bob Marley'    
348     },
349     {
350       join => 'artist', # join the artist table
351     }
352   );
353
354   # Equivalent SQL:
355   # SELECT cd.* FROM cd
356   # JOIN artist ON cd.artist = artist.id
357   # WHERE artist.name = 'Bob Marley'
358
359 If required, you can now sort on any column in the related tables by including
360 it in your C<order_by> attribute:
361
362   my $rs = $schema->resultset('CD')->search(
363     {
364       'artist.name' => 'Bob Marley'
365     },
366     {
367       join     => 'artist',
368       order_by => [qw/ artist.name /]
369     }
370   );
371
372   # Equivalent SQL:
373   # SELECT cd.* FROM cd
374   # JOIN artist ON cd.artist = artist.id
375   # WHERE artist.name = 'Bob Marley'
376   # ORDER BY artist.name
377
378 Note that the C<join> attribute should only be used when you need to search or
379 sort using columns in a related table. Joining related tables when you only
380 need columns from the main table will make performance worse!
381
382 Now let's say you want to display a list of CDs, each with the name of the
383 artist. The following will work fine:
384
385   while (my $cd = $rs->next) {
386     print "CD: " . $cd->title . ", Artist: " . $cd->artist->name;
387   }
388
389 There is a problem however. We have searched both the C<cd> and C<artist> tables
390 in our main query, but we have only returned data from the C<cd> table. To get
391 the artist name for any of the CD objects returned, L<DBIx::Class> will go back
392 to the database:
393
394   SELECT artist.* FROM artist WHERE artist.id = ?
395
396 A statement like the one above will run for each and every CD returned by our
397 main query. Five CDs, five extra queries. A hundred CDs, one hundred extra
398 queries!
399
400 Thankfully, L<DBIx::Class> has a C<prefetch> attribute to solve this problem.
401 This allows you to fetch results from related tables in advance:
402
403   my $rs = $schema->resultset('CD')->search(
404     {
405       'artist.name' => 'Bob Marley'
406     },
407     {
408       join     => 'artist',
409       order_by => [qw/ artist.name /],
410       prefetch => 'artist' # return artist data too!
411     }
412   );
413
414   # Equivalent SQL (note SELECT from both "cd" and "artist"):
415   # SELECT cd.*, artist.* FROM cd
416   # JOIN artist ON cd.artist = artist.id
417   # WHERE artist.name = 'Bob Marley'
418   # ORDER BY artist.name
419
420 The code to print the CD list remains the same:
421
422   while (my $cd = $rs->next) {
423     print "CD: " . $cd->title . ", Artist: " . $cd->artist->name;
424   }
425
426 L<DBIx::Class> has now prefetched all matching data from the C<artist> table,
427 so no additional SQL statements are executed. You now have a much more
428 efficient query.
429
430 Note that as of L<DBIx::Class> 0.05999_01, C<prefetch> I<can> be used with
431 C<has_many> relationships.
432
433 Also note that C<prefetch> should only be used when you know you will
434 definitely use data from a related table. Pre-fetching related tables when you
435 only need columns from the main table will make performance worse!
436
437 =head2 Multiple joins
438
439 In the examples above, the C<join> attribute was a scalar.  If you
440 pass an array reference instead, you can join to multiple tables.  In
441 this example, we want to limit the search further, using
442 C<LinerNotes>:
443
444   # Relationships defined elsewhere:
445   # CD->belongs_to('artist' => 'Artist');
446   # CD->has_one('liner_notes' => 'LinerNotes', 'cd');
447   my $rs = $schema->resultset('CD')->search(
448     {
449       'artist.name' => 'Bob Marley'
450       'liner_notes.notes' => { 'like', '%some text%' },
451     },
452     {
453       join     => [qw/ artist liner_notes /],
454       order_by => [qw/ artist.name /],
455     }
456   );
457
458   # Equivalent SQL:
459   # SELECT cd.*, artist.*, liner_notes.* FROM cd
460   # JOIN artist ON cd.artist = artist.id
461   # JOIN liner_notes ON cd.id = liner_notes.cd
462   # WHERE artist.name = 'Bob Marley'
463   # ORDER BY artist.name
464
465 =head2 Multi-step joins
466
467 Sometimes you want to join more than one relationship deep. In this example,
468 we want to find all C<Artist> objects who have C<CD>s whose C<LinerNotes>
469 contain a specific string:
470
471   # Relationships defined elsewhere:
472   # Artist->has_many('cds' => 'CD', 'artist');
473   # CD->has_one('liner_notes' => 'LinerNotes', 'cd');
474
475   my $rs = $schema->resultset('Artist')->search(
476     {
477       'liner_notes.notes' => { 'like', '%some text%' },
478     },
479     {
480       join => {
481         'cds' => 'liner_notes'
482       }
483     }
484   );
485
486   # Equivalent SQL:
487   # SELECT artist.* FROM artist
488   # LEFT JOIN cd ON artist.id = cd.artist
489   # LEFT JOIN liner_notes ON cd.id = liner_notes.cd
490   # WHERE liner_notes.notes LIKE '%some text%'
491
492 Joins can be nested to an arbitrary level. So if we decide later that we
493 want to reduce the number of Artists returned based on who wrote the liner
494 notes:
495
496   # Relationship defined elsewhere:
497   # LinerNotes->belongs_to('author' => 'Person');
498
499   my $rs = $schema->resultset('Artist')->search(
500     {
501       'liner_notes.notes' => { 'like', '%some text%' },
502       'author.name' => 'A. Writer'
503     },
504     {
505       join => {
506         'cds' => {
507           'liner_notes' => 'author'
508         }
509       }
510     }
511   );
512
513   # Equivalent SQL:
514   # SELECT artist.* FROM artist
515   # LEFT JOIN cd ON artist.id = cd.artist
516   # LEFT JOIN liner_notes ON cd.id = liner_notes.cd
517   # LEFT JOIN author ON author.id = liner_notes.author
518   # WHERE liner_notes.notes LIKE '%some text%'
519   # AND author.name = 'A. Writer'
520
521 =head2 Multi-step and multiple joins
522
523 With various combinations of array and hash references, you can join
524 tables in any combination you desire.  For example, to join Artist to
525 CD and Concert, and join CD to LinerNotes:
526
527   # Relationships defined elsewhere:
528   # Artist->has_many('concerts' => 'Concert', 'artist');
529
530   my $rs = $schema->resultset('Artist')->search(
531     { },
532     {
533       join => [
534         {
535           cds => 'liner_notes'
536         },
537         'concerts'
538       ],
539     }
540   );
541
542   # Equivalent SQL:
543   # SELECT artist.* FROM artist
544   # LEFT JOIN cd ON artist.id = cd.artist
545   # LEFT JOIN liner_notes ON cd.id = liner_notes.cd
546   # LEFT JOIN concert ON artist.id = concert.artist
547
548 =head2 Multi-step prefetch
549
550 From 0.04999_05 onwards, C<prefetch> can be nested more than one relationship
551 deep using the same syntax as a multi-step join:
552
553   my $rs = $schema->resultset('Tag')->search(
554     {},
555     {
556       prefetch => {
557         cd => 'artist'
558       }
559     }
560   );
561
562   # Equivalent SQL:
563   # SELECT tag.*, cd.*, artist.* FROM tag
564   # JOIN cd ON tag.cd = cd.id
565   # JOIN artist ON cd.artist = artist.id
566
567 Now accessing our C<cd> and C<artist> relationships does not need additional
568 SQL statements:
569
570   my $tag = $rs->first;
571   print $tag->cd->artist->name;
572
573 =head1 ROW-LEVEL OPERATIONS
574
575 =head2 Retrieving a row object's Schema
576
577 It is possible to get a Schema object from a row object like so:
578
579   my $schema = $cd->result_source->schema;
580   # use the schema as normal:
581   my $artist_rs = $schema->resultset('Artist'); 
582
583 This can be useful when you don't want to pass around a Schema object to every
584 method.
585
586 =head2 Getting the value of the primary key for the last database insert
587
588 AKA getting last_insert_id
589
590 If you are using PK::Auto (which is a core component as of 0.07), this is 
591 straightforward:
592
593   my $foo = $rs->create(\%blah);
594   # do more stuff
595   my $id = $foo->id; # foo->my_primary_key_field will also work.
596
597 If you are not using autoincrementing primary keys, this will probably
598 not work, but then you already know the value of the last primary key anyway.
599
600 =head2 Stringification
601
602 Employ the standard stringification technique by using the C<overload>
603 module.
604
605 To make an object stringify itself as a single column, use something
606 like this (replace C<foo> with the column/method of your choice):
607
608   use overload '""' => sub { shift->name}, fallback => 1;
609
610 For more complex stringification, you can use an anonymous subroutine:
611
612   use overload '""' => sub { $_[0]->name . ", " .
613                              $_[0]->address }, fallback => 1;
614
615 =head3 Stringification Example
616
617 Suppose we have two tables: C<Product> and C<Category>. The table
618 specifications are:
619
620   Product(id, Description, category)
621   Category(id, Description)
622
623 C<category> is a foreign key into the Category table.
624
625 If you have a Product object C<$obj> and write something like
626
627   print $obj->category
628
629 things will not work as expected.
630
631 To obtain, for example, the category description, you should add this
632 method to the class defining the Category table:
633
634   use overload "" => sub {
635       my $self = shift;
636
637       return $self->Description;
638   }, fallback => 1;
639
640 =head2 Want to know if find_or_create found or created a row?
641
642 Just use C<find_or_new> instead, then check C<in_storage>:
643
644   my $obj = $rs->find_or_new({ blah => 'blarg' });
645   unless ($obj->in_storage) {
646     $obj->insert;
647     # do whatever else you wanted if it was a new row
648   }
649
650 =head2 Dynamic Sub-classing DBIx::Class proxy classes 
651
652 AKA multi-class object inflation from one table
653  
654 L<DBIx::Class> classes are proxy classes, therefore some different
655 techniques need to be employed for more than basic subclassing.  In
656 this example we have a single user table that carries a boolean bit
657 for admin.  We would like like to give the admin users
658 objects(L<DBIx::Class::Row>) the same methods as a regular user but
659 also special admin only methods.  It doesn't make sense to create two
660 seperate proxy-class files for this.  We would be copying all the user
661 methods into the Admin class.  There is a cleaner way to accomplish
662 this.
663
664 Overriding the C<inflate_result> method within the User proxy-class
665 gives us the effect we want.  This method is called by
666 L<DBIx::Class::ResultSet> when inflating a result from storage.  So we
667 grab the object being returned, inspect the values we are looking for,
668 bless it if it's an admin object, and then return it.  See the example
669 below:
670  
671 B<Schema Definition> 
672  
673     package DB::Schema; 
674      
675     use base qw/DBIx::Class::Schema/; 
676  
677     __PACKAGE__->load_classes(qw/User/); 
678  
679  
680 B<Proxy-Class definitions> 
681  
682     package DB::Schema::User; 
683      
684     use strict; 
685     use warnings; 
686     use base qw/DBIx::Class/; 
687      
688     ### Defined what our admin class is for ensure_class_loaded 
689     my $admin_class = __PACKAGE__ . '::Admin'; 
690      
691     __PACKAGE__->load_components(qw/Core/); 
692      
693     __PACKAGE__->table('users'); 
694      
695     __PACKAGE__->add_columns(qw/user_id   email    password  
696                                 firstname lastname active 
697                                 admin/); 
698      
699     __PACKAGE__->set_primary_key('user_id'); 
700      
701     sub inflate_result { 
702         my $self = shift;  
703         my $ret = $self->next::method(@_); 
704         if( $ret->admin ) {### If this is an admin rebless for extra functions  
705             $self->ensure_class_loaded( $admin_class ); 
706             bless $ret, $admin_class; 
707         } 
708         return $ret; 
709     } 
710      
711     sub hello { 
712         print "I am a regular user.\n"; 
713         return ; 
714     } 
715      
716      
717     package DB::Schema::User::Admin; 
718      
719     use strict; 
720     use warnings; 
721     use base qw/DB::Schema::User/; 
722      
723     sub hello 
724     { 
725         print "I am an admin.\n"; 
726         return; 
727     } 
728      
729     sub do_admin_stuff 
730     { 
731         print "I am doing admin stuff\n"; 
732         return ; 
733     } 
734  
735 B<Test File> test.pl 
736  
737     use warnings; 
738     use strict; 
739     use DB::Schema; 
740      
741     my $user_data = { email    => 'someguy@place.com',  
742                       password => 'pass1',  
743                       admin    => 0 }; 
744                            
745     my $admin_data = { email    => 'someadmin@adminplace.com',  
746                        password => 'pass2',  
747                        admin    => 1 }; 
748                            
749     my $schema = DB::Schema->connection('dbi:Pg:dbname=test'); 
750      
751     $schema->resultset('User')->create( $user_data ); 
752     $schema->resultset('User')->create( $admin_data ); 
753      
754     ### Now we search for them 
755     my $user = $schema->resultset('User')->single( $user_data ); 
756     my $admin = $schema->resultset('User')->single( $admin_data ); 
757      
758     print ref $user, "\n"; 
759     print ref $admin, "\n"; 
760      
761     print $user->password , "\n"; # pass1 
762     print $admin->password , "\n";# pass2; inherited from User 
763     print $user->hello , "\n";# I am a regular user. 
764     print $admin->hello, "\n";# I am an admin. 
765  
766     ### The statement below will NOT print 
767     print "I can do admin stuff\n" if $user->can('do_admin_stuff'); 
768     ### The statement below will print 
769     print "I can do admin stuff\n" if $admin->can('do_admin_stuff'); 
770
771 =head2 Skip row object creation for faster results
772
773 DBIx::Class is not built for speed, it's built for convenience and
774 ease of use, but sometimes you just need to get the data, and skip the
775 fancy objects.
776   
777 To do this simply use L<DBIx::Class::ResultClass::HashRefInflator>.
778   
779  my $rs = $schema->resultset('CD');
780  
781  $rs->result_class('DBIx::Class::ResultClass::HashRefInflator');
782  
783  my $hash_ref = $rs->find(1);
784
785 Wasn't that easy?
786   
787 =head2 Get raw data for blindingly fast results
788
789 If the L<HashRefInflator|DBIx::Class::ResultClass::HashRefInflator> solution
790 above is not fast enough for you, you can use a DBIx::Class to return values
791 exactly as they come out of the data base with none of the convenience methods
792 wrapped round them.
793
794 This is used like so:-
795
796   my $cursor = $rs->cursor
797   while (my @vals = $cursor->next) {
798       # use $val[0..n] here
799   }
800
801 You will need to map the array offsets to particular columns (you can
802 use the I<select> attribute of C<search()> to force ordering).
803
804 =head1 RESULTSET OPERATIONS
805
806 =head2 Getting Schema from a ResultSet
807
808 To get the schema object from a result set, do the following:
809
810  $rs->result_source->schema
811
812 =head2 Getting Columns Of Data
813
814 AKA Aggregating Data
815
816 If you want to find the sum of a particular column there are several
817 ways, the obvious one is to use search:
818
819   my $rs = $schema->resultset('Items')->search(
820     {},
821     { 
822        select => [ { sum => 'Cost' } ],
823        as     => [ 'total_cost' ], # remember this 'as' is for DBIx::Class::ResultSet not SQL
824     }
825   );
826   my $tc = $rs->first->get_column('total_cost');
827
828 Or, you can use the L<DBIx::Class::ResultSetColumn>, which gets
829 returned when you ask the C<ResultSet> for a column using
830 C<get_column>:
831
832   my $cost = $schema->resultset('Items')->get_column('Cost');
833   my $tc = $cost->sum;
834
835 With this you can also do:
836
837   my $minvalue = $cost->min;
838   my $maxvalue = $cost->max;
839
840 Or just iterate through the values of this column only:
841
842   while ( my $c = $cost->next ) {
843     print $c;
844   }
845
846   foreach my $c ($cost->all) {
847     print $c;
848   }
849
850 C<ResultSetColumn> only has a limited number of built-in functions, if
851 you need one that it doesn't have, then you can use the C<func> method
852 instead:
853
854   my $avg = $cost->func('AVERAGE');
855
856 This will cause the following SQL statement to be run:
857
858   SELECT AVERAGE(Cost) FROM Items me
859
860 Which will of course only work if your database supports this function.
861 See L<DBIx::Class::ResultSetColumn> for more documentation.
862
863 =head2 Creating a result set from a set of rows
864
865 Sometimes you have a (set of) row objects that you want to put into a 
866 resultset without the need to hit the DB again. You can do that by using the
867 L<set_cache|DBIx::Class::Resultset/set_cache> method:
868
869  my @uploadable_groups;
870  while (my $group = $groups->next) {
871    if ($group->can_upload($self)) {
872      push @uploadable_groups, $group;
873    }
874  }
875  my $new_rs = $self->result_source->resultset;
876  $new_rs->set_cache(\@uploadable_groups);
877  return $new_rs;
878
879
880 =head1 USING RELATIONSHIPS
881
882 =head2 Create a new row in a related table
883
884   my $author = $book->create_related('author', { name => 'Fred'});
885
886 =head2 Search in a related table
887
888 Only searches for books named 'Titanic' by the author in $author.
889
890   my $books_rs = $author->search_related('books', { name => 'Titanic' });
891
892 =head2 Delete data in a related table
893
894 Deletes only the book named Titanic by the author in $author.
895
896   $author->delete_related('books', { name => 'Titanic' });
897
898 =head2 Ordering a relationship result set
899
900 If you always want a relation to be ordered, you can specify this when you 
901 create the relationship.
902
903 To order C<< $book->pages >> by descending page_number, create the relation
904 as follows:
905
906   __PACKAGE__->has_many('pages' => 'Page', 'book', { order_by => \'page_number DESC'} );
907
908 =head2 Filtering a relationship result set
909
910 If you want to get a filtered result set, you can just add add to $attr as follows:
911
912  __PACKAGE__->has_many('pages' => 'Page', 'book', { where => { scrap => 0 } } );
913
914 =head2 Many-to-many relationships
915
916 This is straightforward using L<ManyToMany|DBIx::Class::Relationship/many_to_many>:
917
918   package My::User;
919   use base 'DBIx::Class';
920   __PACKAGE__->load_components('Core');
921   __PACKAGE__->table('user');
922   __PACKAGE__->add_columns(qw/id name/);
923   __PACKAGE__->set_primary_key('id');
924   __PACKAGE__->has_many('user_address' => 'My::UserAddress', 'user');
925   __PACKAGE__->many_to_many('addresses' => 'user_address', 'address');
926
927   package My::UserAddress;
928   use base 'DBIx::Class';
929   __PACKAGE__->load_components('Core');
930   __PACKAGE__->table('user_address');
931   __PACKAGE__->add_columns(qw/user address/);
932   __PACKAGE__->set_primary_key(qw/user address/);
933   __PACKAGE__->belongs_to('user' => 'My::User');
934   __PACKAGE__->belongs_to('address' => 'My::Address');
935
936   package My::Address;
937   use base 'DBIx::Class';
938   __PACKAGE__->load_components('Core');
939   __PACKAGE__->table('address');
940   __PACKAGE__->add_columns(qw/id street town area_code country/);
941   __PACKAGE__->set_primary_key('id');
942   __PACKAGE__->has_many('user_address' => 'My::UserAddress', 'address');
943   __PACKAGE__->many_to_many('users' => 'user_address', 'user');
944
945   $rs = $user->addresses(); # get all addresses for a user
946   $rs = $address->users(); # get all users for an address
947
948 =head1 TRANSACTIONS
949
950 As of version 0.04001, there is improved transaction support in
951 L<DBIx::Class::Storage> and L<DBIx::Class::Schema>.  Here is an
952 example of the recommended way to use it:
953
954   my $genus = $schema->resultset('Genus')->find(12);
955
956   my $coderef2 = sub {
957     $genus->extinct(1);
958     $genus->update;
959   };
960
961   my $coderef1 = sub {
962     $genus->add_to_species({ name => 'troglodyte' });
963     $genus->wings(2);
964     $genus->update;
965     $schema->txn_do($coderef2); # Can have a nested transaction. Only the outer will actualy commit
966     return $genus->species;
967   };
968
969   my $rs;
970   eval {
971     $rs = $schema->txn_do($coderef1);
972   };
973
974   if ($@) {                             # Transaction failed
975     die "the sky is falling!"           #
976       if ($@ =~ /Rollback failed/);     # Rollback failed
977
978     deal_with_failed_transaction();
979   }
980
981 Nested transactions will work as expected. That is, only the outermost
982 transaction will actually issue a commit to the $dbh, and a rollback
983 at any level of any transaction will cause the entire nested
984 transaction to fail. Support for savepoints and for true nested
985 transactions (for databases that support them) will hopefully be added
986 in the future.
987
988 =head1 SQL 
989
990 =head2 Creating Schemas From An Existing Database
991
992 L<DBIx::Class::Schema::Loader> will connect to a database and create a 
993 L<DBIx::Class::Schema> and associated sources by examining the database.
994
995 The recommend way of achieving this is to use the 
996 L<make_schema_at|DBIx::Class::Schema::Loader/make_schema_at> method:
997
998   perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib \
999     -e 'make_schema_at("My::Schema", { debug => 1 }, [ "dbi:Pg:dbname=foo","postgres" ])'
1000
1001 This will create a tree of files rooted at C<./lib/My/Schema/> containing
1002 source definitions for all the tables found in the C<foo> database.
1003
1004 =head2 Creating DDL SQL
1005
1006 The following functionality requires you to have L<SQL::Translator>
1007 (also known as "SQL Fairy") installed.
1008
1009 To create a set of database-specific .sql files for the above schema:
1010
1011  my $schema = My::Schema->connect($dsn);
1012  $schema->create_ddl_dir(['MySQL', 'SQLite', 'PostgreSQL'],
1013                         '0.1',
1014                         './dbscriptdir/'
1015                         );
1016
1017 By default this will create schema files in the current directory, for
1018 MySQL, SQLite and PostgreSQL, using the $VERSION from your Schema.pm.
1019
1020 To create a new database using the schema:
1021
1022  my $schema = My::Schema->connect($dsn);
1023  $schema->deploy({ add_drop_tables => 1});
1024
1025 To import created .sql files using the mysql client:
1026
1027   mysql -h "host" -D "database" -u "user" -p < My_Schema_1.0_MySQL.sql
1028
1029 To create C<ALTER TABLE> conversion scripts to update a database to a
1030 newer version of your schema at a later point, first set a new
1031 C<$VERSION> in your Schema file, then:
1032
1033  my $schema = My::Schema->connect($dsn);
1034  $schema->create_ddl_dir(['MySQL', 'SQLite', 'PostgreSQL'],
1035                          '0.2',
1036                          '/dbscriptdir/',
1037                          '0.1'
1038                          );
1039
1040 This will produce new database-specific .sql files for the new version
1041 of the schema, plus scripts to convert from version 0.1 to 0.2. This
1042 requires that the files for 0.1 as created above are available in the
1043 given directory to diff against.
1044
1045 =head2 Select from dual
1046
1047 Dummy tables are needed by some databases to allow calling functions
1048 or expressions that aren't based on table content, for examples of how
1049 this applies to various database types, see:
1050 L<http://troels.arvin.dk/db/rdbms/#other-dummy_table>.
1051
1052 Note: If you're using Oracles dual table don't B<ever> do anything
1053 other than a select, if you CRUD on your dual table you *will* break
1054 your database.
1055
1056 Make a table class as you would for any other table
1057                                                                                
1058   package MyAppDB::Dual;
1059   use strict;
1060   use warnings;
1061   use base 'DBIx::Class';
1062   __PACKAGE__->load_components("Core");
1063   __PACKAGE__->table("Dual");
1064   __PACKAGE__->add_columns(
1065     "dummy",
1066     { data_type => "VARCHAR2", is_nullable => 0, size => 1 },
1067   );
1068  
1069 Once you've loaded your table class select from it using C<select>
1070 and C<as> instead of C<columns>
1071  
1072   my $rs = $schema->resultset('Dual')->search(undef,
1073     { select => [ 'sydate' ],
1074       as     => [ 'now' ]
1075     },
1076   );
1077  
1078 All you have to do now is be careful how you access your resultset, the below
1079 will not work because there is no column called 'now' in the Dual table class
1080  
1081   while (my $dual = $rs->next) {
1082     print $dual->now."\n";
1083   }
1084   # Can't locate object method "now" via package "MyAppDB::Dual" at headshot.pl line 23.
1085  
1086 You could of course use 'dummy' in C<as> instead of 'now', or C<add_columns> to
1087 your Dual class for whatever you wanted to select from dual, but that's just
1088 silly, instead use C<get_column>
1089  
1090   while (my $dual = $rs->next) {
1091     print $dual->get_column('now')."\n";
1092   }
1093  
1094 Or use C<cursor>
1095  
1096   my $cursor = $rs->cursor;
1097   while (my @vals = $cursor->next) {
1098     print $vals[0]."\n";
1099   }
1100  
1101 Or use L<DBIx::Class::ResultClass::HashRefInflator>
1102  
1103   $rs->result_class('DBIx::Class::ResultClass::HashRefInflator');
1104   while ( my $dual = $rs->next ) {
1105     print $dual->{now}."\n";
1106   }
1107  
1108 Here are some example C<select> conditions to illustrate the different syntax
1109 you could use for doing stuff like 
1110 C<oracles.heavily(nested(functions_can('take', 'lots'), OF), 'args')>
1111  
1112   # get a sequence value
1113   select => [ 'A_SEQ.nextval' ],
1114  
1115   # get create table sql
1116   select => [ { 'dbms_metadata.get_ddl' => [ "'TABLE'", "'ARTIST'" ]} ],
1117  
1118   # get a random num between 0 and 100
1119   select => [ { "trunc" => [ { "dbms_random.value" => [0,100] } ]} ],
1120  
1121   # what year is it?
1122   select => [ { 'extract' => [ \'year from sysdate' ] } ],
1123  
1124   # do some math
1125   select => [ {'round' => [{'cos' => [ \'180 * 3.14159265359/180' ]}]}],
1126  
1127   # which day of the week were you born on?
1128   select => [{'to_char' => [{'to_date' => [ "'25-DEC-1980'", "'dd-mon-yyyy'" ]}, "'day'"]}],
1129  
1130   # select 16 rows from dual
1131   select   => [ "'hello'" ],
1132   as       => [ 'world' ],
1133   group_by => [ 'cube( 1, 2, 3, 4 )' ],
1134  
1135  
1136
1137 =head2 Adding Indexes And Functions To Your SQL
1138
1139 Often you will want indexes on columns on your table to speed up searching. To
1140 do this, create a method called C<sqlt_deploy_hook> in the relevant source 
1141 class:
1142
1143  package My::Schema::Artist;
1144
1145  __PACKAGE__->table('artist');
1146  __PACKAGE__->add_columns(id => { ... }, name => { ... })
1147
1148  sub sqlt_deploy_hook {
1149    my ($self, $sqlt_table) = @_;
1150
1151    $sqlt_table->add_index(name => 'idx_name', fields => ['name']);
1152  }
1153
1154  1;
1155
1156 Sometimes you might want to change the index depending on the type of the 
1157 database for which SQL is being generated:
1158
1159   my ($db_type = $sqlt_table->schema->translator->producer_type)
1160     =~ s/^SQL::Translator::Producer:://;
1161
1162 You can also add hooks to the schema level to stop certain tables being 
1163 created:
1164
1165  package My::Schema;
1166
1167  ...
1168
1169  sub sqlt_deploy_hook {
1170    my ($self, $sqlt_schema) = @_;
1171
1172    $sqlt_schema->drop_table('table_name');
1173  }
1174
1175 You could also add views or procedures to the output using 
1176 L<SQL::Translator::Schema/add_view> or 
1177 L<SQL::Translator::Schema/add_procedure>.
1178
1179 =head2 Schema versioning
1180
1181 The following example shows simplistically how you might use DBIx::Class to
1182 deploy versioned schemas to your customers. The basic process is as follows:
1183
1184 =over 4
1185
1186 =item 1.
1187
1188 Create a DBIx::Class schema
1189
1190 =item 2.
1191
1192 Save the schema
1193
1194 =item 3.
1195
1196 Deploy to customers
1197
1198 =item 4.
1199
1200 Modify schema to change functionality
1201
1202 =item 5.
1203
1204 Deploy update to customers
1205
1206 =back
1207
1208 B<Create a DBIx::Class schema>
1209
1210 This can either be done manually, or generated from an existing database as
1211 described under L</Creating Schemas From An Existing Database>
1212
1213 B<Save the schema>
1214
1215 Call L<DBIx::Class::Schema/create_ddl_dir> as above under L</Creating DDL SQL>.
1216
1217 B<Deploy to customers>
1218
1219 There are several ways you could deploy your schema. These are probably
1220 beyond the scope of this recipe, but might include:
1221
1222 =over 4
1223
1224 =item 1.
1225
1226 Require customer to apply manually using their RDBMS.
1227
1228 =item 2.
1229
1230 Package along with your app, making database dump/schema update/tests
1231 all part of your install.
1232
1233 =back
1234
1235 B<Modify the schema to change functionality>
1236
1237 As your application evolves, it may be necessary to modify your schema
1238 to change functionality. Once the changes are made to your schema in
1239 DBIx::Class, export the modified schema and the conversion scripts as
1240 in L</Creating DDL SQL>.
1241
1242 B<Deploy update to customers>
1243
1244 Add the L<DBIx::Class::Schema::Versioned> schema component to your
1245 Schema class. This will add a new table to your database called
1246 C<dbix_class_schema_vesion> which will keep track of which version is installed
1247 and warn if the user trys to run a newer schema version than the
1248 database thinks it has.
1249
1250 Alternatively, you can send the conversion sql scripts to your
1251 customers as above.
1252
1253 =head2 Setting quoting for the generated SQL. 
1254
1255 If the database contains column names with spaces and/or reserved words, they
1256 need to be quoted in the SQL queries. This is done using:
1257
1258  __PACKAGE__->storage->sql_maker->quote_char([ qw/[ ]/] );
1259  __PACKAGE__->storage->sql_maker->name_sep('.');
1260
1261 The first sets the quote characters. Either a pair of matching
1262 brackets, or a C<"> or C<'>:
1263   
1264  __PACKAGE__->storage->sql_maker->quote_char('"');
1265
1266 Check the documentation of your database for the correct quote
1267 characters to use. C<name_sep> needs to be set to allow the SQL
1268 generator to put the quotes the correct place.
1269
1270 In most cases you should set these as part of the arguments passed to 
1271 L<DBIx::Class::Schema/conect>:
1272
1273  my $schema = My::Schema->connect(
1274   'dbi:mysql:my_db',
1275   'db_user',
1276   'db_password',
1277   {
1278     quote_char => '"',
1279     name_sep   => '.'
1280   }
1281  )
1282
1283 =head2 Setting limit dialect for SQL::Abstract::Limit
1284
1285 In some cases, SQL::Abstract::Limit cannot determine the dialect of
1286 the remote SQL server by looking at the database handle. This is a
1287 common problem when using the DBD::JDBC, since the DBD-driver only
1288 know that in has a Java-driver available, not which JDBC driver the
1289 Java component has loaded.  This specifically sets the limit_dialect
1290 to Microsoft SQL-server (See more names in SQL::Abstract::Limit
1291 -documentation.
1292
1293   __PACKAGE__->storage->sql_maker->limit_dialect('mssql');
1294
1295 The JDBC bridge is one way of getting access to a MSSQL server from a platform
1296 that Microsoft doesn't deliver native client libraries for. (e.g. Linux)
1297
1298 The limit dialect can also be set at connect time by specifying a 
1299 C<limit_dialect> key in the final hash as shown above.
1300
1301 =head2 Working with PostgreSQL array types
1302
1303 If your SQL::Abstract version (>= 1.50) supports it, you can assign to
1304 PostgreSQL array values by passing array references in the C<\%columns>
1305 (C<\%vals>) hashref of the L<DBIx::Class::ResultSet/create> and
1306 L<DBIx::Class::Row/update> family of methods:
1307
1308   $resultset->create({
1309     numbers => [1, 2, 3]
1310   });
1311
1312   $row->update(
1313     {
1314       numbers => [1, 2, 3]
1315     },
1316     {
1317       day => '2008-11-24'
1318     }
1319   );
1320
1321 In conditions (eg. C<\%cond> in the L<DBIx::Class::ResultSet/search> family of
1322 methods) you cannot directly use array references (since this is interpreted as
1323 a list of values to be C<OR>ed), but you can use the following syntax to force
1324 passing them as bind values:
1325
1326   $resultset->search(
1327     {
1328       numbers => \[ '= ?', [1, 2, 3] ]
1329     }
1330   );
1331
1332 See L<SQL::Abstract/array_datatypes> and L<SQL::Abstract/Literal SQL with
1333 placeholders and bind values (subqueries)> for more explanation.
1334
1335 =head1 BOOTSTRAPPING/MIGRATING 
1336
1337 =head2 Easy migration from class-based to schema-based setup
1338
1339 You want to start using the schema-based approach to L<DBIx::Class>
1340 (see L<SchemaIntro.pod>), but have an established class-based setup with lots
1341 of existing classes that you don't want to move by hand. Try this nifty script
1342 instead:
1343
1344   use MyDB;
1345   use SQL::Translator;
1346   
1347   my $schema = MyDB->schema_instance;
1348   
1349   my $translator           =  SQL::Translator->new( 
1350       debug                => $debug          ||  0,
1351       trace                => $trace          ||  0,
1352       no_comments          => $no_comments    ||  0,
1353       show_warnings        => $show_warnings  ||  0,
1354       add_drop_table       => $add_drop_table ||  0,
1355       validate             => $validate       ||  0,
1356       parser_args          => {
1357          'DBIx::Schema'    => $schema,
1358                               },
1359       producer_args   => {
1360           'prefix'         => 'My::Schema',
1361                          },
1362   );
1363   
1364   $translator->parser('SQL::Translator::Parser::DBIx::Class');
1365   $translator->producer('SQL::Translator::Producer::DBIx::Class::File');
1366   
1367   my $output = $translator->translate(@args) or die
1368           "Error: " . $translator->error;
1369   
1370   print $output;
1371
1372 You could use L<Module::Find> to search for all subclasses in the MyDB::*
1373 namespace, which is currently left as an exercise for the reader.
1374
1375 =head1 OVERLOADING METHODS
1376
1377 L<DBIx::Class> uses the L<Class::C3> package, which provides for redispatch of
1378 method calls, useful for things like default values and triggers. You have to
1379 use calls to C<next::method> to overload methods. More information on using
1380 L<Class::C3> with L<DBIx::Class> can be found in
1381 L<DBIx::Class::Manual::Component>.
1382
1383 =head2 Setting default values for a row
1384
1385 It's as simple as overriding the C<new> method.  Note the use of
1386 C<next::method>.
1387
1388   sub new {
1389     my ( $class, $attrs ) = @_;
1390
1391     $attrs->{foo} = 'bar' unless defined $attrs->{foo};
1392
1393     my $new = $class->next::method($attrs);
1394
1395     return $new;
1396   }
1397
1398 For more information about C<next::method>, look in the L<Class::C3> 
1399 documentation. See also L<DBIx::Class::Manual::Component> for more
1400 ways to write your own base classes to do this.
1401
1402 People looking for ways to do "triggers" with DBIx::Class are probably
1403 just looking for this. 
1404
1405 =head2 Changing one field whenever another changes
1406
1407 For example, say that you have three columns, C<id>, C<number>, and 
1408 C<squared>.  You would like to make changes to C<number> and have
1409 C<squared> be automagically set to the value of C<number> squared.
1410 You can accomplish this by overriding C<store_column>:
1411
1412   sub store_column {
1413     my ( $self, $name, $value ) = @_;
1414     if ($name eq 'number') {
1415       $self->squared($value * $value);
1416     }
1417     $self->next::method($name, $value);
1418   }
1419
1420 Note that the hard work is done by the call to C<next::method>, which
1421 redispatches your call to store_column in the superclass(es).
1422
1423 =head2 Automatically creating related objects
1424
1425 You might have a class C<Artist> which has many C<CD>s.  Further, if you
1426 want to create a C<CD> object every time you insert an C<Artist> object.
1427 You can accomplish this by overriding C<insert> on your objects:
1428
1429   sub insert {
1430     my ( $self, @args ) = @_;
1431     $self->next::method(@args);
1432     $self->cds->new({})->fill_from_artist($self)->insert;
1433     return $self;
1434   }
1435
1436 where C<fill_from_artist> is a method you specify in C<CD> which sets
1437 values in C<CD> based on the data in the C<Artist> object you pass in.
1438
1439 =head2 Wrapping/overloading a column accessor
1440
1441 B<Problem:>
1442
1443 Say you have a table "Camera" and want to associate a description
1444 with each camera. For most cameras, you'll be able to generate the description from
1445 the other columns. However, in a few special cases you may want to associate a
1446 custom description with a camera.
1447
1448 B<Solution:>
1449
1450 In your database schema, define a description field in the "Camera" table that
1451 can contain text and null values.
1452
1453 In DBIC, we'll overload the column accessor to provide a sane default if no
1454 custom description is defined. The accessor will either return or generate the
1455 description, depending on whether the field is null or not.
1456
1457 First, in your "Camera" schema class, define the description field as follows:
1458
1459   __PACKAGE__->add_columns(description => { accessor => '_description' });
1460
1461 Next, we'll define the accessor-wrapper subroutine:
1462
1463   sub description {
1464       my $self = shift;
1465
1466       # If there is an update to the column, we'll let the original accessor
1467       # deal with it.
1468       return $self->_description(@_) if @_;
1469
1470       # Fetch the column value.
1471       my $description = $self->_description;
1472
1473       # If there's something in the description field, then just return that.
1474       return $description if defined $description && length $descripton;
1475
1476       # Otherwise, generate a description.
1477       return $self->generate_description;
1478   }
1479
1480 =head1 DEBUGGING AND PROFILING
1481
1482 =head2 DBIx::Class objects with Data::Dumper
1483
1484 L<Data::Dumper> can be a very useful tool for debugging, but sometimes it can
1485 be hard to find the pertinent data in all the data it can generate.
1486 Specifically, if one naively tries to use it like so,
1487
1488   use Data::Dumper;
1489
1490   my $cd = $schema->resultset('CD')->find(1);
1491   print Dumper($cd);
1492
1493 several pages worth of data from the CD object's schema and result source will
1494 be dumped to the screen. Since usually one is only interested in a few column
1495 values of the object, this is not very helpful.
1496
1497 Luckily, it is possible to modify the data before L<Data::Dumper> outputs
1498 it. Simply define a hook that L<Data::Dumper> will call on the object before
1499 dumping it. For example,
1500
1501   package My::DB::CD;
1502
1503   sub _dumper_hook {
1504     $_[0] = bless {
1505       %{ $_[0] },
1506       result_source => undef,
1507     }, ref($_[0]);
1508   }
1509
1510   [...]
1511
1512   use Data::Dumper;
1513
1514   local $Data::Dumper::Freezer = '_dumper_hook';
1515
1516   my $cd = $schema->resultset('CD')->find(1);
1517   print Dumper($cd);
1518          # dumps $cd without its ResultSource
1519
1520 If the structure of your schema is such that there is a common base class for
1521 all your table classes, simply put a method similar to C<_dumper_hook> in the
1522 base class and set C<$Data::Dumper::Freezer> to its name and L<Data::Dumper>
1523 will automagically clean up your data before printing it. See
1524 L<Data::Dumper/EXAMPLES> for more information.
1525
1526 =head2 Profiling
1527
1528 When you enable L<DBIx::Class::Storage>'s debugging it prints the SQL
1529 executed as well as notifications of query completion and transaction
1530 begin/commit.  If you'd like to profile the SQL you can subclass the
1531 L<DBIx::Class::Storage::Statistics> class and write your own profiling
1532 mechanism:
1533
1534   package My::Profiler;
1535   use strict;
1536
1537   use base 'DBIx::Class::Storage::Statistics';
1538
1539   use Time::HiRes qw(time);
1540
1541   my $start;
1542
1543   sub query_start {
1544     my $self = shift();
1545     my $sql = shift();
1546     my $params = @_;
1547
1548     $self->print("Executing $sql: ".join(', ', @params)."\n");
1549     $start = time();
1550   }
1551
1552   sub query_end {
1553     my $self = shift();
1554     my $sql = shift();
1555     my @params = @_;
1556
1557     my $elapsed = sprintf("%0.4f", time() - $start);
1558     $self->print("Execution took $elapsed seconds.\n");
1559     $start = undef;
1560   }
1561
1562   1;
1563
1564 You can then install that class as the debugging object:
1565
1566   __PACKAGE__->storage->debugobj(new My::Profiler());
1567   __PACKAGE__->storage->debug(1);
1568
1569 A more complicated example might involve storing each execution of SQL in an
1570 array:
1571
1572   sub query_end {
1573     my $self = shift();
1574     my $sql = shift();
1575     my @params = @_;
1576
1577     my $elapsed = time() - $start;
1578     push(@{ $calls{$sql} }, {
1579         params => \@params,
1580         elapsed => $elapsed
1581     });
1582   }
1583
1584 You could then create average, high and low execution times for an SQL
1585 statement and dig down to see if certain parameters cause aberrant behavior.
1586 You might want to check out L<DBIx::Class::QueryLog> as well.
1587
1588
1589 =cut