1 package DBIx::Class::Row;
6 use base qw/DBIx::Class/;
8 use DBIx::Class::Exception;
9 use Scalar::Util 'blessed';
19 $ENV{DBIC_MULTICREATE_DEBUG}
26 DBIx::Class::Row - Basic row methods
32 This class is responsible for defining and doing basic operations on rows
33 derived from L<DBIx::Class::ResultSource> objects.
35 Row objects are returned from L<DBIx::Class::ResultSet>s using the
36 L<create|DBIx::Class::ResultSet/create>, L<find|DBIx::Class::ResultSet/find>,
37 L<next|DBIx::Class::ResultSet/next> and L<all|DBIx::Class::ResultSet/all> methods,
38 as well as invocations of 'single' (
39 L<belongs_to|DBIx::Class::Relationship/belongs_to>,
40 L<has_one|DBIx::Class::Relationship/has_one> or
41 L<might_have|DBIx::Class::Relationship/might_have>)
42 relationship accessors of L<DBIx::Class::Row> objects.
48 my $row = My::Class->new(\%attrs);
50 my $row = $schema->resultset('MySource')->new(\%colsandvalues);
54 =item Arguments: \%attrs or \%colsandvalues
56 =item Returns: A Row object
60 While you can create a new row object by calling C<new> directly on
61 this class, you are better off calling it on a
62 L<DBIx::Class::ResultSet> object.
64 When calling it directly, you will not get a complete, usable row
65 object until you pass or set the C<result_source> attribute, to a
66 L<DBIx::Class::ResultSource> instance that is attached to a
67 L<DBIx::Class::Schema> with a valid connection.
69 C<$attrs> is a hashref of column name, value data. It can also contain
70 some other attributes such as the C<result_source>.
72 Passing an object, or an arrayref of objects as a value will call
73 L<DBIx::Class::Relationship::Base/set_from_related> for you. When
74 passed a hashref or an arrayref of hashrefs as the value, these will
75 be turned into objects via new_related, and treated as if you had
78 For a more involved explanation, see L<DBIx::Class::ResultSet/create>.
80 Please note that if a value is not passed to new, no value will be sent
81 in the SQL INSERT call, and the column will therefore assume whatever
82 default value was specified in your database. While DBIC will retrieve the
83 value of autoincrement columns, it will never make an explicit database
84 trip to retrieve default values assigned by the RDBMS. You can explicitly
85 request that all values be fetched back from the database by calling
86 L</discard_changes>, or you can supply an explicit C<undef> to columns
87 with NULL as the default, and save yourself a SELECT.
91 The behavior described above will backfire if you use a foreign key column
92 with a database-defined default. If you call the relationship accessor on
93 an object that doesn't have a set value for the FK column, DBIC will throw
94 an exception, as it has no way of knowing the PK of the related object (if
99 ## 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().
100 ## This only works because DBIC doesnt yet care to check whether the new_related objects have been passed all their mandatory columns
101 ## When doing the later insert, we need to make sure the PKs are set.
102 ## using _relationship_data in new and funky ways..
103 ## check Relationship::CascadeActions and Relationship::Accessor for compat
106 sub __new_related_find_or_new_helper {
107 my ($self, $relname, $data) = @_;
109 my $rsrc = $self->result_source;
111 # create a mock-object so all new/set_column component overrides will run:
112 my $rel_rs = $rsrc->related_source($relname)->resultset;
113 my $new_rel_obj = $rel_rs->new_result($data);
114 my $proc_data = { $new_rel_obj->get_columns };
116 if ($self->__their_pk_needs_us($relname)) {
117 MULTICREATE_DEBUG and warn "MC $self constructing $relname via new_result";
120 elsif ($rsrc->_pk_depends_on($relname, $proc_data )) {
121 if (! keys %$proc_data) {
122 # there is nothing to search for - blind create
123 MULTICREATE_DEBUG and warn "MC $self constructing default-insert $relname";
126 MULTICREATE_DEBUG and warn "MC $self constructing $relname via find_or_new";
127 # this is not *really* find or new, as we don't want to double-new the
128 # data (thus potentially double encoding or whatever)
129 my $exists = $rel_rs->find ($proc_data);
130 return $exists if $exists;
135 my $us = $rsrc->source_name;
136 $self->throw_exception (
137 "Unable to determine relationship '$relname' direction from '$us', "
138 . "possibly due to a missing reverse-relationship on '$relname' to '$us'."
143 sub __their_pk_needs_us { # this should maybe be in resultsource.
144 my ($self, $relname) = @_;
145 my $source = $self->result_source;
146 my $reverse = $source->reverse_relationship_info($relname);
147 my $rel_source = $source->related_source($relname);
148 my $us = { $self->get_columns };
149 foreach my $key (keys %$reverse) {
150 # if their primary key depends on us, then we have to
151 # just create a result and we'll fill it out afterwards
152 return 1 if $rel_source->_pk_depends_on($key, $us);
158 my ($class, $attrs) = @_;
159 $class = ref $class if ref $class;
161 my $new = bless { _column_data => {} }, $class;
164 $new->throw_exception("attrs must be a hashref")
165 unless ref($attrs) eq 'HASH';
167 my $source = delete $attrs->{-result_source};
168 if ( my $h = delete $attrs->{-source_handle} ) {
169 $source ||= $h->resolve;
172 $new->result_source($source) if $source;
174 if (my $col_from_rel = delete $attrs->{-cols_from_relations}) {
175 @{$new->{_ignore_at_insert}={}}{@$col_from_rel} = ();
178 my ($related,$inflated);
180 foreach my $key (keys %$attrs) {
181 if (ref $attrs->{$key}) {
182 ## Can we extract this lot to use with update(_or .. ) ?
183 $new->throw_exception("Can't do multi-create without result source")
185 my $info = $source->relationship_info($key);
186 my $acc_type = $info->{attrs}{accessor} || '';
187 if ($acc_type eq 'single') {
188 my $rel_obj = delete $attrs->{$key};
189 if(!blessed $rel_obj) {
190 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
193 if ($rel_obj->in_storage) {
194 $new->{_rel_in_storage}{$key} = 1;
195 $new->set_from_related($key, $rel_obj);
197 MULTICREATE_DEBUG and warn "MC $new uninserted $key $rel_obj\n";
200 $related->{$key} = $rel_obj;
203 elsif ($acc_type eq 'multi' && ref $attrs->{$key} eq 'ARRAY' ) {
204 my $others = delete $attrs->{$key};
205 my $total = @$others;
207 foreach my $idx (0 .. $#$others) {
208 my $rel_obj = $others->[$idx];
209 if(!blessed $rel_obj) {
210 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
213 if ($rel_obj->in_storage) {
214 $rel_obj->throw_exception ('A multi relationship can not be pre-existing when doing multicreate. Something went wrong');
216 MULTICREATE_DEBUG and
217 warn "MC $new uninserted $key $rel_obj (${\($idx+1)} of $total)\n";
219 push(@objects, $rel_obj);
221 $related->{$key} = \@objects;
224 elsif ($acc_type eq 'filter') {
225 ## 'filter' should disappear and get merged in with 'single' above!
226 my $rel_obj = delete $attrs->{$key};
227 if(!blessed $rel_obj) {
228 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
230 if ($rel_obj->in_storage) {
231 $new->{_rel_in_storage}{$key} = 1;
234 MULTICREATE_DEBUG and warn "MC $new uninserted $key $rel_obj";
236 $inflated->{$key} = $rel_obj;
238 } elsif ($class->has_column($key)
239 && $class->column_info($key)->{_inflate_info}) {
240 $inflated->{$key} = $attrs->{$key};
244 $new->throw_exception("No such column $key on $class")
245 unless $class->has_column($key);
246 $new->store_column($key => $attrs->{$key});
249 $new->{_relationship_data} = $related if $related;
250 $new->{_inflated_column} = $inflated if $inflated;
262 =item Arguments: none
264 =item Returns: The Row object
268 Inserts an object previously created by L</new> into the database if
269 it isn't already in there. Returns the object itself. To insert an
270 entirely new row into the database, use L<DBIx::Class::ResultSet/create>.
272 To fetch an uninserted row object, call
273 L<new|DBIx::Class::ResultSet/new> on a resultset.
275 This will also insert any uninserted, related objects held inside this
276 one, see L<DBIx::Class::ResultSet/create> for more details.
282 return $self if $self->in_storage;
283 my $source = $self->result_source;
284 $self->throw_exception("No result_source set on this object; can't insert")
287 my $storage = $source->storage;
291 # Check if we stored uninserted relobjs here in new()
292 my %related_stuff = (%{$self->{_relationship_data} || {}},
293 %{$self->{_inflated_column} || {}});
295 # insert what needs to be inserted before us
297 for my $relname (keys %related_stuff) {
298 my $rel_obj = $related_stuff{$relname};
300 if (! $self->{_rel_in_storage}{$relname}) {
301 next unless (blessed $rel_obj && $rel_obj->isa('DBIx::Class::Row'));
303 next unless $source->_pk_depends_on(
304 $relname, { $rel_obj->get_columns }
307 # The guard will save us if we blow out of this scope via die
308 $rollback_guard ||= $storage->txn_scope_guard;
310 MULTICREATE_DEBUG and warn "MC $self pre-reconstructing $relname $rel_obj\n";
312 my $them = { %{$rel_obj->{_relationship_data} || {} }, $rel_obj->get_columns };
315 # if there are no keys - nothing to search for
316 if (keys %$them and $existing = $self->result_source
317 ->related_source($relname)
321 %{$rel_obj} = %{$existing};
327 $self->{_rel_in_storage}{$relname} = 1;
330 $self->set_from_related($relname, $rel_obj);
331 delete $related_stuff{$relname};
334 # start a transaction here if not started yet and there is more stuff
336 if (keys %related_stuff) {
337 $rollback_guard ||= $storage->txn_scope_guard
340 MULTICREATE_DEBUG and do {
341 no warnings 'uninitialized';
342 warn "MC $self inserting (".join(', ', $self->get_columns).")\n";
345 my %current_rowdata = $self->get_columns;
347 # perform the insert - the storage may return some stuff for us right there
349 my $returned_cols = $storage->insert(
354 for (keys %$returned_cols) {
357 ( $current_rowdata{$_} = $returned_cols->{$_} )
361 # see if any of the pcols still need filling (or re-querying in case of scalarrefs)
362 my @missing_pri = grep
363 { ! defined $current_rowdata{$_} or ref $current_rowdata{$_} eq 'SCALAR' }
364 $self->primary_columns
368 MULTICREATE_DEBUG and warn "MC $self fetching missing PKs ".join(', ', @missing_pri )."\n";
370 $self->throw_exception( "Missing primary key but Storage doesn't support last_insert_id" )
371 unless $storage->can('last_insert_id');
373 my @pri_values = $storage->last_insert_id($self->result_source, @missing_pri);
375 $self->throw_exception( "Can't get last insert id" )
376 unless (@pri_values == @missing_pri);
378 $self->store_column($missing_pri[$_] => $pri_values[$_]) for 0 .. $#missing_pri;
381 $self->{_dirty_columns} = {};
382 $self->{related_resultsets} = {};
384 foreach my $relname (keys %related_stuff) {
385 next unless $source->has_relationship ($relname);
387 my @cands = ref $related_stuff{$relname} eq 'ARRAY'
388 ? @{$related_stuff{$relname}}
389 : $related_stuff{$relname}
392 if (@cands && blessed $cands[0] && $cands[0]->isa('DBIx::Class::Row')
394 my $reverse = $source->reverse_relationship_info($relname);
395 foreach my $obj (@cands) {
396 $obj->set_from_related($_, $self) for keys %$reverse;
397 if ($self->__their_pk_needs_us($relname)) {
398 if (exists $self->{_ignore_at_insert}{$relname}) {
399 MULTICREATE_DEBUG and warn "MC $self skipping post-insert on $relname";
402 MULTICREATE_DEBUG and warn "MC $self inserting $relname $obj";
406 MULTICREATE_DEBUG and warn "MC $self post-inserting $obj";
413 $self->in_storage(1);
414 delete $self->{_orig_ident};
415 delete $self->{_orig_ident_failreason};
416 delete $self->{_ignore_at_insert};
417 $rollback_guard->commit if $rollback_guard;
424 $row->in_storage; # Get value
425 $row->in_storage(1); # Set value
429 =item Arguments: none or 1|0
435 Indicates whether the object exists as a row in the database or
436 not. This is set to true when L<DBIx::Class::ResultSet/find>,
437 L<DBIx::Class::ResultSet/create> or L<DBIx::Class::ResultSet/insert>
440 Creating a row object using L<DBIx::Class::ResultSet/new>, or calling
441 L</delete> on one, sets it to false.
446 my ($self, $val) = @_;
447 $self->{_in_storage} = $val if @_ > 1;
448 return $self->{_in_storage} ? 1 : 0;
453 $row->update(\%columns?)
457 =item Arguments: none or a hashref
459 =item Returns: The Row object
463 Throws an exception if the row object is not yet in the database,
464 according to L</in_storage>.
466 This method issues an SQL UPDATE query to commit any changes to the
467 object to the database if required (see L</get_dirty_columns>).
468 It throws an exception if a proper WHERE clause uniquely identifying
469 the database row can not be constructed (see
470 L<significance of primary keys|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
473 Also takes an optional hashref of C<< column_name => value >> pairs
474 to update on the object first. Be aware that the hashref will be
475 passed to C<set_inflated_columns>, which might edit it in place, so
476 don't rely on it being the same after a call to C<update>. If you
477 need to preserve the hashref, it is sufficient to pass a shallow copy
478 to C<update>, e.g. ( { %{ $href } } )
480 If the values passed or any of the column values set on the object
481 contain scalar references, e.g.:
483 $row->last_modified(\'NOW()');
485 $row->update({ last_modified => \'NOW()' });
487 The update will pass the values verbatim into SQL. (See
488 L<SQL::Abstract> docs). The values in your Row object will NOT change
489 as a result of the update call, if you want the object to be updated
490 with the actual values from the database, call L</discard_changes>
493 $row->update()->discard_changes();
495 To determine before calling this method, which column values have
496 changed and will be updated, call L</get_dirty_columns>.
498 To check if any columns will be updated, call L</is_changed>.
500 To force a column to be updated, call L</make_column_dirty> before
506 my ($self, $upd) = @_;
508 $self->set_inflated_columns($upd) if $upd;
510 my %to_update = $self->get_dirty_columns
513 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
514 $self->throw_exception( "Not in database" ) unless $self->in_storage;
516 $self->throw_exception($self->{_orig_ident_failreason})
517 if ! keys %$ident_cond;
519 my $rows = $self->result_source->storage->update(
520 $self->result_source, \%to_update, $ident_cond
523 $self->throw_exception( "Can't update ${self}: row not found" );
524 } elsif ($rows > 1) {
525 $self->throw_exception("Can't update ${self}: updated more than one row");
527 $self->{_dirty_columns} = {};
528 $self->{related_resultsets} = {};
529 delete $self->{_orig_ident};
539 =item Arguments: none
541 =item Returns: The Row object
545 Throws an exception if the object is not in the database according to
546 L</in_storage>. Also throws an exception if a proper WHERE clause
547 uniquely identifying the database row can not be constructed (see
548 L<significance of primary keys|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
551 The object is still perfectly usable, but L</in_storage> will
552 now return 0 and the object must be reinserted using L</insert>
553 before it can be used to L</update> the row again.
555 If you delete an object in a class with a C<has_many> relationship, an
556 attempt is made to delete all the related objects as well. To turn
557 this behaviour off, pass C<< cascade_delete => 0 >> in the C<$attr>
558 hashref of the relationship, see L<DBIx::Class::Relationship>. Any
559 database-level cascade or restrict will take precedence over a
560 DBIx-Class-based cascading delete, since DBIx-Class B<deletes the
561 main row first> and only then attempts to delete any remaining related
564 If you delete an object within a txn_do() (see L<DBIx::Class::Storage/txn_do>)
565 and the transaction subsequently fails, the row object will remain marked as
566 not being in storage. If you know for a fact that the object is still in
567 storage (i.e. by inspecting the cause of the transaction's failure), you can
568 use C<< $obj->in_storage(1) >> to restore consistency between the object and
569 the database. This would allow a subsequent C<< $obj->delete >> to work
572 See also L<DBIx::Class::ResultSet/delete>.
579 $self->throw_exception( "Not in database" ) unless $self->in_storage;
581 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
582 $self->throw_exception($self->{_orig_ident_failreason})
583 if ! keys %$ident_cond;
585 $self->result_source->storage->delete(
586 $self->result_source, $ident_cond
589 delete $self->{_orig_ident}; # no longer identifiable
590 $self->in_storage(undef);
593 my $rsrc = try { $self->result_source_instance }
594 or $self->throw_exception("Can't do class delete without a ResultSource instance");
596 my $attrs = @_ > 1 && ref $_[$#_] eq 'HASH' ? { %{pop(@_)} } : {};
597 my $query = ref $_[0] eq 'HASH' ? $_[0] : {@_};
598 $rsrc->resultset->search(@_)->delete;
605 my $val = $row->get_column($col);
609 =item Arguments: $columnname
611 =item Returns: The value of the column
615 Throws an exception if the column name given doesn't exist according
618 Returns a raw column value from the row object, if it has already
619 been fetched from the database or set by an accessor.
621 If an L<inflated value|DBIx::Class::InflateColumn> has been set, it
622 will be deflated and returned.
624 Note that if you used the C<columns> or the C<select/as>
625 L<search attributes|DBIx::Class::ResultSet/ATTRIBUTES> on the resultset from
626 which C<$row> was derived, and B<did not include> C<$columnname> in the list,
627 this method will return C<undef> even if the database contains some value.
629 To retrieve all loaded column values as a hash, use L</get_columns>.
634 my ($self, $column) = @_;
635 $self->throw_exception( "Can't fetch data as class method" ) unless ref $self;
636 return $self->{_column_data}{$column} if exists $self->{_column_data}{$column};
637 if (exists $self->{_inflated_column}{$column}) {
638 return $self->store_column($column,
639 $self->_deflated_column($column, $self->{_inflated_column}{$column}));
641 $self->throw_exception( "No such column '${column}'" ) unless $self->has_column($column);
645 =head2 has_column_loaded
647 if ( $row->has_column_loaded($col) ) {
648 print "$col has been loaded from db";
653 =item Arguments: $columnname
659 Returns a true value if the column value has been loaded from the
660 database (or set locally).
664 sub has_column_loaded {
665 my ($self, $column) = @_;
666 $self->throw_exception( "Can't call has_column data as class method" ) unless ref $self;
667 return 1 if exists $self->{_inflated_column}{$column};
668 return exists $self->{_column_data}{$column};
673 my %data = $row->get_columns;
677 =item Arguments: none
679 =item Returns: A hash of columnname, value pairs.
683 Returns all loaded column data as a hash, containing raw values. To
684 get just one value for a particular column, use L</get_column>.
686 See L</get_inflated_columns> to get the inflated values.
692 if (exists $self->{_inflated_column}) {
693 foreach my $col (keys %{$self->{_inflated_column}}) {
694 $self->store_column($col, $self->_deflated_column($col, $self->{_inflated_column}{$col}))
695 unless exists $self->{_column_data}{$col};
698 return %{$self->{_column_data}};
701 =head2 get_dirty_columns
703 my %data = $row->get_dirty_columns;
707 =item Arguments: none
709 =item Returns: A hash of column, value pairs
713 Only returns the column, value pairs for those columns that have been
714 changed on this object since the last L</update> or L</insert> call.
716 See L</get_columns> to fetch all column/value pairs.
720 sub get_dirty_columns {
722 return map { $_ => $self->{_column_data}{$_} }
723 keys %{$self->{_dirty_columns}};
726 =head2 make_column_dirty
728 $row->make_column_dirty($col)
732 =item Arguments: $columnname
734 =item Returns: undefined
738 Throws an exception if the column does not exist.
740 Marks a column as having been changed regardless of whether it has
744 sub make_column_dirty {
745 my ($self, $column) = @_;
747 $self->throw_exception( "No such column '${column}'" )
748 unless exists $self->{_column_data}{$column} || $self->has_column($column);
750 # the entire clean/dirty code relies on exists, not on true/false
751 return 1 if exists $self->{_dirty_columns}{$column};
753 $self->{_dirty_columns}{$column} = 1;
755 # if we are just now making the column dirty, and if there is an inflated
756 # value, force it over the deflated one
757 if (exists $self->{_inflated_column}{$column}) {
758 $self->store_column($column,
759 $self->_deflated_column(
760 $column, $self->{_inflated_column}{$column}
766 =head2 get_inflated_columns
768 my %inflated_data = $obj->get_inflated_columns;
772 =item Arguments: none
774 =item Returns: A hash of column, object|value pairs
778 Returns a hash of all column keys and associated values. Values for any
779 columns set to use inflation will be inflated and returns as objects.
781 See L</get_columns> to get the uninflated values.
783 See L<DBIx::Class::InflateColumn> for how to setup inflation.
787 sub get_inflated_columns {
790 my $loaded_colinfo = $self->columns_info ([
791 grep { $self->has_column_loaded($_) } $self->columns
795 for my $col (keys %$loaded_colinfo) {
796 if (exists $loaded_colinfo->{$col}{accessor}) {
797 my $acc = $loaded_colinfo->{$col}{accessor};
798 $inflated{$col} = $self->$acc if defined $acc;
801 $inflated{$col} = $self->$col;
805 # return all loaded columns with the inflations overlayed on top
806 return %{ { $self->get_columns, %inflated } };
809 sub _is_column_numeric {
810 my ($self, $column) = @_;
811 my $colinfo = $self->column_info ($column);
813 # cache for speed (the object may *not* have a resultsource instance)
815 ! defined $colinfo->{is_numeric}
817 my $storage = try { $self->result_source->schema->storage }
819 $colinfo->{is_numeric} =
820 $storage->is_datatype_numeric ($colinfo->{data_type})
826 return $colinfo->{is_numeric};
831 $row->set_column($col => $val);
835 =item Arguments: $columnname, $value
837 =item Returns: $value
841 Sets a raw column value. If the new value is different from the old one,
842 the column is marked as dirty for when you next call L</update>.
844 If passed an object or reference as a value, this method will happily
845 attempt to store it, and a later L</insert> or L</update> will try and
846 stringify/numify as appropriate. To set an object to be deflated
847 instead, see L</set_inflated_columns>.
852 my ($self, $column, $new_value) = @_;
854 # if we can't get an ident condition on first try - mark the object as unidentifiable
855 # (by using an empty hashref) and store the error for further diag
856 unless ($self->{_orig_ident}) {
858 $self->{_orig_ident} = $self->ident_condition
861 $self->{_orig_ident_failreason} = $_;
862 $self->{_orig_ident} = {};
866 my $old_value = $self->get_column($column);
867 $new_value = $self->store_column($column, $new_value);
870 $self->{_dirty_columns}{$column}
872 $self->in_storage # no point tracking dirtyness on uninserted data
873 ? ! $self->_eq_column_values ($column, $old_value, $new_value)
878 # FIXME sadly the update code just checks for keys, not for their value
879 $self->{_dirty_columns}{$column} = 1;
881 # Clear out the relation/inflation cache related to this column
883 # FIXME - this is a quick *largely incorrect* hack, pending a more
884 # serious rework during the merge of single and filter rels
885 my $rels = $self->result_source->{_relationships};
886 for my $rel (keys %$rels) {
888 my $acc = $rels->{$rel}{attrs}{accessor} || '';
890 if ( $acc eq 'single' and $rels->{$rel}{attrs}{fk_columns}{$column} ) {
891 delete $self->{related_resultsets}{$rel};
892 delete $self->{_relationship_data}{$rel};
893 #delete $self->{_inflated_column}{$rel};
895 elsif ( $acc eq 'filter' and $rel eq $column) {
896 delete $self->{related_resultsets}{$rel};
897 #delete $self->{_relationship_data}{$rel};
898 delete $self->{_inflated_column}{$rel};
906 sub _eq_column_values {
907 my ($self, $col, $old, $new) = @_;
909 if (defined $old xor defined $new) {
912 elsif (not defined $old) { # both undef
915 elsif ($old eq $new) {
918 elsif ($self->_is_column_numeric($col)) { # do a numeric comparison if datatype allows it
928 $row->set_columns({ $col => $val, ... });
932 =item Arguments: \%columndata
934 =item Returns: The Row object
938 Sets multiple column, raw value pairs at once.
940 Works as L</set_column>.
945 my ($self,$data) = @_;
946 foreach my $col (keys %$data) {
947 $self->set_column($col,$data->{$col});
952 =head2 set_inflated_columns
954 $row->set_inflated_columns({ $col => $val, $relname => $obj, ... });
958 =item Arguments: \%columndata
960 =item Returns: The Row object
964 Sets more than one column value at once. Any inflated values are
965 deflated and the raw values stored.
967 Any related values passed as Row objects, using the relation name as a
968 key, are reduced to the appropriate foreign key values and stored. If
969 instead of related row objects, a hashref of column, value data is
970 passed, will create the related object first then store.
972 Will even accept arrayrefs of data as a value to a
973 L<DBIx::Class::Relationship/has_many> key, and create the related
974 objects if necessary.
976 Be aware that the input hashref might be edited in place, so don't rely
977 on it being the same after a call to C<set_inflated_columns>. If you
978 need to preserve the hashref, it is sufficient to pass a shallow copy
979 to C<set_inflated_columns>, e.g. ( { %{ $href } } )
981 See also L<DBIx::Class::Relationship::Base/set_from_related>.
985 sub set_inflated_columns {
986 my ( $self, $upd ) = @_;
987 foreach my $key (keys %$upd) {
988 if (ref $upd->{$key}) {
989 my $info = $self->relationship_info($key);
990 my $acc_type = $info->{attrs}{accessor} || '';
991 if ($acc_type eq 'single') {
992 my $rel = delete $upd->{$key};
993 $self->set_from_related($key => $rel);
994 $self->{_relationship_data}{$key} = $rel;
996 elsif ($acc_type eq 'multi') {
997 $self->throw_exception(
998 "Recursive update is not supported over relationships of type '$acc_type' ($key)"
1001 elsif ($self->has_column($key) && exists $self->column_info($key)->{_inflate_info}) {
1002 $self->set_inflated_column($key, delete $upd->{$key});
1006 $self->set_columns($upd);
1011 my $copy = $orig->copy({ change => $to, ... });
1015 =item Arguments: \%replacementdata
1017 =item Returns: The Row object copy
1021 Inserts a new row into the database, as a copy of the original
1022 object. If a hashref of replacement data is supplied, these will take
1023 precedence over data in the original. Also any columns which have
1024 the L<column info attribute|DBIx::Class::ResultSource/add_columns>
1025 C<< is_auto_increment => 1 >> are explicitly removed before the copy,
1026 so that the database can insert its own autoincremented values into
1029 Relationships will be followed by the copy procedure B<only> if the
1030 relationship specifies a true value for its
1031 L<cascade_copy|DBIx::Class::Relationship::Base> attribute. C<cascade_copy>
1032 is set by default on C<has_many> relationships and unset on all others.
1037 my ($self, $changes) = @_;
1039 my $col_data = { %{$self->{_column_data}} };
1041 my $colinfo = $self->columns_info([ keys %$col_data ]);
1042 foreach my $col (keys %$col_data) {
1043 delete $col_data->{$col}
1044 if $colinfo->{$col}{is_auto_increment};
1047 my $new = { _column_data => $col_data };
1048 bless $new, ref $self;
1050 $new->result_source($self->result_source);
1051 $new->set_inflated_columns($changes);
1054 # Its possible we'll have 2 relations to the same Source. We need to make
1055 # sure we don't try to insert the same row twice else we'll violate unique
1057 my $rels_copied = {};
1059 foreach my $rel ($self->result_source->relationships) {
1060 my $rel_info = $self->result_source->relationship_info($rel);
1062 next unless $rel_info->{attrs}{cascade_copy};
1064 my $resolved = $self->result_source->_resolve_condition(
1065 $rel_info->{cond}, $rel, $new
1068 my $copied = $rels_copied->{ $rel_info->{source} } ||= {};
1069 foreach my $related ($self->search_related($rel)) {
1070 my $id_str = join("\0", $related->id);
1071 next if $copied->{$id_str};
1072 $copied->{$id_str} = 1;
1073 my $rel_copy = $related->copy($resolved);
1082 $row->store_column($col => $val);
1086 =item Arguments: $columnname, $value
1088 =item Returns: The value sent to storage
1092 Set a raw value for a column without marking it as changed. This
1093 method is used internally by L</set_column> which you should probably
1096 This is the lowest level at which data is set on a row object,
1097 extend this method to catch all data setting methods.
1102 my ($self, $column, $value) = @_;
1103 $self->throw_exception( "No such column '${column}'" )
1104 unless exists $self->{_column_data}{$column} || $self->has_column($column);
1105 $self->throw_exception( "set_column called for ${column} without value" )
1107 return $self->{_column_data}{$column} = $value;
1110 =head2 inflate_result
1112 Class->inflate_result($result_source, \%me, \%prefetch?)
1116 =item Arguments: $result_source, \%columndata, \%prefetcheddata
1118 =item Returns: A Row object
1122 All L<DBIx::Class::ResultSet> methods that retrieve data from the
1123 database and turn it into row objects call this method.
1125 Extend this method in your Result classes to hook into this process,
1126 for example to rebless the result into a different class.
1128 Reblessing can also be done more easily by setting C<result_class> in
1129 your Result class. See L<DBIx::Class::ResultSource/result_class>.
1131 Different types of results can also be created from a particular
1132 L<DBIx::Class::ResultSet>, see L<DBIx::Class::ResultSet/result_class>.
1136 sub inflate_result {
1137 my ($class, $source, $me, $prefetch) = @_;
1139 $source = $source->resolve
1140 if $source->isa('DBIx::Class::ResultSourceHandle');
1143 { _column_data => $me, _result_source => $source },
1144 ref $class || $class
1147 foreach my $pre (keys %{$prefetch||{}}) {
1149 my $pre_source = $source->related_source($pre)
1150 or $class->throw_exception("Can't prefetch non-existent relationship ${pre}");
1152 my $accessor = $source->relationship_info($pre)->{attrs}{accessor}
1153 or $class->throw_exception("No accessor for prefetched $pre");
1156 if (ref $prefetch->{$pre}[0] eq 'ARRAY') {
1157 @pre_vals = @{$prefetch->{$pre}};
1159 elsif ($accessor eq 'multi') {
1160 $class->throw_exception("Implicit prefetch (via select/columns) not supported with accessor 'multi'");
1163 @pre_vals = $prefetch->{$pre};
1167 for my $me_pref (@pre_vals) {
1169 # FIXME - this should not be necessary
1170 # the collapser currently *could* return bogus elements with all
1171 # columns set to undef
1173 for (values %{$me_pref->[0]}) {
1179 next unless $has_def;
1181 push @pre_objects, $pre_source->result_class->inflate_result(
1182 $pre_source, @$me_pref
1186 if ($accessor eq 'single') {
1187 $new->{_relationship_data}{$pre} = $pre_objects[0];
1189 elsif ($accessor eq 'filter') {
1190 $new->{_inflated_column}{$pre} = $pre_objects[0];
1193 $new->related_resultset($pre)->set_cache(\@pre_objects);
1196 $new->in_storage (1);
1200 =head2 update_or_insert
1202 $row->update_or_insert
1206 =item Arguments: none
1208 =item Returns: Result of update or insert operation
1212 L</Update>s the object if it's already in the database, according to
1213 L</in_storage>, else L</insert>s it.
1215 =head2 insert_or_update
1217 $obj->insert_or_update
1219 Alias for L</update_or_insert>
1223 sub insert_or_update { shift->update_or_insert(@_) }
1225 sub update_or_insert {
1227 return ($self->in_storage ? $self->update : $self->insert);
1232 my @changed_col_names = $row->is_changed();
1233 if ($row->is_changed()) { ... }
1237 =item Arguments: none
1239 =item Returns: 0|1 or @columnnames
1243 In list context returns a list of columns with uncommited changes, or
1244 in scalar context returns a true value if there are uncommitted
1250 return keys %{shift->{_dirty_columns} || {}};
1253 =head2 is_column_changed
1255 if ($row->is_column_changed('col')) { ... }
1259 =item Arguments: $columname
1265 Returns a true value if the column has uncommitted changes.
1269 sub is_column_changed {
1270 my( $self, $col ) = @_;
1271 return exists $self->{_dirty_columns}->{$col};
1274 =head2 result_source
1276 my $resultsource = $row->result_source;
1280 =item Arguments: $result_source_instance
1282 =item Returns: a ResultSource instance
1286 Accessor to the L<DBIx::Class::ResultSource> this object was created from.
1291 $_[0]->throw_exception( 'result_source can be called on instances only' )
1295 ? $_[0]->{_result_source} = $_[1]
1297 # note this is a || not a ||=, the difference is important
1298 : $_[0]->{_result_source} || do {
1299 my $class = ref $_[0];
1300 $_[0]->can('result_source_instance')
1301 ? $_[0]->result_source_instance
1302 : $_[0]->throw_exception(
1303 "No result source instance registered for $class, did you forget to call $class->table(...) ?"
1309 =head2 register_column
1311 $column_info = { .... };
1312 $class->register_column($column_name, $column_info);
1316 =item Arguments: $columnname, \%columninfo
1318 =item Returns: undefined
1322 Registers a column on the class. If the column_info has an 'accessor'
1323 key, creates an accessor named after the value if defined; if there is
1324 no such key, creates an accessor with the same name as the column
1326 The column_info attributes are described in
1327 L<DBIx::Class::ResultSource/add_columns>
1331 sub register_column {
1332 my ($class, $col, $info) = @_;
1334 if (exists $info->{accessor}) {
1335 return unless defined $info->{accessor};
1336 $acc = [ $info->{accessor}, $col ];
1338 $class->mk_group_accessors('column' => $acc);
1341 =head2 get_from_storage
1343 my $copy = $row->get_from_storage($attrs)
1347 =item Arguments: \%attrs
1349 =item Returns: A Row object
1353 Fetches a fresh copy of the Row object from the database and returns it.
1354 Throws an exception if a proper WHERE clause identifying the database row
1355 can not be constructed (i.e. if the original object does not contain its
1357 L<primary key|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
1358 ). If passed the \%attrs argument, will first apply these attributes to
1359 the resultset used to find the row.
1361 This copy can then be used to compare to an existing row object, to
1362 determine if any changes have been made in the database since it was
1365 To just update your Row object with any latest changes from the
1366 database, use L</discard_changes> instead.
1368 The \%attrs argument should be compatible with
1369 L<DBIx::Class::ResultSet/ATTRIBUTES>.
1373 sub get_from_storage {
1374 my $self = shift @_;
1375 my $attrs = shift @_;
1376 my $resultset = $self->result_source->resultset;
1378 if(defined $attrs) {
1379 $resultset = $resultset->search(undef, $attrs);
1382 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
1384 $self->throw_exception($self->{_orig_ident_failreason})
1385 if ! keys %$ident_cond;
1387 return $resultset->find($ident_cond);
1390 =head2 discard_changes ($attrs?)
1392 $row->discard_changes
1396 =item Arguments: none or $attrs
1398 =item Returns: self (updates object in-place)
1402 Re-selects the row from the database, losing any changes that had
1403 been made. Throws an exception if a proper C<WHERE> clause identifying
1404 the database row can not be constructed (i.e. if the original object
1405 does not contain its entire
1406 L<primary key|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>).
1408 This method can also be used to refresh from storage, retrieving any
1409 changes made since the row was last read from storage.
1411 $attrs, if supplied, is expected to be a hashref of attributes suitable for passing as the
1412 second argument to C<< $resultset->search($cond, $attrs) >>;
1414 Note: If you are using L<DBIx::Class::Storage::DBI::Replicated> as your
1415 storage, please kept in mind that if you L</discard_changes> on a row that you
1416 just updated or created, you should wrap the entire bit inside a transaction.
1417 Otherwise you run the risk that you insert or update to the master database
1418 but read from a replicant database that has not yet been updated from the
1419 master. This will result in unexpected results.
1423 sub discard_changes {
1424 my ($self, $attrs) = @_;
1425 return unless $self->in_storage; # Don't reload if we aren't real!
1427 # add a replication default to read from the master only
1428 $attrs = { force_pool => 'master', %{$attrs||{}} };
1430 if( my $current_storage = $self->get_from_storage($attrs)) {
1432 # Set $self to the current.
1433 %$self = %$current_storage;
1435 # Avoid a possible infinite loop with
1436 # sub DESTROY { $_[0]->discard_changes }
1437 bless $current_storage, 'Do::Not::Exist';
1442 $self->in_storage(0);
1448 =head2 throw_exception
1450 See L<DBIx::Class::Schema/throw_exception>.
1454 sub throw_exception {
1457 if (ref $self && ref $self->result_source ) {
1458 $self->result_source->throw_exception(@_)
1461 DBIx::Class::Exception->throw(@_);
1471 =item Arguments: none
1473 =item Returns: A list of primary key values
1477 Returns the primary key(s) for a row. Can't be called as a class method.
1478 Actually implemented in L<DBIx::Class::PK>
1484 Matt S. Trout <mst@shadowcatsystems.co.uk>
1488 You may distribute this code under the same terms as Perl itself.