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