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