← Index
NYTProf Performance Profile   « block view • line view • sub view »
For xt/tapper-mcp-scheduler-with-db-longrun.t
  Run on Tue May 22 17:18:39 2012
Reported on Tue May 22 17:23:46 2012

Filename/2home/ss5/perl5/perlbrew/perls/perl-5.12.3/lib/site_perl/5.12.3/DBIx/Class/Relationship.pm
StatementsExecuted 11 statements in 301µs
Subroutines
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
11114µs16µsDBIx::Class::Relationship::::BEGIN@3DBIx::Class::Relationship::BEGIN@3
1119µs26µsDBIx::Class::Relationship::::BEGIN@4DBIx::Class::Relationship::BEGIN@4
1117µs103µsDBIx::Class::Relationship::::BEGIN@6DBIx::Class::Relationship::BEGIN@6
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments
Time
on line
Calls Time
in subs
Code
1package DBIx::Class::Relationship;
2
3318µs218µs
# spent 16µs (14+2) within DBIx::Class::Relationship::BEGIN@3 which was called: # once (14µs+2µs) by Class::C3::Componentised::ensure_class_loaded at line 3
use strict;
# spent 16µs making 1 call to DBIx::Class::Relationship::BEGIN@3 # spent 2µs making 1 call to strict::import
4329µs243µs
# spent 26µs (9+17) within DBIx::Class::Relationship::BEGIN@4 which was called: # once (9µs+17µs) by Class::C3::Componentised::ensure_class_loaded at line 4
use warnings;
# spent 26µs making 1 call to DBIx::Class::Relationship::BEGIN@4 # spent 17µs making 1 call to warnings::import
5
63240µs2199µs
# spent 103µs (7+96) within DBIx::Class::Relationship::BEGIN@6 which was called: # once (7µs+96µs) by Class::C3::Componentised::ensure_class_loaded at line 6
use base qw/DBIx::Class/;
# spent 103µs making 1 call to DBIx::Class::Relationship::BEGIN@6 # spent 96µs making 1 call to base::import
7
8110µs110.1ms__PACKAGE__->load_own_components(qw/
# spent 10.1ms making 1 call to Class::C3::Componentised::load_own_components
9 Helpers
10 Accessor
11 CascadeActions
12 ProxyMethods
13 Base
14/);
15
16=head1 NAME
17
18DBIx::Class::Relationship - Inter-table relationships
19
20=head1 SYNOPSIS
21
22 ## Creating relationships
23 MyApp::Schema::Actor->has_many('actorroles' => 'MyApp::Schema::ActorRole',
24 'actor');
25 MyApp::Schema::Role->has_many('actorroles' => 'MyApp::Schema::ActorRole',
26 'role');
27 MyApp::Schema::ActorRole->belongs_to('role' => 'MyApp::Schema::Role');
28 MyApp::Schema::ActorRole->belongs_to('actor' => 'MyApp::Schema::Actor');
29
30 MyApp::Schema::Role->many_to_many('actors' => 'actorroles', 'actor');
31 MyApp::Schema::Actor->many_to_many('roles' => 'actorroles', 'role');
32
33 ## Using relationships
34 $schema->resultset('Actor')->find({ id => 1})->roles();
35 $schema->resultset('Role')->find({ id => 1 })->actorroles->search_related('actor', { Name => 'Fred' });
36 $schema->resultset('Actor')->add_to_roles({ Name => 'Sherlock Holmes'});
37
38See L<DBIx::Class::Manual::Cookbook> for more.
39
40=head1 DESCRIPTION
41
42The word I<Relationship> has a specific meaning in DBIx::Class, see
43the definition in the L<Glossary|DBIx::Class::Manual::Glossary/Relationship>.
44
45This class provides methods to set up relationships between the tables
46in your database model. Relationships are the most useful and powerful
47technique that L<DBIx::Class> provides. To create efficient database queries,
48create relationships between any and all tables that have something in
49common, for example if you have a table Authors:
50
51 ID | Name | Age
52 ------------------
53 1 | Fred | 30
54 2 | Joe | 32
55
56and a table Books:
57
58 ID | Author | Name
59 --------------------
60 1 | 1 | Rulers of the universe
61 2 | 1 | Rulers of the galaxy
62
63Then without relationships, the method of getting all books by Fred goes like
64this:
65
66 my $fred = $schema->resultset('Author')->find({ Name => 'Fred' });
67 my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID });
68
69With a has_many relationship called "books" on Author (see below for details),
70we can do this instead:
71
72 my $fredsbooks = $schema->resultset('Author')->find({ Name => 'Fred' })->books;
73
74Each relationship sets up an accessor method on the
75L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items
76of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects,
77the relationships can be searched using the "search_related" method.
78In list context, each returns a list of Row objects for the related class,
79in scalar context, a new ResultSet representing the joined tables is
80returned. Thus, the calls can be chained to produce complex queries.
81Since the database is not actually queried until you attempt to retrieve
82the data for an actual item, no time is wasted producing them.
83
84 my $cheapfredbooks = $schema->resultset('Author')->find({
85 Name => 'Fred',
86 })->books->search_related('prices', {
87 Price => { '<=' => '5.00' },
88 });
89
90will produce a query something like:
91
92 SELECT * FROM Author me
93 LEFT JOIN Books books ON books.author = me.id
94 LEFT JOIN Prices prices ON prices.book = books.id
95 WHERE prices.Price <= 5.00
96
97all without needing multiple fetches.
98
99Only the helper methods for setting up standard relationship types
100are documented here. For the basic, lower-level methods, and a description
101of all the useful *_related methods that you get for free, see
102L<DBIx::Class::Relationship::Base>.
103
104=head1 METHODS
105
106All helper methods are called similar to the following template:
107
108 __PACKAGE__->$method_name('relname', 'Foreign::Class', \%cond|\@cond|\&cond?, \%attrs?);
109
110Both C<cond> and C<attrs> are optional. Pass C<undef> for C<cond> if
111you want to use the default value for it, but still want to set C<attrs>.
112
113See L<DBIx::Class::Relationship::Base/condition> for full documentation on
114definition of the C<cond> argument.
115
116See L<DBIx::Class::Relationship::Base/attributes> for documentation on the
117attributes that are allowed in the C<attrs> argument.
118
119
120=head2 belongs_to
121
122=over 4
123
124=item Arguments: $accessor_name, $related_class, $our_fk_column|\%cond|\@cond|\$cond?, \%attrs?
125
126=back
127
128Creates a relationship where the calling class stores the foreign
129class's primary key in one (or more) of the calling class columns.
130This relationship defaults to using C<$accessor_name> as the column
131name in this class to resolve the join against the primary key from
132C<$related_class>, unless C<$our_fk_column> specifies the foreign key column
133in this class or C<cond> specifies a reference to a join condition.
134
135=over
136
137=item accessor_name
138
139This argument is the name of the method you can call on a
140L<DBIx::Class::Row> object to retrieve the instance of the foreign
141class matching this relationship. This is often called the
142C<relation(ship) name>.
143
144Use this accessor_name in L<DBIx::Class::ResultSet/join>
145or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
146indicated by this relationship.
147
148=item related_class
149
150This is the class name of the table referenced by the foreign key in
151this class.
152
153=item our_fk_column
154
155The column name on this class that contains the foreign key.
156
157OR
158
159=item cond
160
161A hashref, arrayref or coderef specifying a custom join expression. For
162more info see L<DBIx::Class::Relationship::Base/condition>.
163
164=back
165
166 # in a Book class (where Author has many Books)
167 My::DBIC::Schema::Book->belongs_to(
168 author =>
169 'My::DBIC::Schema::Author',
170 'author_id'
171 );
172
173 # OR (same result)
174 My::DBIC::Schema::Book->belongs_to(
175 author =>
176 'My::DBIC::Schema::Author',
177 { 'foreign.author_id' => 'self.author_id' }
178 );
179
180 # OR (similar result but uglier accessor name)
181 My::DBIC::Schema::Book->belongs_to(
182 author_id =>
183 'My::DBIC::Schema::Author'
184 );
185
186 # Usage
187 my $author_obj = $book->author; # get author object
188 $book->author( $new_author_obj ); # set author object
189 $book->author_id(); # get the plain id
190
191 # To retrieve the plain id if you used the ugly version:
192 $book->get_column('author_id');
193
194
195If the relationship is optional -- i.e. the column containing the
196foreign key can be NULL -- then the belongs_to relationship does the
197right thing. Thus, in the example above C<< $obj->author >> would
198return C<undef>. However in this case you would probably want to set
199the L<join_type|DBIx::Class::Relationship/join_type> attribute so that
200a C<LEFT JOIN> is done, which makes complex resultsets involving
201C<join> or C<prefetch> operations work correctly. The modified
202declaration is shown below:
203
204 # in a Book class (where Author has_many Books)
205 __PACKAGE__->belongs_to(
206 author =>
207 'My::DBIC::Schema::Author',
208 'author',
209 { join_type => 'left' }
210 );
211
212
213Cascading deletes are off by default on a C<belongs_to>
214relationship. To turn them on, pass C<< cascade_delete => 1 >>
215in the $attr hashref.
216
217By default, DBIC will return undef and avoid querying the database if a
218C<belongs_to> accessor is called when any part of the foreign key IS NULL. To
219disable this behavior, pass C<< undef_on_null_fk => 0 >> in the C<\%attrs>
220hashref.
221
222NOTE: If you are used to L<Class::DBI> relationships, this is the equivalent
223of C<has_a>.
224
225See L<DBIx::Class::Relationship::Base/attributes> for documentation on relationship
226methods and valid relationship attributes. Also see L<DBIx::Class::ResultSet>
227for a L<list of standard resultset attributes|DBIx::Class::ResultSet/ATTRIBUTES>
228which can be assigned to relationships as well.
229
230=head2 has_many
231
232=over 4
233
234=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs?
235
236=back
237
238Creates a one-to-many relationship where the foreign class refers to
239this class's primary key. This relationship refers to zero or more
240records in the foreign table (e.g. a C<LEFT JOIN>). This relationship
241defaults to using the end of this classes namespace as the foreign key
242in C<$related_class> to resolve the join, unless C<$their_fk_column>
243specifies the foreign key column in C<$related_class> or C<cond>
244specifies a reference to a join condition.
245
246=over
247
248=item accessor_name
249
250This argument is the name of the method you can call on a
251L<DBIx::Class::Row> object to retrieve a resultset of the related
252class restricted to the ones related to the row object. In list
253context it returns the row objects. This is often called the
254C<relation(ship) name>.
255
256Use this accessor_name in L<DBIx::Class::ResultSet/join>
257or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
258indicated by this relationship.
259
260=item related_class
261
262This is the class name of the table which contains a foreign key
263column containing PK values of this class.
264
265=item their_fk_column
266
267The column name on the related class that contains the foreign key.
268
269OR
270
271=item cond
272
273A hashref, arrayref or coderef specifying a custom join expression. For
274more info see L<DBIx::Class::Relationship::Base/condition>.
275
276=back
277
278 # in an Author class (where Author has_many Books)
279 # assuming related class is storing our PK in "author_id"
280 My::DBIC::Schema::Author->has_many(
281 books =>
282 'My::DBIC::Schema::Book',
283 'author_id'
284 );
285
286 # OR (same result)
287 My::DBIC::Schema::Author->has_many(
288 books =>
289 'My::DBIC::Schema::Book',
290 { 'foreign.author_id' => 'self.id' },
291 );
292
293 # OR (similar result, assuming related_class is storing our PK, in "author")
294 # (the "author" is guessed at from "Author" in the class namespace)
295 My::DBIC::Schema::Author->has_many(
296 books =>
297 'My::DBIC::Schema::Book',
298 );
299
300
301 # Usage
302 # resultset of Books belonging to author
303 my $booklist = $author->books;
304
305 # resultset of Books belonging to author, restricted by author name
306 my $booklist = $author->books({
307 name => { LIKE => '%macaroni%' },
308 { prefetch => [qw/book/],
309 });
310
311 # array of Book objects belonging to author
312 my @book_objs = $author->books;
313
314 # force resultset even in list context
315 my $books_rs = $author->books;
316 ( $books_rs ) = $obj->books_rs;
317
318 # create a new book for this author, the relation fields are auto-filled
319 $author->create_related('books', \%col_data);
320 # alternative method for the above
321 $author->add_to_books(\%col_data);
322
323
324Three methods are created when you create a has_many relationship.
325The first method is the expected accessor method, C<$accessor_name()>.
326The second is almost exactly the same as the accessor method but "_rs"
327is added to the end of the method name, eg C<$accessor_name_rs()>.
328This method works just like the normal accessor, except that it always
329returns a resultset, even in list context. The third method, named C<<
330add_to_$relname >>, will also be added to your Row items; this allows
331you to insert new related items, using the same mechanism as in
332L<DBIx::Class::Relationship::Base/"create_related">.
333
334If you delete an object in a class with a C<has_many> relationship, all
335the related objects will be deleted as well. To turn this behaviour off,
336pass C<< cascade_delete => 0 >> in the C<$attr> hashref.
337
338The cascaded operations are performed after the requested delete or
339update, so if your database has a constraint on the relationship, it
340will have deleted/updated the related records or raised an exception
341before DBIx::Class gets to perform the cascaded operation.
342
343If you copy an object in a class with a C<has_many> relationship, all
344the related objects will be copied as well. To turn this behaviour off,
345pass C<< cascade_copy => 0 >> in the C<$attr> hashref. The behaviour
346defaults to C<< cascade_copy => 1 >>.
347
348See L<DBIx::Class::Relationship::Base/attributes> for documentation on
349relationship methods and valid relationship attributes. Also see
350L<DBIx::Class::ResultSet> for a L<list of standard resultset
351attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to
352relationships as well.
353
354=head2 might_have
355
356=over 4
357
358=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs?
359
360=back
361
362Creates an optional one-to-one relationship with a class. This relationship
363defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
364resolve the join, unless C<$their_fk_column> specifies the foreign key
365column in C<$related_class> or C<cond> specifies a reference to a join
366condition.
367
368=over
369
370=item accessor_name
371
372This argument is the name of the method you can call on a
373L<DBIx::Class::Row> object to retrieve the instance of the foreign
374class matching this relationship. This is often called the
375C<relation(ship) name>.
376
377Use this accessor_name in L<DBIx::Class::ResultSet/join>
378or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
379indicated by this relationship.
380
381=item related_class
382
383This is the class name of the table which contains a foreign key
384column containing PK values of this class.
385
386=item their_fk_column
387
388The column name on the related class that contains the foreign key.
389
390OR
391
392=item cond
393
394A hashref, arrayref or coderef specifying a custom join expression. For
395more info see L<DBIx::Class::Relationship::Base/condition>.
396
397=back
398
399 # Author may have an entry in the pseudonym table
400 My::DBIC::Schema::Author->might_have(
401 pseudonym =>
402 'My::DBIC::Schema::Pseudonym',
403 'author_id',
404 );
405
406 # OR (same result, assuming the related_class stores our PK)
407 My::DBIC::Schema::Author->might_have(
408 pseudonym =>
409 'My::DBIC::Schema::Pseudonym',
410 );
411
412 # OR (same result)
413 My::DBIC::Schema::Author->might_have(
414 pseudonym =>
415 'My::DBIC::Schema::Pseudonym',
416 { 'foreign.author_id' => 'self.id' },
417 );
418
419 # Usage
420 my $pname = $author->pseudonym; # to get the Pseudonym object
421
422If you update or delete an object in a class with a C<might_have>
423relationship, the related object will be updated or deleted as well. To
424turn off this behavior, add C<< cascade_delete => 0 >> to the C<$attr>
425hashref.
426
427The cascaded operations are performed after the requested delete or
428update, so if your database has a constraint on the relationship, it
429will have deleted/updated the related records or raised an exception
430before DBIx::Class gets to perform the cascaded operation.
431
432See L<DBIx::Class::Relationship::Base/attributes> for documentation on
433relationship methods and valid relationship attributes. Also see
434L<DBIx::Class::ResultSet> for a L<list of standard resultset
435attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to
436relationships as well.
437
438Note that if you supply a condition on which to join, and the column in the
439current table allows nulls (i.e., has the C<is_nullable> attribute set to a
440true value), than C<might_have> will warn about this because it's naughty and
441you shouldn't do that. The warning will look something like:
442
443 "might_have/has_one" must not be on columns with is_nullable set to true (MySchema::SomeClass/key)
444
445If you must be naughty, you can suppress the warning by setting
446C<DBIC_DONT_VALIDATE_RELS> environment variable to a true value. Otherwise,
447you probably just meant to use C<DBIx::Class::Relationship/belongs_to>.
448
449=head2 has_one
450
451=over 4
452
453=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs?
454
455=back
456
457Creates a one-to-one relationship with a class. This relationship
458defaults to using C<$accessor_name> as the foreign key in C<$related_class> to
459resolve the join, unless C<$their_fk_column> specifies the foreign key
460column in C<$related_class> or C<cond> specifies a reference to a join
461condition.
462
463=over
464
465=item accessor_name
466
467This argument is the name of the method you can call on a
468L<DBIx::Class::Row> object to retrieve the instance of the foreign
469class matching this relationship. This is often called the
470C<relation(ship) name>.
471
472Use this accessor_name in L<DBIx::Class::ResultSet/join>
473or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
474indicated by this relationship.
475
476=item related_class
477
478This is the class name of the table which contains a foreign key
479column containing PK values of this class.
480
481=item their_fk_column
482
483The column name on the related class that contains the foreign key.
484
485OR
486
487=item cond
488
489A hashref, arrayref or coderef specifying a custom join expression. For
490more info see L<DBIx::Class::Relationship::Base/condition>.
491
492=back
493
494 # Every book has exactly one ISBN
495 My::DBIC::Schema::Book->has_one(
496 isbn =>
497 'My::DBIC::Schema::ISBN',
498 'book_id',
499 );
500
501 # OR (same result, assuming related_class stores our PK)
502 My::DBIC::Schema::Book->has_one(
503 isbn =>
504 'My::DBIC::Schema::ISBN',
505 );
506
507 # OR (same result)
508 My::DBIC::Schema::Book->has_one(
509 isbn =>
510 'My::DBIC::Schema::ISBN',
511 { 'foreign.book_id' => 'self.id' },
512 );
513
514 # Usage
515 my $isbn_obj = $book->isbn; # to get the ISBN object
516
517Creates a one-to-one relationship with another class. This is just
518like C<might_have>, except the implication is that the other object is
519always present. The only difference between C<has_one> and
520C<might_have> is that C<has_one> uses an (ordinary) inner join,
521whereas C<might_have> defaults to a left join.
522
523The has_one relationship should be used when a row in the table must
524have exactly one related row in another table. If the related row
525might not exist in the foreign table, use the
526L<DBIx::Class::Relationship/might_have> relationship.
527
528In the above example, each Book in the database is associated with exactly one
529ISBN object.
530
531See L<DBIx::Class::Relationship::Base/attributes> for documentation on
532relationship methods and valid relationship attributes. Also see
533L<DBIx::Class::ResultSet> for a L<list of standard resultset
534attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to
535relationships as well.
536
537Note that if you supply a condition on which to join, if the column in the
538current table allows nulls (i.e., has the C<is_nullable> attribute set to a
539true value), than warnings might apply just as with
540L<DBIx::Class::Relationship/might_have>.
541
542=head2 many_to_many
543
544=over 4
545
546=item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, \%attrs?
547
548=back
549
550C<many_to_many> is a I<Relationship bridge> which has a specific
551meaning in DBIx::Class, see the definition in the
552L<Glossary|DBIx::Class::Manual::Glossary/Relationship bridge>.
553
554C<many_to_many> is not strictly a relationship in its own right. Instead, it is
555a bridge between two resultsets which provide the same kind of convenience
556accessors as true relationships provide. Although the accessor will return a
557resultset or collection of objects just like has_many does, you cannot call
558C<related_resultset> and similar methods which operate on true relationships.
559
560=over
561
562=item accessor_name
563
564This argument is the name of the method you can call on a
565L<DBIx::Class::Row> object to retrieve the rows matching this
566relationship.
567
568On a many_to_many, unlike other relationships, this cannot be used in
569L<DBIx::Class::ResultSet/search> to join tables. Use the relations
570bridged across instead.
571
572=item link_rel_name
573
574This is the accessor_name from the has_many relationship we are
575bridging from.
576
577=item foreign_rel_name
578
579This is the accessor_name of the belongs_to relationship in the link
580table that we are bridging across (which gives us the table we are
581bridging to).
582
583=back
584
585To create a many_to_many relationship from Actor to Role:
586
587 My::DBIC::Schema::Actor->has_many( actor_roles =>
588 'My::DBIC::Schema::ActorRoles',
589 'actor' );
590 My::DBIC::Schema::ActorRoles->belongs_to( role =>
591 'My::DBIC::Schema::Role' );
592 My::DBIC::Schema::ActorRoles->belongs_to( actor =>
593 'My::DBIC::Schema::Actor' );
594
595 My::DBIC::Schema::Actor->many_to_many( roles => 'actor_roles',
596 'role' );
597
598And, for the reverse relationship, from Role to Actor:
599
600 My::DBIC::Schema::Role->has_many( actor_roles =>
601 'My::DBIC::Schema::ActorRoles',
602 'role' );
603
604 My::DBIC::Schema::Role->many_to_many( actors => 'actor_roles', 'actor' );
605
606To add a role for your actor, and fill in the year of the role in the
607actor_roles table:
608
609 $actor->add_to_roles($role, { year => 1995 });
610
611In the above example, ActorRoles is the link table class, and Role is the
612foreign class. The C<$link_rel_name> parameter is the name of the accessor for
613the has_many relationship from this table to the link table, and the
614C<$foreign_rel_name> parameter is the accessor for the belongs_to relationship
615from the link table to the foreign table.
616
617To use many_to_many, existing relationships from the original table to the link
618table, and from the link table to the end table must already exist, these
619relation names are then used in the many_to_many call.
620
621In the above example, the Actor class will have 3 many_to_many accessor methods
622set: C<roles>, C<add_to_roles>, C<set_roles>, and similarly named accessors
623will be created for the Role class for the C<actors> many_to_many
624relationship.
625
626See L<DBIx::Class::Relationship::Base/attributes> for documentation on
627relationship methods and valid relationship attributes. Also see
628L<DBIx::Class::ResultSet> for a L<list of standard resultset
629attributes|DBIx::Class::ResultSet/ATTRIBUTES> which can be assigned to
630relationships as well.
631
632=cut
633
63415µs1;
635
636=head1 AUTHORS
637
638see L<DBIx::Class>
639
640=head1 LICENSE
641
642You may distribute this code under the same terms as Perl itself.
643
644=cut
645