1 package DBIx::Class::ResultSource;
6 use base qw/DBIx::Class::ResultSource::RowParser DBIx::Class/;
8 use DBIx::Class::ResultSet;
9 use DBIx::Class::ResultSourceHandle;
11 use DBIx::Class::Carp;
12 use Devel::GlobalDestruction;
14 use List::Util 'first';
15 use Scalar::Util qw/blessed weaken isweak/;
19 __PACKAGE__->mk_group_accessors(simple => qw/
20 source_name name source_info
21 _ordered_columns _columns _primaries _unique_constraints
22 _relationships resultset_attributes
23 column_info_from_storage
26 __PACKAGE__->mk_group_accessors(component_class => qw/
31 __PACKAGE__->mk_classdata( sqlt_deploy_callback => 'default_sqlt_deploy_hook' );
35 DBIx::Class::ResultSource - Result source object
39 # Create a table based result source, in a result class.
41 package MyApp::Schema::Result::Artist;
42 use base qw/DBIx::Class::Core/;
44 __PACKAGE__->table('artist');
45 __PACKAGE__->add_columns(qw/ artistid name /);
46 __PACKAGE__->set_primary_key('artistid');
47 __PACKAGE__->has_many(cds => 'MyApp::Schema::Result::CD');
51 # Create a query (view) based result source, in a result class
52 package MyApp::Schema::Result::Year2000CDs;
53 use base qw/DBIx::Class::Core/;
55 __PACKAGE__->load_components('InflateColumn::DateTime');
56 __PACKAGE__->table_class('DBIx::Class::ResultSource::View');
58 __PACKAGE__->table('year2000cds');
59 __PACKAGE__->result_source_instance->is_virtual(1);
60 __PACKAGE__->result_source_instance->view_definition(
61 "SELECT cdid, artist, title FROM cd WHERE year ='2000'"
67 A ResultSource is an object that represents a source of data for querying.
69 This class is a base class for various specialised types of result
70 sources, for example L<DBIx::Class::ResultSource::Table>. Table is the
71 default result source type, so one is created for you when defining a
72 result class as described in the synopsis above.
74 More specifically, the L<DBIx::Class::Core> base class pulls in the
75 L<DBIx::Class::ResultSourceProxy::Table> component, which defines
76 the L<table|DBIx::Class::ResultSourceProxy::Table/table> method.
77 When called, C<table> creates and stores an instance of
78 L<DBIx::Class::ResultSoure::Table>. Luckily, to use tables as result
79 sources, you don't need to remember any of this.
81 Result sources representing select queries, or views, can also be
82 created, see L<DBIx::Class::ResultSource::View> for full details.
84 =head2 Finding result source objects
86 As mentioned above, a result source instance is created and stored for
87 you when you define a L<result class|DBIx::Class::Manual::Glossary/Result class>.
89 You can retrieve the result source at runtime in the following ways:
93 =item From a Schema object:
95 $schema->source($source_name);
97 =item From a Result object:
99 $result->result_source;
101 =item From a ResultSet object:
114 my ($class, $attrs) = @_;
115 $class = ref $class if ref $class;
117 my $new = bless { %{$attrs || {}} }, $class;
118 $new->{resultset_class} ||= 'DBIx::Class::ResultSet';
119 $new->{resultset_attributes} = { %{$new->{resultset_attributes} || {}} };
120 $new->{_ordered_columns} = [ @{$new->{_ordered_columns}||[]}];
121 $new->{_columns} = { %{$new->{_columns}||{}} };
122 $new->{_relationships} = { %{$new->{_relationships}||{}} };
123 $new->{name} ||= "!!NAME NOT SET!!";
124 $new->{_columns_info_loaded} ||= 0;
134 =item Arguments: @columns
136 =item Return Value: L<$result_source|/new>
140 $source->add_columns(qw/col1 col2 col3/);
142 $source->add_columns('col1' => \%col1_info, 'col2' => \%col2_info, ...);
144 Adds columns to the result source. If supplied colname => hashref
145 pairs, uses the hashref as the L</column_info> for that column. Repeated
146 calls of this method will add more columns, not replace them.
148 The column names given will be created as accessor methods on your
149 L<Result|DBIx::Class::Manual::ResultClass> objects. You can change the name of the accessor
150 by supplying an L</accessor> in the column_info hash.
152 If a column name beginning with a plus sign ('+col1') is provided, the
153 attributes provided will be merged with any existing attributes for the
154 column, with the new attributes taking precedence in the case that an
155 attribute already exists. Using this without a hashref
156 (C<< $source->add_columns(qw/+col1 +col2/) >>) is legal, but useless --
157 it does the same thing it would do without the plus.
159 The contents of the column_info are not set in stone. The following
160 keys are currently recognised/used by DBIx::Class:
166 { accessor => '_name' }
168 # example use, replace standard accessor with one of your own:
170 my ($self, $value) = @_;
172 die "Name cannot contain digits!" if($value =~ /\d/);
173 $self->_name($value);
175 return $self->_name();
178 Use this to set the name of the accessor method for this column. If unset,
179 the name of the column will be used.
183 { data_type => 'integer' }
185 This contains the column type. It is automatically filled if you use the
186 L<SQL::Translator::Producer::DBIx::Class::File> producer, or the
187 L<DBIx::Class::Schema::Loader> module.
189 Currently there is no standard set of values for the data_type. Use
190 whatever your database supports.
196 The length of your column, if it is a column type that can have a size
197 restriction. This is currently only used to create tables from your
198 schema, see L<DBIx::Class::Schema/deploy>.
204 Set this to a true value for a columns that is allowed to contain NULL
205 values, default is false. This is currently only used to create tables
206 from your schema, see L<DBIx::Class::Schema/deploy>.
208 =item is_auto_increment
210 { is_auto_increment => 1 }
212 Set this to a true value for a column whose value is somehow
213 automatically set, defaults to false. This is used to determine which
214 columns to empty when cloning objects using
215 L<DBIx::Class::Row/copy>. It is also used by
216 L<DBIx::Class::Schema/deploy>.
222 Set this to a true or false value (not C<undef>) to explicitly specify
223 if this column contains numeric data. This controls how set_column
224 decides whether to consider a column dirty after an update: if
225 C<is_numeric> is true a numeric comparison C<< != >> will take place
226 instead of the usual C<eq>
228 If not specified the storage class will attempt to figure this out on
229 first access to the column, based on the column C<data_type>. The
230 result will be cached in this attribute.
234 { is_foreign_key => 1 }
236 Set this to a true value for a column that contains a key from a
237 foreign table, defaults to false. This is currently only used to
238 create tables from your schema, see L<DBIx::Class::Schema/deploy>.
242 { default_value => \'now()' }
244 Set this to the default value which will be inserted into a column by
245 the database. Can contain either a value or a function (use a
246 reference to a scalar e.g. C<\'now()'> if you want a function). This
247 is currently only used to create tables from your schema, see
248 L<DBIx::Class::Schema/deploy>.
250 See the note on L<DBIx::Class::Row/new> for more information about possible
251 issues related to db-side default values.
255 { sequence => 'my_table_seq' }
257 Set this on a primary key column to the name of the sequence used to
258 generate a new key value. If not specified, L<DBIx::Class::PK::Auto>
259 will attempt to retrieve the name of the sequence from the database
262 =item retrieve_on_insert
264 { retrieve_on_insert => 1 }
266 For every column where this is set to true, DBIC will retrieve the RDBMS-side
267 value upon a new row insertion (normally only the autoincrement PK is
268 retrieved on insert). C<INSERT ... RETURNING> is used automatically if
269 supported by the underlying storage, otherwise an extra SELECT statement is
270 executed to retrieve the missing data.
274 { auto_nextval => 1 }
276 Set this to a true value for a column whose value is retrieved automatically
277 from a sequence or function (if supported by your Storage driver.) For a
278 sequence, if you do not use a trigger to get the nextval, you have to set the
279 L</sequence> value as well.
281 Also set this for MSSQL columns with the 'uniqueidentifier'
282 L<data_type|DBIx::Class::ResultSource/data_type> whose values you want to
283 automatically generate using C<NEWID()>, unless they are a primary key in which
284 case this will be done anyway.
288 This is used by L<DBIx::Class::Schema/deploy> and L<SQL::Translator>
289 to add extra non-generic data to the column. For example: C<< extra
290 => { unsigned => 1} >> is used by the MySQL producer to set an integer
291 column to unsigned. For more details, see
292 L<SQL::Translator::Producer::MySQL>.
300 =item Arguments: $colname, \%columninfo?
302 =item Return Value: 1/0 (true/false)
306 $source->add_column('col' => \%info);
308 Add a single column and optional column info. Uses the same column
309 info keys as L</add_columns>.
314 my ($self, @cols) = @_;
315 $self->_ordered_columns(\@cols) unless $self->_ordered_columns;
318 my $columns = $self->_columns;
319 while (my $col = shift @cols) {
320 my $column_info = {};
321 if ($col =~ s/^\+//) {
322 $column_info = $self->column_info($col);
325 # If next entry is { ... } use that for the column info, if not
326 # use an empty hashref
328 my $new_info = shift(@cols);
329 %$column_info = (%$column_info, %$new_info);
331 push(@added, $col) unless exists $columns->{$col};
332 $columns->{$col} = $column_info;
334 push @{ $self->_ordered_columns }, @added;
338 sub add_column { shift->add_columns(@_); } # DO NOT CHANGE THIS TO GLOB
344 =item Arguments: $colname
346 =item Return Value: 1/0 (true/false)
350 if ($source->has_column($colname)) { ... }
352 Returns true if the source has a column of this name, false otherwise.
357 my ($self, $column) = @_;
358 return exists $self->_columns->{$column};
365 =item Arguments: $colname
367 =item Return Value: Hashref of info
371 my $info = $source->column_info($col);
373 Returns the column metadata hashref for a column, as originally passed
374 to L</add_columns>. See L</add_columns> above for information on the
375 contents of the hashref.
380 my ($self, $column) = @_;
381 $self->throw_exception("No such column $column")
382 unless exists $self->_columns->{$column};
384 if ( ! $self->_columns->{$column}{data_type}
385 and ! $self->{_columns_info_loaded}
386 and $self->column_info_from_storage
387 and my $stor = try { $self->storage } )
389 $self->{_columns_info_loaded}++;
391 # try for the case of storage without table
393 my $info = $stor->columns_info_for( $self->from );
395 { (lc $_) => $info->{$_} }
399 foreach my $col ( keys %{$self->_columns} ) {
400 $self->_columns->{$col} = {
401 %{ $self->_columns->{$col} },
402 %{ $info->{$col} || $lc_info->{lc $col} || {} }
408 return $self->_columns->{$column};
415 =item Arguments: none
417 =item Return Value: Ordered list of column names
421 my @column_names = $source->columns;
423 Returns all column names in the order they were declared to L</add_columns>.
429 $self->throw_exception(
430 "columns() is a read-only accessor, did you mean add_columns()?"
432 return @{$self->{_ordered_columns}||[]};
439 =item Arguments: \@colnames ?
441 =item Return Value: Hashref of column name/info pairs
445 my $columns_info = $source->columns_info;
447 Like L</column_info> but returns information for the requested columns. If
448 the optional column-list arrayref is omitted it returns info on all columns
449 currently defined on the ResultSource via L</add_columns>.
454 my ($self, $columns) = @_;
456 my $colinfo = $self->_columns;
459 first { ! $_->{data_type} } values %$colinfo
461 ! $self->{_columns_info_loaded}
463 $self->column_info_from_storage
465 my $stor = try { $self->storage }
467 $self->{_columns_info_loaded}++;
469 # try for the case of storage without table
471 my $info = $stor->columns_info_for( $self->from );
473 { (lc $_) => $info->{$_} }
477 foreach my $col ( keys %$colinfo ) {
479 %{ $colinfo->{$col} },
480 %{ $info->{$col} || $lc_info->{lc $col} || {} }
490 if (my $inf = $colinfo->{$_}) {
494 $self->throw_exception( sprintf (
495 "No such column '%s' on source '%s'",
497 $self->source_name || $self->name || 'Unknown source...?',
509 =head2 remove_columns
513 =item Arguments: @colnames
515 =item Return Value: not defined
519 $source->remove_columns(qw/col1 col2 col3/);
521 Removes the given list of columns by name, from the result source.
523 B<Warning>: Removing a column that is also used in the sources primary
524 key, or in one of the sources unique constraints, B<will> result in a
525 broken result source.
531 =item Arguments: $colname
533 =item Return Value: not defined
537 $source->remove_column('col');
539 Remove a single column by name from the result source, similar to
542 B<Warning>: Removing a column that is also used in the sources primary
543 key, or in one of the sources unique constraints, B<will> result in a
544 broken result source.
549 my ($self, @to_remove) = @_;
551 my $columns = $self->_columns
556 delete $columns->{$_};
560 $self->_ordered_columns([ grep { not $to_remove{$_} } @{$self->_ordered_columns} ]);
563 sub remove_column { shift->remove_columns(@_); } # DO NOT CHANGE THIS TO GLOB
565 =head2 set_primary_key
569 =item Arguments: @cols
571 =item Return Value: not defined
575 Defines one or more columns as primary key for this source. Must be
576 called after L</add_columns>.
578 Additionally, defines a L<unique constraint|add_unique_constraint>
581 Note: you normally do want to define a primary key on your sources
582 B<even if the underlying database table does not have a primary key>.
584 L<DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
589 sub set_primary_key {
590 my ($self, @cols) = @_;
592 my $colinfo = $self->columns_info(\@cols);
593 for my $col (@cols) {
594 carp_unique(sprintf (
595 "Primary key of source '%s' includes the column '%s' which has its "
596 . "'is_nullable' attribute set to true. This is a mistake and will cause "
597 . 'various Result-object operations to fail',
598 $self->source_name || $self->name || 'Unknown source...?',
600 )) if $colinfo->{$col}{is_nullable};
603 $self->_primaries(\@cols);
605 $self->add_unique_constraint(primary => \@cols);
608 =head2 primary_columns
612 =item Arguments: none
614 =item Return Value: Ordered list of primary column names
618 Read-only accessor which returns the list of primary keys, supplied by
623 sub primary_columns {
624 return @{shift->_primaries||[]};
627 # a helper method that will automatically die with a descriptive message if
628 # no pk is defined on the source in question. For internal use to save
629 # on if @pks... boilerplate
630 sub _pri_cols_or_die {
632 my @pcols = $self->primary_columns
633 or $self->throw_exception (sprintf(
634 "Operation requires a primary key to be declared on '%s' via set_primary_key",
635 # source_name is set only after schema-registration
636 $self->source_name || $self->result_class || $self->name || 'Unknown source...?',
641 # same as above but mandating single-column PK (used by relationship condition
643 sub _single_pri_col_or_die {
645 my ($pri, @too_many) = $self->_pri_cols_or_die;
647 $self->throw_exception( sprintf(
648 "Operation requires a single-column primary key declared on '%s'",
649 $self->source_name || $self->result_class || $self->name || 'Unknown source...?',
657 Manually define the correct sequence for your table, to avoid the overhead
658 associated with looking up the sequence automatically. The supplied sequence
659 will be applied to the L</column_info> of each L<primary_key|/set_primary_key>
663 =item Arguments: $sequence_name
665 =item Return Value: not defined
672 my ($self,$seq) = @_;
674 my @pks = $self->primary_columns
677 $_->{sequence} = $seq
678 for values %{ $self->columns_info (\@pks) };
682 =head2 add_unique_constraint
686 =item Arguments: $name?, \@colnames
688 =item Return Value: not defined
692 Declare a unique constraint on this source. Call once for each unique
695 # For UNIQUE (column1, column2)
696 __PACKAGE__->add_unique_constraint(
697 constraint_name => [ qw/column1 column2/ ],
700 Alternatively, you can specify only the columns:
702 __PACKAGE__->add_unique_constraint([ qw/column1 column2/ ]);
704 This will result in a unique constraint named
705 C<table_column1_column2>, where C<table> is replaced with the table
708 Unique constraints are used, for example, when you pass the constraint
709 name as the C<key> attribute to L<DBIx::Class::ResultSet/find>. Then
710 only columns in the constraint are searched.
712 Throws an error if any of the given column names do not yet exist on
717 sub add_unique_constraint {
721 $self->throw_exception(
722 'add_unique_constraint() does not accept multiple constraints, use '
723 . 'add_unique_constraints() instead'
728 if (ref $cols ne 'ARRAY') {
729 $self->throw_exception (
730 'Expecting an arrayref of constraint columns, got ' . ($cols||'NOTHING')
736 $name ||= $self->name_unique_constraint($cols);
738 foreach my $col (@$cols) {
739 $self->throw_exception("No such column $col on table " . $self->name)
740 unless $self->has_column($col);
743 my %unique_constraints = $self->unique_constraints;
744 $unique_constraints{$name} = $cols;
745 $self->_unique_constraints(\%unique_constraints);
748 =head2 add_unique_constraints
752 =item Arguments: @constraints
754 =item Return Value: not defined
758 Declare multiple unique constraints on this source.
760 __PACKAGE__->add_unique_constraints(
761 constraint_name1 => [ qw/column1 column2/ ],
762 constraint_name2 => [ qw/column2 column3/ ],
765 Alternatively, you can specify only the columns:
767 __PACKAGE__->add_unique_constraints(
768 [ qw/column1 column2/ ],
769 [ qw/column3 column4/ ]
772 This will result in unique constraints named C<table_column1_column2> and
773 C<table_column3_column4>, where C<table> is replaced with the table name.
775 Throws an error if any of the given column names do not yet exist on
778 See also L</add_unique_constraint>.
782 sub add_unique_constraints {
784 my @constraints = @_;
786 if ( !(@constraints % 2) && first { ref $_ ne 'ARRAY' } @constraints ) {
787 # with constraint name
788 while (my ($name, $constraint) = splice @constraints, 0, 2) {
789 $self->add_unique_constraint($name => $constraint);
794 foreach my $constraint (@constraints) {
795 $self->add_unique_constraint($constraint);
800 =head2 name_unique_constraint
804 =item Arguments: \@colnames
806 =item Return Value: Constraint name
810 $source->table('mytable');
811 $source->name_unique_constraint(['col1', 'col2']);
815 Return a name for a unique constraint containing the specified
816 columns. The name is created by joining the table name and each column
817 name, using an underscore character.
819 For example, a constraint on a table named C<cd> containing the columns
820 C<artist> and C<title> would result in a constraint name of C<cd_artist_title>.
822 This is used by L</add_unique_constraint> if you do not specify the
823 optional constraint name.
827 sub name_unique_constraint {
828 my ($self, $cols) = @_;
830 my $name = $self->name;
831 $name = $$name if (ref $name eq 'SCALAR');
833 return join '_', $name, @$cols;
836 =head2 unique_constraints
840 =item Arguments: none
842 =item Return Value: Hash of unique constraint data
846 $source->unique_constraints();
848 Read-only accessor which returns a hash of unique constraints on this
851 The hash is keyed by constraint name, and contains an arrayref of
852 column names as values.
856 sub unique_constraints {
857 return %{shift->_unique_constraints||{}};
860 =head2 unique_constraint_names
864 =item Arguments: none
866 =item Return Value: Unique constraint names
870 $source->unique_constraint_names();
872 Returns the list of unique constraint names defined on this source.
876 sub unique_constraint_names {
879 my %unique_constraints = $self->unique_constraints;
881 return keys %unique_constraints;
884 =head2 unique_constraint_columns
888 =item Arguments: $constraintname
890 =item Return Value: List of constraint columns
894 $source->unique_constraint_columns('myconstraint');
896 Returns the list of columns that make up the specified unique constraint.
900 sub unique_constraint_columns {
901 my ($self, $constraint_name) = @_;
903 my %unique_constraints = $self->unique_constraints;
905 $self->throw_exception(
906 "Unknown unique constraint $constraint_name on '" . $self->name . "'"
907 ) unless exists $unique_constraints{$constraint_name};
909 return @{ $unique_constraints{$constraint_name} };
912 =head2 sqlt_deploy_callback
916 =item Arguments: $callback_name | \&callback_code
918 =item Return Value: $callback_name | \&callback_code
922 __PACKAGE__->sqlt_deploy_callback('mycallbackmethod');
926 __PACKAGE__->sqlt_deploy_callback(sub {
927 my ($source_instance, $sqlt_table) = @_;
931 An accessor to set a callback to be called during deployment of
932 the schema via L<DBIx::Class::Schema/create_ddl_dir> or
933 L<DBIx::Class::Schema/deploy>.
935 The callback can be set as either a code reference or the name of a
936 method in the current result class.
938 Defaults to L</default_sqlt_deploy_hook>.
940 Your callback will be passed the $source object representing the
941 ResultSource instance being deployed, and the
942 L<SQL::Translator::Schema::Table> object being created from it. The
943 callback can be used to manipulate the table object or add your own
944 customised indexes. If you need to manipulate a non-table object, use
945 the L<DBIx::Class::Schema/sqlt_deploy_hook>.
947 See L<DBIx::Class::Manual::Cookbook/Adding Indexes And Functions To
948 Your SQL> for examples.
950 This sqlt deployment callback can only be used to manipulate
951 SQL::Translator objects as they get turned into SQL. To execute
952 post-deploy statements which SQL::Translator does not currently
953 handle, override L<DBIx::Class::Schema/deploy> in your Schema class
954 and call L<dbh_do|DBIx::Class::Storage::DBI/dbh_do>.
956 =head2 default_sqlt_deploy_hook
958 This is the default deploy hook implementation which checks if your
959 current Result class has a C<sqlt_deploy_hook> method, and if present
960 invokes it B<on the Result class directly>. This is to preserve the
961 semantics of C<sqlt_deploy_hook> which was originally designed to expect
962 the Result class name and the
963 L<$sqlt_table instance|SQL::Translator::Schema::Table> of the table being
968 sub default_sqlt_deploy_hook {
971 my $class = $self->result_class;
973 if ($class and $class->can('sqlt_deploy_hook')) {
974 $class->sqlt_deploy_hook(@_);
978 sub _invoke_sqlt_deploy_hook {
980 if ( my $hook = $self->sqlt_deploy_callback) {
989 =item Arguments: $classname
991 =item Return Value: $classname
995 use My::Schema::ResultClass::Inflator;
998 use My::Schema::Artist;
1000 __PACKAGE__->result_class('My::Schema::ResultClass::Inflator');
1002 Set the default result class for this source. You can use this to create
1003 and use your own result inflator. See L<DBIx::Class::ResultSet/result_class>
1006 Please note that setting this to something like
1007 L<DBIx::Class::ResultClass::HashRefInflator> will make every result unblessed
1008 and make life more difficult. Inflators like those are better suited to
1009 temporary usage via L<DBIx::Class::ResultSet/result_class>.
1015 =item Arguments: none
1017 =item Return Value: L<$resultset|DBIx::Class::ResultSet>
1021 Returns a resultset for the given source. This will initially be created
1022 on demand by calling
1024 $self->resultset_class->new($self, $self->resultset_attributes)
1026 but is cached from then on unless resultset_class changes.
1028 =head2 resultset_class
1032 =item Arguments: $classname
1034 =item Return Value: $classname
1038 package My::Schema::ResultSet::Artist;
1039 use base 'DBIx::Class::ResultSet';
1042 # In the result class
1043 __PACKAGE__->resultset_class('My::Schema::ResultSet::Artist');
1046 $source->resultset_class('My::Schema::ResultSet::Artist');
1048 Set the class of the resultset. This is useful if you want to create your
1049 own resultset methods. Create your own class derived from
1050 L<DBIx::Class::ResultSet>, and set it here. If called with no arguments,
1051 this method returns the name of the existing resultset class, if one
1054 =head2 resultset_attributes
1058 =item Arguments: L<\%attrs|DBIx::Class::ResultSet/ATTRIBUTES>
1060 =item Return Value: L<\%attrs|DBIx::Class::ResultSet/ATTRIBUTES>
1064 # In the result class
1065 __PACKAGE__->resultset_attributes({ order_by => [ 'id' ] });
1068 $source->resultset_attributes({ order_by => [ 'id' ] });
1070 Store a collection of resultset attributes, that will be set on every
1071 L<DBIx::Class::ResultSet> produced from this result source.
1073 B<CAVEAT>: C<resultset_attributes> comes with its own set of issues and
1074 bugs! While C<resultset_attributes> isn't deprecated per se, its usage is
1077 Since relationships use attributes to link tables together, the "default"
1078 attributes you set may cause unpredictable and undesired behavior. Furthermore,
1079 the defaults cannot be turned off, so you are stuck with them.
1081 In most cases, what you should actually be using are project-specific methods:
1083 package My::Schema::ResultSet::Artist;
1084 use base 'DBIx::Class::ResultSet';
1088 #__PACKAGE__->resultset_attributes({ prefetch => 'tracks' });
1091 sub with_tracks { shift->search({}, { prefetch => 'tracks' }) }
1094 $schema->resultset('Artist')->with_tracks->...
1096 This gives you the flexibility of not using it when you don't need it.
1098 For more complex situations, another solution would be to use a virtual view
1099 via L<DBIx::Class::ResultSource::View>.
1105 $self->throw_exception(
1106 'resultset does not take any arguments. If you want another resultset, '.
1107 'call it on the schema instead.'
1110 $self->resultset_class->new(
1113 try { %{$self->schema->default_resultset_attributes} },
1114 %{$self->{resultset_attributes}},
1123 =item Arguments: none
1125 =item Result value: $name
1129 Returns the name of the result source, which will typically be the table
1130 name. This may be a scalar reference if the result source has a non-standard
1137 =item Arguments: $source_name
1139 =item Result value: $source_name
1143 Set an alternate name for the result source when it is loaded into a schema.
1144 This is useful if you want to refer to a result source by a name other than
1147 package ArchivedBooks;
1148 use base qw/DBIx::Class/;
1149 __PACKAGE__->table('books_archive');
1150 __PACKAGE__->source_name('Books');
1152 # from your schema...
1153 $schema->resultset('Books')->find(1);
1159 =item Arguments: none
1161 =item Return Value: FROM clause
1165 my $from_clause = $source->from();
1167 Returns an expression of the source to be supplied to storage to specify
1168 retrieval from this source. In the case of a database, the required FROM
1173 sub from { die 'Virtual method!' }
1179 =item Arguments: L<$schema?|DBIx::Class::Schema>
1181 =item Return Value: L<$schema|DBIx::Class::Schema>
1185 my $schema = $source->schema();
1187 Sets and/or returns the L<DBIx::Class::Schema> object to which this
1188 result source instance has been attached to.
1194 $_[0]->{schema} = $_[1];
1197 $_[0]->{schema} || do {
1198 my $name = $_[0]->{source_name} || '_unnamed_';
1199 my $err = 'Unable to perform storage-dependent operations with a detached result source '
1200 . "(source '$name' is not associated with a schema).";
1202 $err .= ' You need to use $schema->thaw() or manually set'
1203 . ' $DBIx::Class::ResultSourceHandle::thaw_schema while thawing.'
1204 if $_[0]->{_detached_thaw};
1206 DBIx::Class::Exception->throw($err);
1215 =item Arguments: none
1217 =item Return Value: L<$storage|DBIx::Class::Storage>
1221 $source->storage->debug(1);
1223 Returns the L<storage handle|DBIx::Class::Storage> for the current schema.
1227 sub storage { shift->schema->storage; }
1229 =head2 add_relationship
1233 =item Arguments: $rel_name, $related_source_name, \%cond, \%attrs?
1235 =item Return Value: 1/true if it succeeded
1239 $source->add_relationship('rel_name', 'related_source', $cond, $attrs);
1241 L<DBIx::Class::Relationship> describes a series of methods which
1242 create pre-defined useful types of relationships. Look there first
1243 before using this method directly.
1245 The relationship name can be arbitrary, but must be unique for each
1246 relationship attached to this result source. 'related_source' should
1247 be the name with which the related result source was registered with
1248 the current schema. For example:
1250 $schema->source('Book')->add_relationship('reviews', 'Review', {
1251 'foreign.book_id' => 'self.id',
1254 The condition C<$cond> needs to be an L<SQL::Abstract>-style
1255 representation of the join between the tables. For example, if you're
1256 creating a relation from Author to Book,
1258 { 'foreign.author_id' => 'self.id' }
1260 will result in the JOIN clause
1262 author me JOIN book foreign ON foreign.author_id = me.id
1264 You can specify as many foreign => self mappings as necessary.
1266 Valid attributes are as follows:
1272 Explicitly specifies the type of join to use in the relationship. Any
1273 SQL join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in
1274 the SQL command immediately before C<JOIN>.
1278 An arrayref containing a list of accessors in the foreign class to proxy in
1279 the main class. If, for example, you do the following:
1281 CD->might_have(liner_notes => 'LinerNotes', undef, {
1282 proxy => [ qw/notes/ ],
1285 Then, assuming LinerNotes has an accessor named notes, you can do:
1287 my $cd = CD->find(1);
1288 # set notes -- LinerNotes object is created if it doesn't exist
1289 $cd->notes('Notes go here');
1293 Specifies the type of accessor that should be created for the
1294 relationship. Valid values are C<single> (for when there is only a single
1295 related object), C<multi> (when there can be many), and C<filter> (for
1296 when there is a single related object, but you also want the relationship
1297 accessor to double as a column accessor). For C<multi> accessors, an
1298 add_to_* method is also created, which calls C<create_related> for the
1303 Throws an exception if the condition is improperly supplied, or cannot
1308 sub add_relationship {
1309 my ($self, $rel, $f_source_name, $cond, $attrs) = @_;
1310 $self->throw_exception("Can't create relationship without join condition")
1314 # Check foreign and self are right in cond
1315 if ( (ref $cond ||'') eq 'HASH') {
1317 $self->throw_exception("Keys of condition should be of form 'foreign.col', not '$_'")
1318 if /\./ && !/^foreign\./;
1322 my %rels = %{ $self->_relationships };
1323 $rels{$rel} = { class => $f_source_name,
1324 source => $f_source_name,
1327 $self->_relationships(\%rels);
1331 # XXX disabled. doesn't work properly currently. skip in tests.
1333 my $f_source = $self->schema->source($f_source_name);
1334 unless ($f_source) {
1335 $self->ensure_class_loaded($f_source_name);
1336 $f_source = $f_source_name->result_source;
1337 #my $s_class = ref($self->schema);
1338 #$f_source_name =~ m/^${s_class}::(.*)$/;
1339 #$self->schema->register_class(($1 || $f_source_name), $f_source_name);
1340 #$f_source = $self->schema->source($f_source_name);
1342 return unless $f_source; # Can't test rel without f_source
1344 try { $self->_resolve_join($rel, 'me', {}, []) }
1346 # If the resolve failed, back out and re-throw the error
1348 $self->_relationships(\%rels);
1349 $self->throw_exception("Error creating relationship $rel: $_");
1355 =head2 relationships
1359 =item Arguments: none
1361 =item Return Value: L<@rel_names|DBIx::Class::Relationship>
1365 my @relnames = $source->relationships();
1367 Returns all relationship names for this source.
1372 return keys %{shift->_relationships};
1375 =head2 relationship_info
1379 =item Arguments: L<$rel_name|DBIx::Class::Relationship>
1381 =item Return Value: L<\%rel_data|DBIx::Class::Relationship::Base/add_relationship>
1385 Returns a hash of relationship information for the specified relationship
1386 name. The keys/values are as specified for L<DBIx::Class::Relationship::Base/add_relationship>.
1390 sub relationship_info {
1391 #my ($self, $rel) = @_;
1392 return shift->_relationships->{+shift};
1395 =head2 has_relationship
1399 =item Arguments: L<$rel_name|DBIx::Class::Relationship>
1401 =item Return Value: 1/0 (true/false)
1405 Returns true if the source has a relationship of this name, false otherwise.
1409 sub has_relationship {
1410 #my ($self, $rel) = @_;
1411 return exists shift->_relationships->{+shift};
1414 =head2 reverse_relationship_info
1418 =item Arguments: L<$rel_name|DBIx::Class::Relationship>
1420 =item Return Value: L<\%rel_data|DBIx::Class::Relationship::Base/add_relationship>
1424 Looks through all the relationships on the source this relationship
1425 points to, looking for one whose condition is the reverse of the
1426 condition on this relationship.
1428 A common use of this is to find the name of the C<belongs_to> relation
1429 opposing a C<has_many> relation. For definition of these look in
1430 L<DBIx::Class::Relationship>.
1432 The returned hashref is keyed by the name of the opposing
1433 relationship, and contains its data in the same manner as
1434 L</relationship_info>.
1438 sub reverse_relationship_info {
1439 my ($self, $rel) = @_;
1441 my $rel_info = $self->relationship_info($rel)
1442 or $self->throw_exception("No such relationship '$rel'");
1446 return $ret unless ((ref $rel_info->{cond}) eq 'HASH');
1448 my $stripped_cond = $self->__strip_relcond ($rel_info->{cond});
1450 my $registered_source_name = $self->source_name;
1452 # this may be a partial schema or something else equally esoteric
1453 my $other_rsrc = $self->related_source($rel);
1455 # Get all the relationships for that source that related to this source
1456 # whose foreign column set are our self columns on $rel and whose self
1457 # columns are our foreign columns on $rel
1458 foreach my $other_rel ($other_rsrc->relationships) {
1460 # only consider stuff that points back to us
1461 # "us" here is tricky - if we are in a schema registration, we want
1462 # to use the source_names, otherwise we will use the actual classes
1464 # the schema may be partial
1465 my $roundtrip_rsrc = try { $other_rsrc->related_source($other_rel) }
1468 if ($registered_source_name) {
1469 next if $registered_source_name ne ($roundtrip_rsrc->source_name || '')
1472 next if $self->result_class ne $roundtrip_rsrc->result_class;
1475 my $other_rel_info = $other_rsrc->relationship_info($other_rel);
1477 # this can happen when we have a self-referential class
1478 next if $other_rel_info eq $rel_info;
1480 next unless ref $other_rel_info->{cond} eq 'HASH';
1481 my $other_stripped_cond = $self->__strip_relcond($other_rel_info->{cond});
1483 $ret->{$other_rel} = $other_rel_info if (
1484 $self->_compare_relationship_keys (
1485 [ keys %$stripped_cond ], [ values %$other_stripped_cond ]
1488 $self->_compare_relationship_keys (
1489 [ values %$stripped_cond ], [ keys %$other_stripped_cond ]
1497 # all this does is removes the foreign/self prefix from a condition
1498 sub __strip_relcond {
1501 { map { /^ (?:foreign|self) \. (\w+) $/x } ($_, $_[1]{$_}) }
1506 sub compare_relationship_keys {
1507 carp 'compare_relationship_keys is a private method, stop calling it';
1509 $self->_compare_relationship_keys (@_);
1512 # Returns true if both sets of keynames are the same, false otherwise.
1513 sub _compare_relationship_keys {
1514 # my ($self, $keys1, $keys2) = @_;
1516 join ("\x00", sort @{$_[1]})
1518 join ("\x00", sort @{$_[2]})
1522 # optionally takes either an arrayref of column names, or a hashref of already
1523 # retrieved colinfos
1524 # returns an arrayref of column names of the shortest unique constraint
1525 # (matching some of the input if any), giving preference to the PK
1526 sub _identifying_column_set {
1527 my ($self, $cols) = @_;
1529 my %unique = $self->unique_constraints;
1530 my $colinfos = ref $cols eq 'HASH' ? $cols : $self->columns_info($cols||());
1532 # always prefer the PK first, and then shortest constraints first
1534 for my $set (delete $unique{primary}, sort { @$a <=> @$b } (values %unique) ) {
1535 next unless $set && @$set;
1538 next USET unless ($colinfos->{$_} && !$colinfos->{$_}{is_nullable} );
1541 # copy so we can mangle it at will
1548 # Returns the {from} structure used to express JOIN conditions
1550 my ($self, $join, $alias, $seen, $jpath, $parent_force_left) = @_;
1552 # we need a supplied one, because we do in-place modifications, no returns
1553 $self->throw_exception ('You must supply a seen hashref as the 3rd argument to _resolve_join')
1554 unless ref $seen eq 'HASH';
1556 $self->throw_exception ('You must supply a joinpath arrayref as the 4th argument to _resolve_join')
1557 unless ref $jpath eq 'ARRAY';
1559 $jpath = [@$jpath]; # copy
1561 if (not defined $join or not length $join) {
1564 elsif (ref $join eq 'ARRAY') {
1567 $self->_resolve_join($_, $alias, $seen, $jpath, $parent_force_left);
1570 elsif (ref $join eq 'HASH') {
1573 for my $rel (keys %$join) {
1575 my $rel_info = $self->relationship_info($rel)
1576 or $self->throw_exception("No such relationship '$rel' on " . $self->source_name);
1578 my $force_left = $parent_force_left;
1579 $force_left ||= lc($rel_info->{attrs}{join_type}||'') eq 'left';
1581 # the actual seen value will be incremented by the recursion
1582 my $as = $self->storage->relname_to_table_alias(
1583 $rel, ($seen->{$rel} && $seen->{$rel} + 1)
1587 $self->_resolve_join($rel, $alias, $seen, [@$jpath], $force_left),
1588 $self->related_source($rel)->_resolve_join(
1589 $join->{$rel}, $as, $seen, [@$jpath, { $rel => $as }], $force_left
1597 $self->throw_exception("No idea how to resolve join reftype ".ref $join);
1600 my $count = ++$seen->{$join};
1601 my $as = $self->storage->relname_to_table_alias(
1602 $join, ($count > 1 && $count)
1605 my $rel_info = $self->relationship_info($join)
1606 or $self->throw_exception("No such relationship $join on " . $self->source_name);
1608 my $rel_src = $self->related_source($join);
1609 return [ { $as => $rel_src->from,
1611 -join_type => $parent_force_left
1613 : $rel_info->{attrs}{join_type}
1615 -join_path => [@$jpath, { $join => $as } ],
1617 (! $rel_info->{attrs}{accessor})
1619 first { $rel_info->{attrs}{accessor} eq $_ } (qw/single filter/)
1622 -relation_chain_depth => ( $seen->{-relation_chain_depth} || 0 ) + 1,
1624 scalar $self->_resolve_condition($rel_info->{cond}, $as, $alias, $join)
1630 carp 'pk_depends_on is a private method, stop calling it';
1632 $self->_pk_depends_on (@_);
1635 # Determines whether a relation is dependent on an object from this source
1636 # having already been inserted. Takes the name of the relationship and a
1637 # hashref of columns of the related object.
1638 sub _pk_depends_on {
1639 my ($self, $rel_name, $rel_data) = @_;
1641 my $relinfo = $self->relationship_info($rel_name);
1643 # don't assume things if the relationship direction is specified
1644 return $relinfo->{attrs}{is_foreign_key_constraint}
1645 if exists ($relinfo->{attrs}{is_foreign_key_constraint});
1647 my $cond = $relinfo->{cond};
1648 return 0 unless ref($cond) eq 'HASH';
1650 # map { foreign.foo => 'self.bar' } to { bar => 'foo' }
1651 my $keyhash = { map { my $x = $_; $x =~ s/.*\.//; $x; } reverse %$cond };
1653 # assume anything that references our PK probably is dependent on us
1654 # rather than vice versa, unless the far side is (a) defined or (b)
1656 my $rel_source = $self->related_source($rel_name);
1658 foreach my $p ($self->primary_columns) {
1659 if (exists $keyhash->{$p}) {
1660 unless (defined($rel_data->{$keyhash->{$p}})
1661 || $rel_source->column_info($keyhash->{$p})
1662 ->{is_auto_increment}) {
1671 sub resolve_condition {
1672 carp 'resolve_condition is a private method, stop calling it';
1674 $self->_resolve_condition (@_);
1677 our $UNRESOLVABLE_CONDITION = \ '1 = 0';
1679 # Resolves the passed condition to a concrete query fragment and a flag
1680 # indicating whether this is a cross-table condition. Also an optional
1681 # list of non-trivial values (normally conditions) returned as a part
1682 # of a joinfree condition hash
1683 sub _resolve_condition {
1684 my ($self, $cond, $as, $for, $rel_name) = @_;
1686 my $obj_rel = defined blessed $for;
1688 if (ref $cond eq 'CODE') {
1689 my $relalias = $obj_rel ? 'me' : $as;
1691 my ($crosstable_cond, $joinfree_cond) = $cond->({
1692 self_alias => $obj_rel ? $as : $for,
1693 foreign_alias => $relalias,
1694 self_resultsource => $self,
1695 foreign_relname => $rel_name || ($obj_rel ? $as : $for),
1696 self_rowobj => $obj_rel ? $for : undef
1700 if ($joinfree_cond) {
1702 # FIXME sanity check until things stabilize, remove at some point
1703 $self->throw_exception (
1704 "A join-free condition returned for relationship '$rel_name' without a row-object to chain from"
1707 # FIXME another sanity check
1709 ref $joinfree_cond ne 'HASH'
1711 first { $_ !~ /^\Q$relalias.\E.+/ } keys %$joinfree_cond
1713 $self->throw_exception (
1714 "The join-free condition returned for relationship '$rel_name' must be a hash "
1715 .'reference with all keys being valid columns on the related result source'
1720 for (values %$joinfree_cond) {
1730 # see which parts of the joinfree cond are conditionals
1731 my $relcol_list = { map { $_ => 1 } $self->related_source($rel_name)->columns };
1733 for my $c (keys %$joinfree_cond) {
1734 my ($colname) = $c =~ /^ (?: \Q$relalias.\E )? (.+)/x;
1736 unless ($relcol_list->{$colname}) {
1737 push @$cond_cols, $colname;
1742 ref $joinfree_cond->{$c}
1744 ref $joinfree_cond->{$c} ne 'SCALAR'
1746 ref $joinfree_cond->{$c} ne 'REF'
1748 push @$cond_cols, $colname;
1753 return wantarray ? ($joinfree_cond, 0, $cond_cols) : $joinfree_cond;
1756 return wantarray ? ($crosstable_cond, 1) : $crosstable_cond;
1759 elsif (ref $cond eq 'HASH') {
1761 foreach my $k (keys %{$cond}) {
1762 my $v = $cond->{$k};
1763 # XXX should probably check these are valid columns
1764 $k =~ s/^foreign\.// ||
1765 $self->throw_exception("Invalid rel cond key ${k}");
1766 $v =~ s/^self\.// ||
1767 $self->throw_exception("Invalid rel cond val ${v}");
1768 if (ref $for) { # Object
1769 #warn "$self $k $for $v";
1770 unless ($for->has_column_loaded($v)) {
1771 if ($for->in_storage) {
1772 $self->throw_exception(sprintf
1773 "Unable to resolve relationship '%s' from object %s: column '%s' not "
1774 . 'loaded from storage (or not passed to new() prior to insert()). You '
1775 . 'probably need to call ->discard_changes to get the server-side defaults '
1776 . 'from the database.',
1782 return $UNRESOLVABLE_CONDITION;
1784 $ret{$k} = $for->get_column($v);
1785 #$ret{$k} = $for->get_column($v) if $for->has_column_loaded($v);
1787 } elsif (!defined $for) { # undef, i.e. "no object"
1789 } elsif (ref $as eq 'HASH') { # reverse hashref
1790 $ret{$v} = $as->{$k};
1791 } elsif (ref $as) { # reverse object
1792 $ret{$v} = $as->get_column($k);
1793 } elsif (!defined $as) { # undef, i.e. "no reverse object"
1796 $ret{"${as}.${k}"} = { -ident => "${for}.${v}" };
1801 ? ( \%ret, ($obj_rel || !defined $as || ref $as) ? 0 : 1 )
1805 elsif (ref $cond eq 'ARRAY') {
1806 my (@ret, $crosstable);
1808 my ($cond, $crosstab) = $self->_resolve_condition($_, $as, $for, $rel_name);
1810 $crosstable ||= $crosstab;
1812 return wantarray ? (\@ret, $crosstable) : \@ret;
1815 $self->throw_exception ("Can't handle condition $cond for relationship '$rel_name' yet :(");
1819 =head2 related_source
1823 =item Arguments: $rel_name
1825 =item Return Value: $source
1829 Returns the result source object for the given relationship.
1833 sub related_source {
1834 my ($self, $rel) = @_;
1835 if( !$self->has_relationship( $rel ) ) {
1836 $self->throw_exception("No such relationship '$rel' on " . $self->source_name);
1839 # if we are not registered with a schema - just use the prototype
1840 # however if we do have a schema - ask for the source by name (and
1841 # throw in the process if all fails)
1842 if (my $schema = try { $self->schema }) {
1843 $schema->source($self->relationship_info($rel)->{source});
1846 my $class = $self->relationship_info($rel)->{class};
1847 $self->ensure_class_loaded($class);
1848 $class->result_source_instance;
1852 =head2 related_class
1856 =item Arguments: $rel_name
1858 =item Return Value: $classname
1862 Returns the class name for objects in the given relationship.
1867 my ($self, $rel) = @_;
1868 if( !$self->has_relationship( $rel ) ) {
1869 $self->throw_exception("No such relationship '$rel' on " . $self->source_name);
1871 return $self->schema->class($self->relationship_info($rel)->{source});
1878 =item Arguments: none
1880 =item Return Value: L<$source_handle|DBIx::Class::ResultSourceHandle>
1884 Obtain a new L<result source handle instance|DBIx::Class::ResultSourceHandle>
1885 for this source. Used as a serializable pointer to this resultsource, as it is not
1886 easy (nor advisable) to serialize CODErefs which may very well be present in e.g.
1887 relationship definitions.
1892 return DBIx::Class::ResultSourceHandle->new({
1893 source_moniker => $_[0]->source_name,
1895 # so that a detached thaw can be re-frozen
1896 $_[0]->{_detached_thaw}
1897 ? ( _detached_source => $_[0] )
1898 : ( schema => $_[0]->schema )
1903 my $global_phase_destroy;
1905 return if $global_phase_destroy ||= in_global_destruction;
1911 # Under no circumstances shall $_[0] be stored anywhere else (like copied to
1912 # a lexical variable, or shifted, or anything else). Doing so will mess up
1913 # the refcount of this particular result source, and will allow the $schema
1914 # we are trying to save to reattach back to the source we are destroying.
1915 # The relevant code checking refcounts is in ::Schema::DESTROY()
1917 # if we are not a schema instance holder - we don't matter
1919 ! ref $_[0]->{schema}
1921 isweak $_[0]->{schema}
1924 # weaken our schema hold forcing the schema to find somewhere else to live
1925 # during global destruction (if we have not yet bailed out) this will throw
1926 # which will serve as a signal to not try doing anything else
1927 # however beware - on older perls the exception seems randomly untrappable
1928 # due to some weird race condition during thread joining :(((
1931 weaken $_[0]->{schema};
1933 # if schema is still there reintroduce ourselves with strong refs back to us
1934 if ($_[0]->{schema}) {
1935 my $srcregs = $_[0]->{schema}->source_registrations;
1936 for (keys %$srcregs) {
1937 next unless $srcregs->{$_};
1938 $srcregs->{$_} = $_[0] if $srcregs->{$_} == $_[0];
1944 $global_phase_destroy = 1;
1950 sub STORABLE_freeze { Storable::nfreeze($_[0]->handle) }
1953 my ($self, $cloning, $ice) = @_;
1954 %$self = %{ (Storable::thaw($ice))->resolve };
1957 =head2 throw_exception
1959 See L<DBIx::Class::Schema/"throw_exception">.
1963 sub throw_exception {
1967 ? $self->{schema}->throw_exception(@_)
1968 : DBIx::Class::Exception->throw(@_)
1974 Stores a hashref of per-source metadata. No specific key names
1975 have yet been standardized, the examples below are purely hypothetical
1976 and don't actually accomplish anything on their own:
1978 __PACKAGE__->source_info({
1979 "_tablespace" => 'fast_disk_array_3',
1980 "_engine" => 'InnoDB',
1987 $class->new({attribute_name => value});
1989 Creates a new ResultSource object. Not normally called directly by end users.
1991 =head2 column_info_from_storage
1995 =item Arguments: 1/0 (default: 0)
1997 =item Return Value: 1/0
2001 __PACKAGE__->column_info_from_storage(1);
2003 Enables the on-demand automatic loading of the above column
2004 metadata from storage as necessary. This is *deprecated*, and
2005 should not be used. It will be removed before 1.0.
2008 =head1 AUTHOR AND CONTRIBUTORS
2010 See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
2014 You may distribute this code under the same terms as Perl itself.