1 package DBIx::Class::Row;
6 use base qw/DBIx::Class/;
8 use Scalar::Util 'blessed';
9 use DBIx::Class::_Util 'dbic_internal_try';
10 use DBIx::Class::Carp;
11 use SQL::Abstract qw( is_literal_value is_plain_value );
19 $ENV{DBIC_MULTICREATE_DEBUG}
26 __PACKAGE__->mk_group_accessors ( simple => [ in_storage => '_in_storage' ] );
30 DBIx::Class::Row - Basic row methods
36 This class is responsible for defining and doing basic operations on rows
37 derived from L<DBIx::Class::ResultSource> objects.
39 Result objects are returned from L<DBIx::Class::ResultSet>s using the
40 L<create|DBIx::Class::ResultSet/create>, L<find|DBIx::Class::ResultSet/find>,
41 L<next|DBIx::Class::ResultSet/next> and L<all|DBIx::Class::ResultSet/all> methods,
42 as well as invocations of 'single' (
43 L<belongs_to|DBIx::Class::Relationship/belongs_to>,
44 L<has_one|DBIx::Class::Relationship/has_one> or
45 L<might_have|DBIx::Class::Relationship/might_have>)
46 relationship accessors of L<Result|DBIx::Class::Manual::ResultClass> objects.
50 All "Row objects" derived from a Schema-attached L<DBIx::Class::ResultSet>
51 object (such as a typical C<< L<search|DBIx::Class::ResultSet/search>->
52 L<next|DBIx::Class::ResultSet/next> >> call) are actually Result
53 instances, based on your application's
54 L<Result Class|DBIx::Class::Manual::Glossary/Result Class>.
56 L<DBIx::Class::Row> implements most of the row-based communication with the
57 underlying storage, but a Result class B<should not inherit from it directly>.
58 Usually, Result classes inherit from L<DBIx::Class::Core>, which in turn
59 combines the methods from several classes, one of them being
60 L<DBIx::Class::Row>. Therefore, while many of the methods available to a
61 L<DBIx::Class::Core>-derived Result class are described in the following
62 documentation, it does not detail all of the methods available to Result
63 objects. Refer to L<DBIx::Class::Manual::ResultClass> for more info.
69 my $result = My::Class->new(\%attrs);
71 my $result = $schema->resultset('MySource')->new(\%colsandvalues);
75 =item Arguments: \%attrs or \%colsandvalues
77 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
81 While you can create a new result object by calling C<new> directly on
82 this class, you are better off calling it on a
83 L<DBIx::Class::ResultSet> object.
85 When calling it directly, you will not get a complete, usable row
86 object until you pass or set the C<result_source> attribute, to a
87 L<DBIx::Class::ResultSource> instance that is attached to a
88 L<DBIx::Class::Schema> with a valid connection.
90 C<$attrs> is a hashref of column name, value data. It can also contain
91 some other attributes such as the C<result_source>.
93 Passing an object, or an arrayref of objects as a value will call
94 L<DBIx::Class::Relationship::Base/set_from_related> for you. When
95 passed a hashref or an arrayref of hashrefs as the value, these will
96 be turned into objects via new_related, and treated as if you had
99 For a more involved explanation, see L<DBIx::Class::ResultSet/create>.
101 Please note that if a value is not passed to new, no value will be sent
102 in the SQL INSERT call, and the column will therefore assume whatever
103 default value was specified in your database. While DBIC will retrieve the
104 value of autoincrement columns, it will never make an explicit database
105 trip to retrieve default values assigned by the RDBMS. You can explicitly
106 request that all values be fetched back from the database by calling
107 L</discard_changes>, or you can supply an explicit C<undef> to columns
108 with NULL as the default, and save yourself a SELECT.
112 The behavior described above will backfire if you use a foreign key column
113 with a database-defined default. If you call the relationship accessor on
114 an object that doesn't have a set value for the FK column, DBIC will throw
115 an exception, as it has no way of knowing the PK of the related object (if
120 ## It needs to store the new objects somewhere, and call insert on that list later when insert is called on this object. We may need an accessor for these so the user can retrieve them, if just doing ->new().
121 ## This only works because DBIC doesn't yet care to check whether the new_related objects have been passed all their mandatory columns
122 ## When doing the later insert, we need to make sure the PKs are set.
123 ## using _relationship_data in new and funky ways..
124 ## check Relationship::CascadeActions and Relationship::Accessor for compat
127 sub __new_related_find_or_new_helper {
128 my ($self, $rel_name, $values) = @_;
130 my $rsrc = $self->result_source;
132 # create a mock-object so all new/set_column component overrides will run:
133 my $rel_rs = $rsrc->related_source($rel_name)->resultset;
134 my $new_rel_obj = $rel_rs->new_result($values);
135 my $proc_data = { $new_rel_obj->get_columns };
137 if ($self->__their_pk_needs_us($rel_name)) {
138 MULTICREATE_DEBUG and print STDERR "MC $self constructing $rel_name via new_result\n";
141 elsif ($rsrc->_pk_depends_on($rel_name, $proc_data )) {
142 if (! keys %$proc_data) {
143 # there is nothing to search for - blind create
144 MULTICREATE_DEBUG and print STDERR "MC $self constructing default-insert $rel_name\n";
147 MULTICREATE_DEBUG and print STDERR "MC $self constructing $rel_name via find_or_new\n";
148 # this is not *really* find or new, as we don't want to double-new the
149 # data (thus potentially double encoding or whatever)
150 my $exists = $rel_rs->find ($proc_data);
151 return $exists if $exists;
156 my $us = $rsrc->source_name;
157 $self->throw_exception (
158 "Unable to determine relationship '$rel_name' direction from '$us', "
159 . "possibly due to a missing reverse-relationship on '$rel_name' to '$us'."
164 sub __their_pk_needs_us { # this should maybe be in resultsource.
165 my ($self, $rel_name) = @_;
166 my $rsrc = $self->result_source;
167 my $reverse = $rsrc->reverse_relationship_info($rel_name);
168 my $rel_source = $rsrc->related_source($rel_name);
169 my $us = { $self->get_columns };
170 foreach my $key (keys %$reverse) {
171 # if their primary key depends on us, then we have to
172 # just create a result and we'll fill it out afterwards
173 return 1 if $rel_source->_pk_depends_on($key, $us);
179 my ($class, $attrs) = @_;
180 $class = ref $class if ref $class;
182 my $new = bless { _column_data => {}, _in_storage => 0 }, $class;
185 $new->throw_exception("attrs must be a hashref")
186 unless ref($attrs) eq 'HASH';
188 my $rsrc = delete $attrs->{-result_source};
189 if ( my $h = delete $attrs->{-source_handle} ) {
190 $rsrc ||= $h->resolve;
193 $new->result_source($rsrc) if $rsrc;
195 if (my $col_from_rel = delete $attrs->{-cols_from_relations}) {
196 @{$new->{_ignore_at_insert}={}}{@$col_from_rel} = ();
199 my ($related,$inflated);
201 foreach my $key (keys %$attrs) {
202 if (ref $attrs->{$key} and ! is_literal_value($attrs->{$key}) ) {
203 ## Can we extract this lot to use with update(_or .. ) ?
204 $new->throw_exception("Can't do multi-create without result source")
206 my $info = $rsrc->relationship_info($key);
207 my $acc_type = $info->{attrs}{accessor} || '';
208 if ($acc_type eq 'single') {
209 my $rel_obj = delete $attrs->{$key};
210 if(!blessed $rel_obj) {
211 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
214 if ($rel_obj->in_storage) {
215 $new->{_rel_in_storage}{$key} = 1;
216 $new->set_from_related($key, $rel_obj);
218 MULTICREATE_DEBUG and print STDERR "MC $new uninserted $key $rel_obj\n";
221 $related->{$key} = $rel_obj;
224 elsif ($acc_type eq 'multi' && ref $attrs->{$key} eq 'ARRAY' ) {
225 my $others = delete $attrs->{$key};
226 my $total = @$others;
228 foreach my $idx (0 .. $#$others) {
229 my $rel_obj = $others->[$idx];
230 if(!blessed $rel_obj) {
231 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
234 if ($rel_obj->in_storage) {
235 $rel_obj->throw_exception ('A multi relationship can not be pre-existing when doing multicreate. Something went wrong');
237 MULTICREATE_DEBUG and
238 print STDERR "MC $new uninserted $key $rel_obj (${\($idx+1)} of $total)\n";
240 push(@objects, $rel_obj);
242 $related->{$key} = \@objects;
245 elsif ($acc_type eq 'filter') {
246 ## 'filter' should disappear and get merged in with 'single' above!
247 my $rel_obj = delete $attrs->{$key};
248 if(!blessed $rel_obj) {
249 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
251 if ($rel_obj->in_storage) {
252 $new->{_rel_in_storage}{$key} = 1;
255 MULTICREATE_DEBUG and print STDERR "MC $new uninserted $key $rel_obj\n";
257 $inflated->{$key} = $rel_obj;
261 $rsrc->has_column($key)
263 $rsrc->column_info($key)->{_inflate_info}
265 $inflated->{$key} = $attrs->{$key};
269 $new->store_column($key => $attrs->{$key});
272 $new->{_relationship_data} = $related if $related;
273 $new->{_inflated_column} = $inflated if $inflated;
279 =head2 $column_accessor
281 # Each pair does the same thing
283 # (un-inflated, regular column)
284 my $val = $result->get_column('first_name');
285 my $val = $result->first_name;
287 $result->set_column('first_name' => $val);
288 $result->first_name($val);
290 # (inflated column via DBIx::Class::InflateColumn::DateTime)
291 my $val = $result->get_inflated_column('last_modified');
292 my $val = $result->last_modified;
294 $result->set_inflated_column('last_modified' => $val);
295 $result->last_modified($val);
299 =item Arguments: $value?
301 =item Return Value: $value
305 A column accessor method is created for each column, which is used for
306 getting/setting the value for that column.
308 The actual method name is based on the
309 L<accessor|DBIx::Class::ResultSource/accessor> name given during the
310 L<Result Class|DBIx::Class::Manual::ResultClass> L<column definition
311 |DBIx::Class::ResultSource/add_columns>. Like L</set_column>, this
312 will not store the data in the database until L</insert> or L</update>
313 is called on the row.
321 =item Arguments: none
323 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
327 Inserts an object previously created by L</new> into the database if
328 it isn't already in there. Returns the object itself. To insert an
329 entirely new row into the database, use L<DBIx::Class::ResultSet/create>.
331 To fetch an uninserted result object, call
332 L<new_result|DBIx::Class::ResultSet/new_result> on a resultset.
334 This will also insert any uninserted, related objects held inside this
335 one, see L<DBIx::Class::ResultSet/create> for more details.
341 return $self if $self->in_storage;
342 my $rsrc = $self->result_source;
343 $self->throw_exception("No result_source set on this object; can't insert")
346 my $storage = $rsrc->storage;
350 # Check if we stored uninserted relobjs here in new()
351 my %related_stuff = (%{$self->{_relationship_data} || {}},
352 %{$self->{_inflated_column} || {}});
354 # insert what needs to be inserted before us
356 for my $rel_name (keys %related_stuff) {
357 my $rel_obj = $related_stuff{$rel_name};
359 if (! $self->{_rel_in_storage}{$rel_name}) {
360 next unless (blessed $rel_obj && $rel_obj->isa('DBIx::Class::Row'));
362 next unless $rsrc->_pk_depends_on(
363 $rel_name, { $rel_obj->get_columns }
366 # The guard will save us if we blow out of this scope via die
367 $rollback_guard ||= $storage->txn_scope_guard;
369 MULTICREATE_DEBUG and print STDERR "MC $self pre-reconstructing $rel_name $rel_obj\n";
371 my $them = { %{$rel_obj->{_relationship_data} || {} }, $rel_obj->get_columns };
374 # if there are no keys - nothing to search for
375 if (keys %$them and $existing = $rsrc->related_source($rel_name)
379 %{$rel_obj} = %{$existing};
385 $self->{_rel_in_storage}{$rel_name} = 1;
388 $self->set_from_related($rel_name, $rel_obj);
389 delete $related_stuff{$rel_name};
392 # start a transaction here if not started yet and there is more stuff
394 if (keys %related_stuff) {
395 $rollback_guard ||= $storage->txn_scope_guard
398 MULTICREATE_DEBUG and do {
399 no warnings 'uninitialized';
400 print STDERR "MC $self inserting (".join(', ', $self->get_columns).")\n";
403 # perform the insert - the storage will return everything it is asked to
404 # (autoinc primary columns and any retrieve_on_insert columns)
405 my %current_rowdata = $self->get_columns;
406 my $returned_cols = $storage->insert(
408 { %current_rowdata }, # what to insert, copy because the storage *will* change it
411 for (keys %$returned_cols) {
412 $self->store_column($_, $returned_cols->{$_})
413 # this ensures we fire store_column only once
414 # (some asshats like overriding it)
416 (!exists $current_rowdata{$_})
418 (defined $current_rowdata{$_} xor defined $returned_cols->{$_})
420 (defined $current_rowdata{$_} and $current_rowdata{$_} ne $returned_cols->{$_})
424 delete $self->{_column_data_in_storage};
425 $self->in_storage(1);
427 $self->{_dirty_columns} = {};
428 $self->{related_resultsets} = {};
430 foreach my $rel_name (keys %related_stuff) {
431 next unless $rsrc->has_relationship ($rel_name);
433 my @cands = ref $related_stuff{$rel_name} eq 'ARRAY'
434 ? @{$related_stuff{$rel_name}}
435 : $related_stuff{$rel_name}
438 if (@cands && blessed $cands[0] && $cands[0]->isa('DBIx::Class::Row')
440 my $reverse = $rsrc->reverse_relationship_info($rel_name);
441 foreach my $obj (@cands) {
442 $obj->set_from_related($_, $self) for keys %$reverse;
443 if ($self->__their_pk_needs_us($rel_name)) {
444 if (exists $self->{_ignore_at_insert}{$rel_name}) {
445 MULTICREATE_DEBUG and print STDERR "MC $self skipping post-insert on $rel_name\n";
448 MULTICREATE_DEBUG and print STDERR "MC $self inserting $rel_name $obj\n";
452 MULTICREATE_DEBUG and print STDERR "MC $self post-inserting $obj\n";
459 delete $self->{_ignore_at_insert};
461 $rollback_guard->commit if $rollback_guard;
468 $result->in_storage; # Get value
469 $result->in_storage(1); # Set value
473 =item Arguments: none or 1|0
475 =item Return Value: 1|0
479 Indicates whether the object exists as a row in the database or
480 not. This is set to true when L<DBIx::Class::ResultSet/find>,
481 L<DBIx::Class::ResultSet/create> or L<DBIx::Class::Row/insert>
484 Creating a result object using L<DBIx::Class::ResultSet/new_result>, or
485 calling L</delete> on one, sets it to false.
490 $result->update(\%columns?)
494 =item Arguments: none or a hashref
496 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
500 Throws an exception if the result object is not yet in the database,
501 according to L</in_storage>. Returns the object itself.
503 This method issues an SQL UPDATE query to commit any changes to the
504 object to the database if required (see L</get_dirty_columns>).
505 It throws an exception if a proper WHERE clause uniquely identifying
506 the database row can not be constructed (see
507 L<significance of primary keys|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
510 Also takes an optional hashref of C<< column_name => value >> pairs
511 to update on the object first. Be aware that the hashref will be
512 passed to C<set_inflated_columns>, which might edit it in place, so
513 don't rely on it being the same after a call to C<update>. If you
514 need to preserve the hashref, it is sufficient to pass a shallow copy
515 to C<update>, e.g. ( { %{ $href } } )
517 If the values passed or any of the column values set on the object
518 contain scalar references, e.g.:
520 $result->last_modified(\'NOW()')->update();
522 $result->update({ last_modified => \'NOW()' });
524 The update will pass the values verbatim into SQL. (See
525 L<SQL::Abstract> docs). The values in your Result object will NOT change
526 as a result of the update call, if you want the object to be updated
527 with the actual values from the database, call L</discard_changes>
530 $result->update()->discard_changes();
532 To determine before calling this method, which column values have
533 changed and will be updated, call L</get_dirty_columns>.
535 To check if any columns will be updated, call L</is_changed>.
537 To force a column to be updated, call L</make_column_dirty> before
543 my ($self, $upd) = @_;
545 $self->set_inflated_columns($upd) if $upd;
547 my %to_update = $self->get_dirty_columns
550 $self->throw_exception( "Not in database" ) unless $self->in_storage;
552 my $rows = $self->result_source->storage->update(
553 $self->result_source, \%to_update, $self->_storage_ident_condition
556 $self->throw_exception( "Can't update ${self}: row not found" );
557 } elsif ($rows > 1) {
558 $self->throw_exception("Can't update ${self}: updated more than one row");
560 $self->{_dirty_columns} = {};
561 $self->{related_resultsets} = {};
562 delete $self->{_column_data_in_storage};
572 =item Arguments: none
574 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
578 Throws an exception if the object is not in the database according to
579 L</in_storage>. Also throws an exception if a proper WHERE clause
580 uniquely identifying the database row can not be constructed (see
581 L<significance of primary keys|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
584 The object is still perfectly usable, but L</in_storage> will
585 now return 0 and the object must be reinserted using L</insert>
586 before it can be used to L</update> the row again.
588 If you delete an object in a class with a C<has_many> relationship, an
589 attempt is made to delete all the related objects as well. To turn
590 this behaviour off, pass C<< cascade_delete => 0 >> in the C<$attr>
591 hashref of the relationship, see L<DBIx::Class::Relationship>. Any
592 database-level cascade or restrict will take precedence over a
593 DBIx-Class-based cascading delete, since DBIx-Class B<deletes the
594 main row first> and only then attempts to delete any remaining related
597 If you delete an object within a txn_do() (see L<DBIx::Class::Storage/txn_do>)
598 and the transaction subsequently fails, the result object will remain marked as
599 not being in storage. If you know for a fact that the object is still in
600 storage (i.e. by inspecting the cause of the transaction's failure), you can
601 use C<< $obj->in_storage(1) >> to restore consistency between the object and
602 the database. This would allow a subsequent C<< $obj->delete >> to work
605 See also L<DBIx::Class::ResultSet/delete>.
612 $self->throw_exception( "Not in database" ) unless $self->in_storage;
614 $self->result_source->storage->delete(
615 $self->result_source, $self->_storage_ident_condition
618 delete $self->{_column_data_in_storage};
619 $self->in_storage(0);
622 my $rsrc = dbic_internal_try { $self->result_source_instance }
623 or $self->throw_exception("Can't do class delete without a ResultSource instance");
625 my $attrs = @_ > 1 && ref $_[$#_] eq 'HASH' ? { %{pop(@_)} } : {};
626 my $query = ref $_[0] eq 'HASH' ? $_[0] : {@_};
627 $rsrc->resultset->search(@_)->delete;
634 my $val = $result->get_column($col);
638 =item Arguments: $columnname
640 =item Return Value: The value of the column
644 Throws an exception if the column name given doesn't exist according
645 to L<has_column|DBIx::Class::ResultSource/has_column>.
647 Returns a raw column value from the result object, if it has already
648 been fetched from the database or set by an accessor.
650 If an L<inflated value|DBIx::Class::InflateColumn> has been set, it
651 will be deflated and returned.
653 Note that if you used the C<columns> or the C<select/as>
654 L<search attributes|DBIx::Class::ResultSet/ATTRIBUTES> on the resultset from
655 which C<$result> was derived, and B<did not include> C<$columnname> in the list,
656 this method will return C<undef> even if the database contains some value.
658 To retrieve all loaded column values as a hash, use L</get_columns>.
663 my ($self, $column) = @_;
664 $self->throw_exception( "Can't fetch data as class method" ) unless ref $self;
666 return $self->{_column_data}{$column}
667 if exists $self->{_column_data}{$column};
669 if (exists $self->{_inflated_column}{$column}) {
670 # deflate+return cycle
671 return $self->store_column($column, $self->_deflated_column(
672 $column, $self->{_inflated_column}{$column}
676 $self->throw_exception( "No such column '${column}' on " . ref $self )
677 unless $self->result_source->has_column($column);
682 =head2 has_column_loaded
684 if ( $result->has_column_loaded($col) ) {
685 print "$col has been loaded from db";
690 =item Arguments: $columnname
692 =item Return Value: 0|1
696 Returns a true value if the column value has been loaded from the
697 database (or set locally).
701 sub has_column_loaded {
702 my ($self, $column) = @_;
703 $self->throw_exception( "Can't call has_column data as class method" ) unless ref $self;
706 exists $self->{_inflated_column}{$column}
708 exists $self->{_column_data}{$column}
714 my %data = $result->get_columns;
718 =item Arguments: none
720 =item Return Value: A hash of columnname, value pairs.
724 Returns all loaded column data as a hash, containing raw values. To
725 get just one value for a particular column, use L</get_column>.
727 See L</get_inflated_columns> to get the inflated values.
733 if (exists $self->{_inflated_column}) {
734 # deflate cycle for each inflation, including filter rels
735 foreach my $col (keys %{$self->{_inflated_column}}) {
736 unless (exists $self->{_column_data}{$col}) {
738 # if cached related_resultset is present assume this was a prefetch
740 "Returning primary keys of prefetched 'filter' rels as part of get_columns() is deprecated and will "
741 . 'eventually be removed entirely (set DBIC_COLUMNS_INCLUDE_FILTER_RELS to disable this warning)'
743 ! $ENV{DBIC_COLUMNS_INCLUDE_FILTER_RELS}
745 defined $self->{related_resultsets}{$col}
747 defined $self->{related_resultsets}{$col}->get_cache
750 $self->store_column($col, $self->_deflated_column($col, $self->{_inflated_column}{$col}));
754 return %{$self->{_column_data}};
757 =head2 get_dirty_columns
759 my %data = $result->get_dirty_columns;
763 =item Arguments: none
765 =item Return Value: A hash of column, value pairs
769 Only returns the column, value pairs for those columns that have been
770 changed on this object since the last L</update> or L</insert> call.
772 See L</get_columns> to fetch all column/value pairs.
776 sub get_dirty_columns {
778 return map { $_ => $self->{_column_data}{$_} }
779 keys %{$self->{_dirty_columns}};
782 =head2 make_column_dirty
784 $result->make_column_dirty($col)
788 =item Arguments: $columnname
790 =item Return Value: not defined
794 Throws an exception if the column does not exist.
796 Marks a column as having been changed regardless of whether it has
801 sub make_column_dirty {
802 my ($self, $column) = @_;
804 $self->throw_exception( "No such column '${column}' on " . ref $self )
805 unless exists $self->{_column_data}{$column} || $self->result_source->has_column($column);
807 # the entire clean/dirty code relies on exists, not on true/false
808 return 1 if exists $self->{_dirty_columns}{$column};
810 $self->{_dirty_columns}{$column} = 1;
812 # if we are just now making the column dirty, and if there is an inflated
813 # value, force it over the deflated one
814 if (exists $self->{_inflated_column}{$column}) {
815 $self->store_column($column,
816 $self->_deflated_column(
817 $column, $self->{_inflated_column}{$column}
823 =head2 get_inflated_columns
825 my %inflated_data = $obj->get_inflated_columns;
829 =item Arguments: none
831 =item Return Value: A hash of column, object|value pairs
835 Returns a hash of all column keys and associated values. Values for any
836 columns set to use inflation will be inflated and returns as objects.
838 See L</get_columns> to get the uninflated values.
840 See L<DBIx::Class::InflateColumn> for how to setup inflation.
844 sub get_inflated_columns {
847 my $loaded_colinfo = $self->result_source->columns_info;
848 $self->has_column_loaded($_) or delete $loaded_colinfo->{$_}
849 for keys %$loaded_colinfo;
851 my %cols_to_return = ( %{$self->{_column_data}}, %$loaded_colinfo );
853 unless ($ENV{DBIC_COLUMNS_INCLUDE_FILTER_RELS}) {
854 for (keys %$loaded_colinfo) {
855 # if cached related_resultset is present assume this was a prefetch
857 $loaded_colinfo->{$_}{_inflate_info}
859 defined $self->{related_resultsets}{$_}
861 defined $self->{related_resultsets}{$_}->get_cache
864 "Returning prefetched 'filter' rels as part of get_inflated_columns() is deprecated and will "
865 . 'eventually be removed entirely (set DBIC_COLUMNS_INCLUDE_FILTER_RELS to disable this warning)'
874 ! exists $loaded_colinfo->{$_}
877 exists $loaded_colinfo->{$_}{accessor}
879 ! defined $loaded_colinfo->{$_}{accessor}
881 ) ? $self->get_column($_)
883 defined $loaded_colinfo->{$_}{accessor}
884 ? $loaded_colinfo->{$_}{accessor}
887 )} keys %cols_to_return;
890 sub _is_column_numeric {
891 my ($self, $column) = @_;
896 unless ( $rsrc = $self->result_source )->has_column($column);
898 my $colinfo = $rsrc->column_info ($column);
900 # cache for speed (the object may *not* have a resultsource instance)
902 ! defined $colinfo->{is_numeric}
904 my $storage = dbic_internal_try { $rsrc->schema->storage }
906 $colinfo->{is_numeric} =
907 $storage->is_datatype_numeric ($colinfo->{data_type})
913 return $colinfo->{is_numeric};
918 $result->set_column($col => $val);
922 =item Arguments: $columnname, $value
924 =item Return Value: $value
928 Sets a raw column value. If the new value is different from the old one,
929 the column is marked as dirty for when you next call L</update>.
931 If passed an object or reference as a value, this method will happily
932 attempt to store it, and a later L</insert> or L</update> will try and
933 stringify/numify as appropriate. To set an object to be deflated
934 instead, see L</set_inflated_columns>, or better yet, use L</$column_accessor>.
939 my ($self, $column, $new_value) = @_;
941 my $had_value = $self->has_column_loaded($column);
942 my $old_value = $self->get_column($column);
944 $new_value = $self->store_column($column, $new_value);
947 $self->{_dirty_columns}{$column}
949 ( $self->in_storage # no point tracking dirtyness on uninserted data
950 ? ! $self->_eq_column_values ($column, $old_value, $new_value)
956 # FIXME sadly the update code just checks for keys, not for their value
957 $self->{_dirty_columns}{$column} = 1;
959 # Clear out the relation/inflation cache related to this column
961 # FIXME - this is a quick *largely incorrect* hack, pending a more
962 # serious rework during the merge of single and filter rels
963 my $rel_names = $self->result_source->{_relationships};
964 for my $rel_name (keys %$rel_names) {
966 my $acc = $rel_names->{$rel_name}{attrs}{accessor} || '';
968 if ( $acc eq 'single' and $rel_names->{$rel_name}{attrs}{fk_columns}{$column} ) {
969 delete $self->{related_resultsets}{$rel_name};
970 delete $self->{_relationship_data}{$rel_name};
971 #delete $self->{_inflated_column}{$rel_name};
973 elsif ( $acc eq 'filter' and $rel_name eq $column) {
974 delete $self->{related_resultsets}{$rel_name};
975 #delete $self->{_relationship_data}{$rel_name};
976 delete $self->{_inflated_column}{$rel_name};
981 # value change from something (even if NULL)
984 # no storage - no storage-value
987 # no value already stored (multiple changes before commit to storage)
988 ! exists $self->{_column_data_in_storage}{$column}
990 $self->_track_storage_value($column)
992 $self->{_column_data_in_storage}{$column} = $old_value;
999 sub _eq_column_values {
1000 my ($self, $col, $old, $new) = @_;
1002 if (defined $old xor defined $new) {
1005 elsif (not defined $old) { # both undef
1009 is_literal_value $old
1011 is_literal_value $new
1015 elsif ($old eq $new) {
1018 elsif ($self->_is_column_numeric($col)) { # do a numeric comparison if datatype allows it
1019 return $old == $new;
1026 # returns a boolean indicating if the passed column should have its original
1027 # value tracked between column changes and commitment to storage
1028 sub _track_storage_value {
1029 my ($self, $col) = @_;
1032 $self->result_source->primary_columns
1038 $result->set_columns({ $col => $val, ... });
1042 =item Arguments: \%columndata
1044 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
1048 Sets multiple column, raw value pairs at once.
1050 Works as L</set_column>.
1055 my ($self, $values) = @_;
1056 $self->set_column( $_, $values->{$_} ) for keys %$values;
1060 =head2 set_inflated_columns
1062 $result->set_inflated_columns({ $col => $val, $rel_name => $obj, ... });
1066 =item Arguments: \%columndata
1068 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
1072 Sets more than one column value at once. Any inflated values are
1073 deflated and the raw values stored.
1075 Any related values passed as Result objects, using the relation name as a
1076 key, are reduced to the appropriate foreign key values and stored. If
1077 instead of related result objects, a hashref of column, value data is
1078 passed, will create the related object first then store.
1080 Will even accept arrayrefs of data as a value to a
1081 L<DBIx::Class::Relationship/has_many> key, and create the related
1082 objects if necessary.
1084 Be aware that the input hashref might be edited in place, so don't rely
1085 on it being the same after a call to C<set_inflated_columns>. If you
1086 need to preserve the hashref, it is sufficient to pass a shallow copy
1087 to C<set_inflated_columns>, e.g. ( { %{ $href } } )
1089 See also L<DBIx::Class::Relationship::Base/set_from_related>.
1093 sub set_inflated_columns {
1094 my ( $self, $upd ) = @_;
1096 foreach my $key (keys %$upd) {
1097 if (ref $upd->{$key}) {
1098 $rsrc ||= $self->result_source;
1099 my $info = $rsrc->relationship_info($key);
1100 my $acc_type = $info->{attrs}{accessor} || '';
1102 if ($acc_type eq 'single') {
1103 my $rel_obj = delete $upd->{$key};
1104 $self->set_from_related($key => $rel_obj);
1105 $self->{_relationship_data}{$key} = $rel_obj;
1107 elsif ($acc_type eq 'multi') {
1108 $self->throw_exception(
1109 "Recursive update is not supported over relationships of type '$acc_type' ($key)"
1113 $rsrc->has_column($key)
1115 exists $rsrc->column_info($key)->{_inflate_info}
1117 $self->set_inflated_column($key, delete $upd->{$key});
1121 $self->set_columns($upd);
1126 my $copy = $orig->copy({ change => $to, ... });
1130 =item Arguments: \%replacementdata
1132 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> copy
1136 Inserts a new row into the database, as a copy of the original
1137 object. If a hashref of replacement data is supplied, these will take
1138 precedence over data in the original. Also any columns which have
1139 the L<column info attribute|DBIx::Class::ResultSource/add_columns>
1140 C<< is_auto_increment => 1 >> are explicitly removed before the copy,
1141 so that the database can insert its own autoincremented values into
1144 Relationships will be followed by the copy procedure B<only> if the
1145 relationship specifies a true value for its
1146 L<cascade_copy|DBIx::Class::Relationship::Base> attribute. C<cascade_copy>
1147 is set by default on C<has_many> relationships and unset on all others.
1152 my ($self, $changes) = @_;
1154 my $col_data = { $self->get_columns };
1156 my $rsrc = $self->result_source;
1158 my $colinfo = $rsrc->columns_info;
1159 foreach my $col (keys %$col_data) {
1160 delete $col_data->{$col}
1161 if ( ! $colinfo->{$col} or $colinfo->{$col}{is_auto_increment} );
1164 my $new = { _column_data => $col_data };
1165 bless $new, ref $self;
1167 $new->result_source($rsrc);
1168 $new->set_inflated_columns($changes);
1171 # Its possible we'll have 2 relations to the same Source. We need to make
1172 # sure we don't try to insert the same row twice else we'll violate unique
1174 my $rel_names_copied = {};
1176 foreach my $rel_name ($rsrc->relationships) {
1177 my $rel_info = $rsrc->relationship_info($rel_name);
1179 next unless $rel_info->{attrs}{cascade_copy};
1182 my $copied = $rel_names_copied->{ $rel_info->{source} } ||= {};
1184 $copied->{$_->ID}++ or $_->copy(
1186 $foreign_vals ||= $rsrc->_resolve_relationship_condition(
1187 infer_values_based_on => {},
1188 rel_name => $rel_name,
1189 self_result_object => $new,
1191 self_alias => "\xFE", # irrelevant
1192 foreign_alias => "\xFF", # irrelevant,
1193 )->{inferred_values}
1195 ) for $self->search_related($rel_name)->all;
1202 $result->store_column($col => $val);
1206 =item Arguments: $columnname, $value
1208 =item Return Value: The value sent to storage
1212 Set a raw value for a column without marking it as changed. This
1213 method is used internally by L</set_column> which you should probably
1216 This is the lowest level at which data is set on a result object,
1217 extend this method to catch all data setting methods.
1222 my ($self, $column, $value) = @_;
1223 $self->throw_exception( "No such column '${column}' on " . ref $self )
1224 unless exists $self->{_column_data}{$column} || $self->result_source->has_column($column);
1225 $self->throw_exception( "set_column called for ${column} without value" )
1228 return $self->{_column_data}{$column} = $value
1229 unless length ref $value and my $vref = is_plain_value( $value );
1231 # if we are dealing with a value/ref - there are a couple possibilities
1232 # unpack the underlying piece of data and stringify all objects explicitly
1233 # ( to accomodate { -value => ... } and guard against overloaded objects
1234 # with defined stringification AND fallback => 0 (ugh!)
1235 $self->{_column_data}{$column} = defined blessed $$vref
1241 =head2 inflate_result
1243 Class->inflate_result($result_source, \%me, \%prefetch?)
1247 =item Arguments: L<$result_source|DBIx::Class::ResultSource>, \%columndata, \%prefetcheddata
1249 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
1253 All L<DBIx::Class::ResultSet> methods that retrieve data from the
1254 database and turn it into result objects call this method.
1256 Extend this method in your Result classes to hook into this process,
1257 for example to rebless the result into a different class.
1259 Reblessing can also be done more easily by setting C<result_class> in
1260 your Result class. See L<DBIx::Class::ResultSource/result_class>.
1262 Different types of results can also be created from a particular
1263 L<DBIx::Class::ResultSet>, see L<DBIx::Class::ResultSet/result_class>.
1267 sub inflate_result {
1268 my ($class, $rsrc, $me, $prefetch) = @_;
1271 { _column_data => $me, _result_source => $rsrc },
1272 ref $class || $class
1276 for my $rel_name ( keys %$prefetch ) {
1278 my $relinfo = $rsrc->relationship_info($rel_name) or do {
1280 "Inflation into non-existent relationship '%s' of '%s' requested",
1284 if (my ($colname) = sort { length($a) <=> length ($b) } keys %{$prefetch->{$rel_name}[0] || {}} ) {
1285 $err .= sprintf ", check the inflation specification (columns/as) ending in '...%s.%s'",
1290 $rsrc->throw_exception($err);
1293 $class->throw_exception("No accessor type declared for prefetched relationship '$rel_name'")
1294 unless $relinfo->{attrs}{accessor};
1296 my $rel_rs = $new->related_resultset($rel_name);
1300 @{ $prefetch->{$rel_name} || [] }
1302 ref($prefetch->{$rel_name}) ne $DBIx::Class::ResultSource::RowParser::Util::null_branch_class
1305 if (ref $prefetch->{$rel_name}[0] eq 'ARRAY') {
1306 my $rel_rsrc = $rel_rs->result_source;
1307 my $rel_class = $rel_rs->result_class;
1308 my $rel_inflator = $rel_class->can('inflate_result');
1310 { $rel_class->$rel_inflator ( $rel_rsrc, @$_ ) }
1311 @{$prefetch->{$rel_name}}
1315 @rel_objects = $rel_rs->result_class->inflate_result(
1316 $rel_rs->result_source, @{$prefetch->{$rel_name}}
1321 if ($relinfo->{attrs}{accessor} eq 'single') {
1322 $new->{_relationship_data}{$rel_name} = $rel_objects[0];
1324 elsif ($relinfo->{attrs}{accessor} eq 'filter') {
1325 $new->{_inflated_column}{$rel_name} = $rel_objects[0];
1328 $rel_rs->set_cache(\@rel_objects);
1332 $new->in_storage (1);
1336 =head2 update_or_insert
1338 $result->update_or_insert
1342 =item Arguments: none
1344 =item Return Value: Result of update or insert operation
1348 L</update>s the object if it's already in the database, according to
1349 L</in_storage>, else L</insert>s it.
1351 =head2 insert_or_update
1353 $obj->insert_or_update
1355 Alias for L</update_or_insert>
1359 sub insert_or_update { shift->update_or_insert(@_) }
1361 sub update_or_insert {
1363 return ($self->in_storage ? $self->update : $self->insert);
1368 my @changed_col_names = $result->is_changed();
1369 if ($result->is_changed()) { ... }
1373 =item Arguments: none
1375 =item Return Value: 0|1 or @columnnames
1379 In list context returns a list of columns with uncommited changes, or
1380 in scalar context returns a true value if there are uncommitted
1386 return keys %{shift->{_dirty_columns} || {}};
1389 =head2 is_column_changed
1391 if ($result->is_column_changed('col')) { ... }
1395 =item Arguments: $columname
1397 =item Return Value: 0|1
1401 Returns a true value if the column has uncommitted changes.
1405 sub is_column_changed {
1406 my( $self, $col ) = @_;
1407 return exists $self->{_dirty_columns}->{$col};
1410 =head2 result_source
1412 my $resultsource = $result->result_source;
1416 =item Arguments: L<$result_source?|DBIx::Class::ResultSource>
1418 =item Return Value: L<$result_source|DBIx::Class::ResultSource>
1422 Accessor to the L<DBIx::Class::ResultSource> this object was created from.
1427 $_[0]->throw_exception( 'result_source can be called on instances only' )
1431 ? $_[0]->{_result_source} = $_[1]
1433 # note this is a || not a ||=, the difference is important
1434 : $_[0]->{_result_source} || do {
1435 $_[0]->can('result_source_instance')
1436 ? $_[0]->result_source_instance
1437 : $_[0]->throw_exception(
1438 "No result source instance registered for @{[ ref $_[0] ]}, did you forget to call @{[ ref $_[0] ]}->table(...) ?"
1444 =head2 register_column
1446 $column_info = { .... };
1447 $class->register_column($column_name, $column_info);
1451 =item Arguments: $columnname, \%columninfo
1453 =item Return Value: not defined
1457 Registers a column on the class. If the column_info has an 'accessor'
1458 key, creates an accessor named after the value if defined; if there is
1459 no such key, creates an accessor with the same name as the column
1461 The column_info attributes are described in
1462 L<DBIx::Class::ResultSource/add_columns>
1466 sub register_column {
1467 my ($class, $col, $info) = @_;
1469 if (exists $info->{accessor}) {
1470 return unless defined $info->{accessor};
1471 $acc = [ $info->{accessor}, $col ];
1473 $class->mk_group_accessors('column' => $acc);
1476 =head2 get_from_storage
1478 my $copy = $result->get_from_storage($attrs)
1482 =item Arguments: \%attrs
1484 =item Return Value: A Result object
1488 Fetches a fresh copy of the Result object from the database and returns it.
1489 Throws an exception if a proper WHERE clause identifying the database row
1490 can not be constructed (i.e. if the original object does not contain its
1492 L<primary key|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
1493 ). If passed the \%attrs argument, will first apply these attributes to
1494 the resultset used to find the row.
1496 This copy can then be used to compare to an existing result object, to
1497 determine if any changes have been made in the database since it was
1500 To just update your Result object with any latest changes from the
1501 database, use L</discard_changes> instead.
1503 The \%attrs argument should be compatible with
1504 L<DBIx::Class::ResultSet/ATTRIBUTES>.
1508 sub get_from_storage {
1509 my $self = shift @_;
1510 my $attrs = shift @_;
1511 my $resultset = $self->result_source->resultset;
1513 if(defined $attrs) {
1514 $resultset = $resultset->search(undef, $attrs);
1517 return $resultset->find($self->_storage_ident_condition);
1520 =head2 discard_changes
1522 $result->discard_changes
1526 =item Arguments: none or $attrs
1528 =item Return Value: self (updates object in-place)
1532 Re-selects the row from the database, losing any changes that had
1533 been made. Throws an exception if a proper C<WHERE> clause identifying
1534 the database row can not be constructed (i.e. if the original object
1535 does not contain its entire
1536 L<primary key|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>).
1538 This method can also be used to refresh from storage, retrieving any
1539 changes made since the row was last read from storage.
1541 $attrs, if supplied, is expected to be a hashref of attributes suitable for passing as the
1542 second argument to C<< $resultset->search($cond, $attrs) >>;
1544 Note: If you are using L<DBIx::Class::Storage::DBI::Replicated> as your
1545 storage, a default of
1546 L<< C<< { force_pool => 'master' } >>
1547 |DBIx::Class::Storage::DBI::Replicated/SYNOPSIS >> is automatically set for
1548 you. Prior to C<< DBIx::Class 0.08109 >> (before 2010) one would have been
1549 required to explicitly wrap the entire operation in a transaction to guarantee
1550 that up-to-date results are read from the master database.
1554 sub discard_changes {
1555 my ($self, $attrs) = @_;
1556 return unless $self->in_storage; # Don't reload if we aren't real!
1558 # add a replication default to read from the master only
1559 $attrs = { force_pool => 'master', %{$attrs||{}} };
1561 if( my $current_storage = $self->get_from_storage($attrs)) {
1563 # Set $self to the current.
1564 %$self = %$current_storage;
1566 # Avoid a possible infinite loop with
1567 # sub DESTROY { $_[0]->discard_changes }
1568 bless $current_storage, 'Do::Not::Exist';
1573 $self->in_storage(0);
1578 =head2 throw_exception
1580 See L<DBIx::Class::Schema/throw_exception>.
1584 sub throw_exception {
1590 my $rsrc = dbic_internal_try { $self->result_source_instance }
1592 $rsrc->throw_exception(@_)
1595 DBIx::Class::Exception->throw(@_);
1601 my @pk = $result->id;
1605 =item Arguments: none
1607 =item Returns: A list of primary key values
1611 Returns the primary key(s) for a row. Can't be called as a class method.
1612 Actually implemented in L<DBIx::Class::PK>
1614 =head1 FURTHER QUESTIONS?
1616 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
1618 =head1 COPYRIGHT AND LICENSE
1620 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1621 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1622 redistribute it and/or modify it under the same terms as the
1623 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.