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