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