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}
24 __PACKAGE__->mk_group_accessors('simple' => qw/_source_handle/);
28 DBIx::Class::Row - Basic row methods
34 This class is responsible for defining and doing basic operations on rows
35 derived from L<DBIx::Class::ResultSource> objects.
37 Row objects are returned from L<DBIx::Class::ResultSet>s using the
38 L<create|DBIx::Class::ResultSet/create>, L<find|DBIx::Class::ResultSet/find>,
39 L<next|DBIx::Class::ResultSet/next> and L<all|DBIx::Class::ResultSet/all> methods,
40 as well as invocations of 'single' (
41 L<belongs_to|DBIx::Class::Relationship/belongs_to>,
42 L<has_one|DBIx::Class::Relationship/has_one> or
43 L<might_have|DBIx::Class::Relationship/might_have>)
44 relationship accessors of L<DBIx::Class::Row> objects.
50 my $row = My::Class->new(\%attrs);
52 my $row = $schema->resultset('MySource')->new(\%colsandvalues);
56 =item Arguments: \%attrs or \%colsandvalues
58 =item Returns: A Row object
62 While you can create a new row object by calling C<new> directly on
63 this class, you are better off calling it on a
64 L<DBIx::Class::ResultSet> object.
66 When calling it directly, you will not get a complete, usable row
67 object until you pass or set the C<source_handle> attribute, to a
68 L<DBIx::Class::ResultSource> instance that is attached to a
69 L<DBIx::Class::Schema> with a valid connection.
71 C<$attrs> is a hashref of column name, value data. It can also contain
72 some other attributes such as the C<source_handle>.
74 Passing an object, or an arrayref of objects as a value will call
75 L<DBIx::Class::Relationship::Base/set_from_related> for you. When
76 passed a hashref or an arrayref of hashrefs as the value, these will
77 be turned into objects via new_related, and treated as if you had
80 For a more involved explanation, see L<DBIx::Class::ResultSet/create>.
82 Please note that if a value is not passed to new, no value will be sent
83 in the SQL INSERT call, and the column will therefore assume whatever
84 default value was specified in your database. While DBIC will retrieve the
85 value of autoincrement columns, it will never make an explicit database
86 trip to retrieve default values assigned by the RDBMS. You can explicitly
87 request that all values be fetched back from the database by calling
88 L</discard_changes>, or you can supply an explicit C<undef> to columns
89 with NULL as the default, and save yourself a SELECT.
93 The behavior described above will backfire if you use a foreign key column
94 with a database-defined default. If you call the relationship accessor on
95 an object that doesn't have a set value for the FK column, DBIC will throw
96 an exception, as it has no way of knowing the PK of the related object (if
101 ## 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().
102 ## This only works because DBIC doesnt yet care to check whether the new_related objects have been passed all their mandatory columns
103 ## When doing the later insert, we need to make sure the PKs are set.
104 ## using _relationship_data in new and funky ways..
105 ## check Relationship::CascadeActions and Relationship::Accessor for compat
108 sub __new_related_find_or_new_helper {
109 my ($self, $relname, $data) = @_;
111 my $rsrc = $self->result_source;
113 # create a mock-object so all new/set_column component overrides will run:
114 my $rel_rs = $rsrc->related_source($relname)->resultset;
115 my $new_rel_obj = $rel_rs->new_result($data);
116 my $proc_data = { $new_rel_obj->get_columns };
118 if ($self->__their_pk_needs_us($relname)) {
119 MULTICREATE_DEBUG and warn "MC $self constructing $relname via new_result";
122 elsif ($rsrc->_pk_depends_on($relname, $proc_data )) {
123 if (! keys %$proc_data) {
124 # there is nothing to search for - blind create
125 MULTICREATE_DEBUG and warn "MC $self constructing default-insert $relname";
128 MULTICREATE_DEBUG and warn "MC $self constructing $relname via find_or_new";
129 # this is not *really* find or new, as we don't want to double-new the
130 # data (thus potentially double encoding or whatever)
131 my $exists = $rel_rs->find ($proc_data);
132 return $exists if $exists;
137 my $us = $rsrc->source_name;
138 $self->throw_exception ("'$us' neither depends nor is depended on by '$relname', something is wrong...");
142 sub __their_pk_needs_us { # this should maybe be in resultsource.
143 my ($self, $relname) = @_;
144 my $source = $self->result_source;
145 my $reverse = $source->reverse_relationship_info($relname);
146 my $rel_source = $source->related_source($relname);
147 my $us = { $self->get_columns };
148 foreach my $key (keys %$reverse) {
149 # if their primary key depends on us, then we have to
150 # just create a result and we'll fill it out afterwards
151 return 1 if $rel_source->_pk_depends_on($key, $us);
157 my ($class, $attrs) = @_;
158 $class = ref $class if ref $class;
165 if (my $handle = delete $attrs->{-source_handle}) {
166 $new->_source_handle($handle);
170 if ($source = delete $attrs->{-result_source}) {
171 $new->result_source($source);
174 if (my $related = delete $attrs->{-cols_from_relations}) {
175 @{$new->{_ignore_at_insert}={}}{@$related} = ();
179 $new->throw_exception("attrs must be a hashref")
180 unless ref($attrs) eq 'HASH';
182 my ($related,$inflated);
184 foreach my $key (keys %$attrs) {
185 if (ref $attrs->{$key}) {
186 ## Can we extract this lot to use with update(_or .. ) ?
187 $new->throw_exception("Can't do multi-create without result source")
189 my $info = $source->relationship_info($key);
190 my $acc_type = $info->{attrs}{accessor} || '';
191 if ($acc_type eq 'single') {
192 my $rel_obj = delete $attrs->{$key};
193 if(!blessed $rel_obj) {
194 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
197 if ($rel_obj->in_storage) {
198 $new->{_rel_in_storage}{$key} = 1;
199 $new->set_from_related($key, $rel_obj);
201 MULTICREATE_DEBUG and warn "MC $new uninserted $key $rel_obj\n";
204 $related->{$key} = $rel_obj;
207 elsif ($acc_type eq 'multi' && ref $attrs->{$key} eq 'ARRAY' ) {
208 my $others = delete $attrs->{$key};
209 my $total = @$others;
211 foreach my $idx (0 .. $#$others) {
212 my $rel_obj = $others->[$idx];
213 if(!blessed $rel_obj) {
214 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
217 if ($rel_obj->in_storage) {
218 $rel_obj->throw_exception ('A multi relationship can not be pre-existing when doing multicreate. Something went wrong');
220 MULTICREATE_DEBUG and
221 warn "MC $new uninserted $key $rel_obj (${\($idx+1)} of $total)\n";
223 push(@objects, $rel_obj);
225 $related->{$key} = \@objects;
228 elsif ($acc_type eq 'filter') {
229 ## 'filter' should disappear and get merged in with 'single' above!
230 my $rel_obj = delete $attrs->{$key};
231 if(!blessed $rel_obj) {
232 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
234 if ($rel_obj->in_storage) {
235 $new->{_rel_in_storage}{$key} = 1;
238 MULTICREATE_DEBUG and warn "MC $new uninserted $key $rel_obj";
240 $inflated->{$key} = $rel_obj;
242 } elsif ($class->has_column($key)
243 && $class->column_info($key)->{_inflate_info}) {
244 $inflated->{$key} = $attrs->{$key};
248 $new->throw_exception("No such column $key on $class")
249 unless $class->has_column($key);
250 $new->store_column($key => $attrs->{$key});
253 $new->{_relationship_data} = $related if $related;
254 $new->{_inflated_column} = $inflated if $inflated;
266 =item Arguments: none
268 =item Returns: The Row object
272 Inserts an object previously created by L</new> into the database if
273 it isn't already in there. Returns the object itself. Requires the
274 object's result source to be set, or the class to have a
275 result_source_instance method. To insert an entirely new row into
276 the database, use C<create> (see L<DBIx::Class::ResultSet/create>).
278 To fetch an uninserted row object, call
279 L<new|DBIx::Class::ResultSet/new> on a resultset.
281 This will also insert any uninserted, related objects held inside this
282 one, see L<DBIx::Class::ResultSet/create> for more details.
288 return $self if $self->in_storage;
289 my $source = $self->result_source;
290 $source ||= $self->result_source($self->result_source_instance)
291 if $self->can('result_source_instance');
292 $self->throw_exception("No result_source set on this object; can't insert")
297 # Check if we stored uninserted relobjs here in new()
298 my %related_stuff = (%{$self->{_relationship_data} || {}},
299 %{$self->{_inflated_column} || {}});
301 # insert what needs to be inserted before us
303 for my $relname (keys %related_stuff) {
304 my $rel_obj = $related_stuff{$relname};
306 if (! $self->{_rel_in_storage}{$relname}) {
307 next unless (blessed $rel_obj && $rel_obj->isa('DBIx::Class::Row'));
309 next unless $source->_pk_depends_on(
310 $relname, { $rel_obj->get_columns }
313 # The guard will save us if we blow out of this scope via die
314 $rollback_guard ||= $source->storage->txn_scope_guard;
316 MULTICREATE_DEBUG and warn "MC $self pre-reconstructing $relname $rel_obj\n";
318 my $them = { %{$rel_obj->{_relationship_data} || {} }, $rel_obj->get_columns };
321 # if there are no keys - nothing to search for
322 if (keys %$them and $existing = $self->result_source
323 ->related_source($relname)
327 %{$rel_obj} = %{$existing};
333 $self->{_rel_in_storage}{$relname} = 1;
336 $self->set_from_related($relname, $rel_obj);
337 delete $related_stuff{$relname};
340 # start a transaction here if not started yet and there is more stuff
342 if (keys %related_stuff) {
343 $rollback_guard ||= $source->storage->txn_scope_guard
349 for ($self->primary_columns) {
351 not defined $self->get_column($_)
353 (ref($self->get_column($_)) eq 'SCALAR')
355 my $col_info = $source->column_info($_);
356 $auto_pri{$_} = $auto_idx++ unless $col_info->{auto_nextval}; # auto_nextval's are pre-fetched in the storage
360 MULTICREATE_DEBUG and do {
361 no warnings 'uninitialized';
362 warn "MC $self inserting (".join(', ', $self->get_columns).")\n";
364 my $updated_cols = $source->storage->insert(
366 { $self->get_columns },
367 (keys %auto_pri) && $source->storage->_supports_insert_returning
368 ? { returning => [ sort { $auto_pri{$a} <=> $auto_pri{$b} } keys %auto_pri ] }
373 foreach my $col (keys %$updated_cols) {
374 $self->store_column($col, $updated_cols->{$col});
375 delete $auto_pri{$col};
378 if (keys %auto_pri) {
379 my @missing = sort { $auto_pri{$a} <=> $auto_pri{$b} } keys %auto_pri;
380 MULTICREATE_DEBUG and warn "MC $self fetching missing PKs ".join(', ', @missing )."\n";
381 my $storage = $self->result_source->storage;
382 $self->throw_exception( "Missing primary key but Storage doesn't support last_insert_id" )
383 unless $storage->can('last_insert_id');
384 my @ids = $storage->last_insert_id($self->result_source, @missing);
385 $self->throw_exception( "Can't get last insert id" )
386 unless (@ids == @missing);
387 $self->store_column($missing[$_] => $ids[$_]) for 0 .. $#missing;
390 $self->{_dirty_columns} = {};
391 $self->{related_resultsets} = {};
393 foreach my $relname (keys %related_stuff) {
394 next unless $source->has_relationship ($relname);
396 my @cands = ref $related_stuff{$relname} eq 'ARRAY'
397 ? @{$related_stuff{$relname}}
398 : $related_stuff{$relname}
401 if (@cands && blessed $cands[0] && $cands[0]->isa('DBIx::Class::Row')
403 my $reverse = $source->reverse_relationship_info($relname);
404 foreach my $obj (@cands) {
405 $obj->set_from_related($_, $self) for keys %$reverse;
406 if ($self->__their_pk_needs_us($relname)) {
407 if (exists $self->{_ignore_at_insert}{$relname}) {
408 MULTICREATE_DEBUG and warn "MC $self skipping post-insert on $relname";
411 MULTICREATE_DEBUG and warn "MC $self inserting $relname $obj";
415 MULTICREATE_DEBUG and warn "MC $self post-inserting $obj";
422 $self->in_storage(1);
423 delete $self->{_orig_ident};
424 delete $self->{_orig_ident_failreason};
425 delete $self->{_ignore_at_insert};
426 $rollback_guard->commit if $rollback_guard;
433 $row->in_storage; # Get value
434 $row->in_storage(1); # Set value
438 =item Arguments: none or 1|0
444 Indicates whether the object exists as a row in the database or
445 not. This is set to true when L<DBIx::Class::ResultSet/find>,
446 L<DBIx::Class::ResultSet/create> or L<DBIx::Class::ResultSet/insert>
449 Creating a row object using L<DBIx::Class::ResultSet/new>, or calling
450 L</delete> on one, sets it to false.
455 my ($self, $val) = @_;
456 $self->{_in_storage} = $val if @_ > 1;
457 return $self->{_in_storage} ? 1 : 0;
462 $row->update(\%columns?)
466 =item Arguments: none or a hashref
468 =item Returns: The Row object
472 Throws an exception if the row object is not yet in the database,
473 according to L</in_storage>.
475 This method issues an SQL UPDATE query to commit any changes to the
476 object to the database if required (see L</get_dirty_columns>).
477 It throws an exception if a proper WHERE clause uniquely identifying
478 the database row can not be constructed (see
479 L<significance of primary keys|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
482 Also takes an optional hashref of C<< column_name => value >> pairs
483 to update on the object first. Be aware that the hashref will be
484 passed to C<set_inflated_columns>, which might edit it in place, so
485 don't rely on it being the same after a call to C<update>. If you
486 need to preserve the hashref, it is sufficient to pass a shallow copy
487 to C<update>, e.g. ( { %{ $href } } )
489 If the values passed or any of the column values set on the object
490 contain scalar references, e.g.:
492 $row->last_modified(\'NOW()');
494 $row->update({ last_modified => \'NOW()' });
496 The update will pass the values verbatim into SQL. (See
497 L<SQL::Abstract> docs). The values in your Row object will NOT change
498 as a result of the update call, if you want the object to be updated
499 with the actual values from the database, call L</discard_changes>
502 $row->update()->discard_changes();
504 To determine before calling this method, which column values have
505 changed and will be updated, call L</get_dirty_columns>.
507 To check if any columns will be updated, call L</is_changed>.
509 To force a column to be updated, call L</make_column_dirty> before
515 my ($self, $upd) = @_;
517 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
519 $self->set_inflated_columns($upd) if $upd;
520 my %to_update = $self->get_dirty_columns;
521 return $self unless keys %to_update;
523 $self->throw_exception( "Not in database" ) unless $self->in_storage;
525 $self->throw_exception($self->{_orig_ident_failreason})
526 if ! keys %$ident_cond;
528 my $rows = $self->result_source->storage->update(
529 $self->result_source, \%to_update, $ident_cond
532 $self->throw_exception( "Can't update ${self}: row not found" );
533 } elsif ($rows > 1) {
534 $self->throw_exception("Can't update ${self}: updated more than one row");
536 $self->{_dirty_columns} = {};
537 $self->{related_resultsets} = {};
538 delete $self->{_orig_ident};
548 =item Arguments: none
550 =item Returns: The Row object
554 Throws an exception if the object is not in the database according to
555 L</in_storage>. Also throws an exception if a proper WHERE clause
556 uniquely identifying the database row can not be constructed (see
557 L<significance of primary keys|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
560 The object is still perfectly usable, but L</in_storage> will
561 now return 0 and the object must be reinserted using L</insert>
562 before it can be used to L</update> the row again.
564 If you delete an object in a class with a C<has_many> relationship, an
565 attempt is made to delete all the related objects as well. To turn
566 this behaviour off, pass C<< cascade_delete => 0 >> in the C<$attr>
567 hashref of the relationship, see L<DBIx::Class::Relationship>. Any
568 database-level cascade or restrict will take precedence over a
569 DBIx-Class-based cascading delete, since DBIx-Class B<deletes the
570 main row first> and only then attempts to delete any remaining related
573 If you delete an object within a txn_do() (see L<DBIx::Class::Storage/txn_do>)
574 and the transaction subsequently fails, the row object will remain marked as
575 not being in storage. If you know for a fact that the object is still in
576 storage (i.e. by inspecting the cause of the transaction's failure), you can
577 use C<< $obj->in_storage(1) >> to restore consistency between the object and
578 the database. This would allow a subsequent C<< $obj->delete >> to work
581 See also L<DBIx::Class::ResultSet/delete>.
588 $self->throw_exception( "Not in database" ) unless $self->in_storage;
590 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
591 $self->throw_exception($self->{_orig_ident_failreason})
592 if ! keys %$ident_cond;
594 $self->result_source->storage->delete(
595 $self->result_source, $ident_cond
598 delete $self->{_orig_ident}; # no longer identifiable
599 $self->in_storage(undef);
602 $self->throw_exception("Can't do class delete without a ResultSource instance")
603 unless $self->can('result_source_instance');
604 my $attrs = @_ > 1 && ref $_[$#_] eq 'HASH' ? { %{pop(@_)} } : {};
605 my $query = ref $_[0] eq 'HASH' ? $_[0] : {@_};
606 $self->result_source_instance->resultset->search(@_)->delete;
613 my $val = $row->get_column($col);
617 =item Arguments: $columnname
619 =item Returns: The value of the column
623 Throws an exception if the column name given doesn't exist according
626 Returns a raw column value from the row object, if it has already
627 been fetched from the database or set by an accessor.
629 If an L<inflated value|DBIx::Class::InflateColumn> has been set, it
630 will be deflated and returned.
632 Note that if you used the C<columns> or the C<select/as>
633 L<search attributes|DBIx::Class::ResultSet/ATTRIBUTES> on the resultset from
634 which C<$row> was derived, and B<did not include> C<$columnname> in the list,
635 this method will return C<undef> even if the database contains some value.
637 To retrieve all loaded column values as a hash, use L</get_columns>.
642 my ($self, $column) = @_;
643 $self->throw_exception( "Can't fetch data as class method" ) unless ref $self;
644 return $self->{_column_data}{$column} if exists $self->{_column_data}{$column};
645 if (exists $self->{_inflated_column}{$column}) {
646 return $self->store_column($column,
647 $self->_deflated_column($column, $self->{_inflated_column}{$column}));
649 $self->throw_exception( "No such column '${column}'" ) unless $self->has_column($column);
653 =head2 has_column_loaded
655 if ( $row->has_column_loaded($col) ) {
656 print "$col has been loaded from db";
661 =item Arguments: $columnname
667 Returns a true value if the column value has been loaded from the
668 database (or set locally).
672 sub has_column_loaded {
673 my ($self, $column) = @_;
674 $self->throw_exception( "Can't call has_column data as class method" ) unless ref $self;
675 return 1 if exists $self->{_inflated_column}{$column};
676 return exists $self->{_column_data}{$column};
681 my %data = $row->get_columns;
685 =item Arguments: none
687 =item Returns: A hash of columnname, value pairs.
691 Returns all loaded column data as a hash, containing raw values. To
692 get just one value for a particular column, use L</get_column>.
694 See L</get_inflated_columns> to get the inflated values.
700 if (exists $self->{_inflated_column}) {
701 foreach my $col (keys %{$self->{_inflated_column}}) {
702 $self->store_column($col, $self->_deflated_column($col, $self->{_inflated_column}{$col}))
703 unless exists $self->{_column_data}{$col};
706 return %{$self->{_column_data}};
709 =head2 get_dirty_columns
711 my %data = $row->get_dirty_columns;
715 =item Arguments: none
717 =item Returns: A hash of column, value pairs
721 Only returns the column, value pairs for those columns that have been
722 changed on this object since the last L</update> or L</insert> call.
724 See L</get_columns> to fetch all column/value pairs.
728 sub get_dirty_columns {
730 return map { $_ => $self->{_column_data}{$_} }
731 keys %{$self->{_dirty_columns}};
734 =head2 make_column_dirty
736 $row->make_column_dirty($col)
740 =item Arguments: $columnname
742 =item Returns: undefined
746 Throws an exception if the column does not exist.
748 Marks a column as having been changed regardless of whether it has
752 sub make_column_dirty {
753 my ($self, $column) = @_;
755 $self->throw_exception( "No such column '${column}'" )
756 unless exists $self->{_column_data}{$column} || $self->has_column($column);
758 # the entire clean/dirty code relies on exists, not on true/false
759 return 1 if exists $self->{_dirty_columns}{$column};
761 $self->{_dirty_columns}{$column} = 1;
763 # if we are just now making the column dirty, and if there is an inflated
764 # value, force it over the deflated one
765 if (exists $self->{_inflated_column}{$column}) {
766 $self->store_column($column,
767 $self->_deflated_column(
768 $column, $self->{_inflated_column}{$column}
774 =head2 get_inflated_columns
776 my %inflated_data = $obj->get_inflated_columns;
780 =item Arguments: none
782 =item Returns: A hash of column, object|value pairs
786 Returns a hash of all column keys and associated values. Values for any
787 columns set to use inflation will be inflated and returns as objects.
789 See L</get_columns> to get the uninflated values.
791 See L<DBIx::Class::InflateColumn> for how to setup inflation.
795 sub get_inflated_columns {
798 my %loaded_colinfo = (map
799 { $_ => $self->column_info($_) }
800 (grep { $self->has_column_loaded($_) } $self->columns)
804 for my $col (keys %loaded_colinfo) {
805 if (exists $loaded_colinfo{$col}{accessor}) {
806 my $acc = $loaded_colinfo{$col}{accessor};
807 $inflated{$col} = $self->$acc if defined $acc;
810 $inflated{$col} = $self->$col;
814 # return all loaded columns with the inflations overlayed on top
815 return ($self->get_columns, %inflated);
818 sub _is_column_numeric {
819 my ($self, $column) = @_;
820 my $colinfo = $self->column_info ($column);
822 # cache for speed (the object may *not* have a resultsource instance)
823 if (not defined $colinfo->{is_numeric} && $self->_source_handle) {
824 $colinfo->{is_numeric} =
825 $self->result_source->schema->storage->is_datatype_numeric ($colinfo->{data_type})
831 return $colinfo->{is_numeric};
836 $row->set_column($col => $val);
840 =item Arguments: $columnname, $value
842 =item Returns: $value
846 Sets a raw column value. If the new value is different from the old one,
847 the column is marked as dirty for when you next call L</update>.
849 If passed an object or reference as a value, this method will happily
850 attempt to store it, and a later L</insert> or L</update> will try and
851 stringify/numify as appropriate. To set an object to be deflated
852 instead, see L</set_inflated_columns>.
857 my ($self, $column, $new_value) = @_;
859 # if we can't get an ident condition on first try - mark the object as unidentifiable
860 # (by using an empty hashref) and store the error for further diag
861 unless ($self->{_orig_ident}) {
863 $self->{_orig_ident} = $self->ident_condition
866 $self->{_orig_ident_failreason} = $_;
867 $self->{_orig_ident} = {};
871 my $old_value = $self->get_column($column);
872 $new_value = $self->store_column($column, $new_value);
875 $self->{_dirty_columns}{$column}
877 $self->in_storage # no point tracking dirtyness on uninserted data
878 ? ! $self->_eq_column_values ($column, $old_value, $new_value)
882 # FIXME sadly the update code just checks for keys, not for their value
883 $self->{_dirty_columns}{$column} = 1 if $dirty;
885 # XXX clear out the relation cache for this column
886 delete $self->{related_resultsets}{$column};
891 sub _eq_column_values {
892 my ($self, $col, $old, $new) = @_;
894 if (defined $old xor defined $new) {
897 elsif (not defined $old) { # both undef
900 elsif ($old eq $new) {
903 elsif ($self->_is_column_numeric($col)) { # do a numeric comparison if datatype allows it
913 $row->set_columns({ $col => $val, ... });
917 =item Arguments: \%columndata
919 =item Returns: The Row object
923 Sets multiple column, raw value pairs at once.
925 Works as L</set_column>.
930 my ($self,$data) = @_;
931 foreach my $col (keys %$data) {
932 $self->set_column($col,$data->{$col});
937 =head2 set_inflated_columns
939 $row->set_inflated_columns({ $col => $val, $relname => $obj, ... });
943 =item Arguments: \%columndata
945 =item Returns: The Row object
949 Sets more than one column value at once. Any inflated values are
950 deflated and the raw values stored.
952 Any related values passed as Row objects, using the relation name as a
953 key, are reduced to the appropriate foreign key values and stored. If
954 instead of related row objects, a hashref of column, value data is
955 passed, will create the related object first then store.
957 Will even accept arrayrefs of data as a value to a
958 L<DBIx::Class::Relationship/has_many> key, and create the related
959 objects if necessary.
961 Be aware that the input hashref might be edited in place, so don't rely
962 on it being the same after a call to C<set_inflated_columns>. If you
963 need to preserve the hashref, it is sufficient to pass a shallow copy
964 to C<set_inflated_columns>, e.g. ( { %{ $href } } )
966 See also L<DBIx::Class::Relationship::Base/set_from_related>.
970 sub set_inflated_columns {
971 my ( $self, $upd ) = @_;
972 foreach my $key (keys %$upd) {
973 if (ref $upd->{$key}) {
974 my $info = $self->relationship_info($key);
975 my $acc_type = $info->{attrs}{accessor} || '';
976 if ($acc_type eq 'single') {
977 my $rel = delete $upd->{$key};
978 $self->set_from_related($key => $rel);
979 $self->{_relationship_data}{$key} = $rel;
981 elsif ($acc_type eq 'multi') {
982 $self->throw_exception(
983 "Recursive update is not supported over relationships of type '$acc_type' ($key)"
986 elsif ($self->has_column($key) && exists $self->column_info($key)->{_inflate_info}) {
987 $self->set_inflated_column($key, delete $upd->{$key});
991 $self->set_columns($upd);
996 my $copy = $orig->copy({ change => $to, ... });
1000 =item Arguments: \%replacementdata
1002 =item Returns: The Row object copy
1006 Inserts a new row into the database, as a copy of the original
1007 object. If a hashref of replacement data is supplied, these will take
1008 precedence over data in the original. Also any columns which have
1009 the L<column info attribute|DBIx::Class::ResultSource/add_columns>
1010 C<< is_auto_increment => 1 >> are explicitly removed before the copy,
1011 so that the database can insert its own autoincremented values into
1014 Relationships will be followed by the copy procedure B<only> if the
1015 relationship specifies a true value for its
1016 L<cascade_copy|DBIx::Class::Relationship::Base> attribute. C<cascade_copy>
1017 is set by default on C<has_many> relationships and unset on all others.
1022 my ($self, $changes) = @_;
1024 my $col_data = { %{$self->{_column_data}} };
1025 foreach my $col (keys %$col_data) {
1026 delete $col_data->{$col}
1027 if $self->result_source->column_info($col)->{is_auto_increment};
1030 my $new = { _column_data => $col_data };
1031 bless $new, ref $self;
1033 $new->result_source($self->result_source);
1034 $new->set_inflated_columns($changes);
1037 # Its possible we'll have 2 relations to the same Source. We need to make
1038 # sure we don't try to insert the same row twice else we'll violate unique
1040 my $rels_copied = {};
1042 foreach my $rel ($self->result_source->relationships) {
1043 my $rel_info = $self->result_source->relationship_info($rel);
1045 next unless $rel_info->{attrs}{cascade_copy};
1047 my $resolved = $self->result_source->_resolve_condition(
1048 $rel_info->{cond}, $rel, $new
1051 my $copied = $rels_copied->{ $rel_info->{source} } ||= {};
1052 foreach my $related ($self->search_related($rel)) {
1053 my $id_str = join("\0", $related->id);
1054 next if $copied->{$id_str};
1055 $copied->{$id_str} = 1;
1056 my $rel_copy = $related->copy($resolved);
1065 $row->store_column($col => $val);
1069 =item Arguments: $columnname, $value
1071 =item Returns: The value sent to storage
1075 Set a raw value for a column without marking it as changed. This
1076 method is used internally by L</set_column> which you should probably
1079 This is the lowest level at which data is set on a row object,
1080 extend this method to catch all data setting methods.
1085 my ($self, $column, $value) = @_;
1086 $self->throw_exception( "No such column '${column}'" )
1087 unless exists $self->{_column_data}{$column} || $self->has_column($column);
1088 $self->throw_exception( "set_column called for ${column} without value" )
1090 return $self->{_column_data}{$column} = $value;
1093 =head2 inflate_result
1095 Class->inflate_result($result_source, \%me, \%prefetch?)
1099 =item Arguments: $result_source, \%columndata, \%prefetcheddata
1101 =item Returns: A Row object
1105 All L<DBIx::Class::ResultSet> methods that retrieve data from the
1106 database and turn it into row objects call this method.
1108 Extend this method in your Result classes to hook into this process,
1109 for example to rebless the result into a different class.
1111 Reblessing can also be done more easily by setting C<result_class> in
1112 your Result class. See L<DBIx::Class::ResultSource/result_class>.
1114 Different types of results can also be created from a particular
1115 L<DBIx::Class::ResultSet>, see L<DBIx::Class::ResultSet/result_class>.
1119 sub inflate_result {
1120 my ($class, $source, $me, $prefetch) = @_;
1122 my ($source_handle) = $source;
1124 if ($source->isa('DBIx::Class::ResultSourceHandle')) {
1125 $source = $source_handle->resolve
1128 $source_handle = $source->handle
1132 _source_handle => $source_handle,
1133 _column_data => $me,
1135 bless $new, (ref $class || $class);
1137 foreach my $pre (keys %{$prefetch||{}}) {
1139 my $pre_source = $source->related_source($pre)
1140 or $class->throw_exception("Can't prefetch non-existent relationship ${pre}");
1142 my $accessor = $source->relationship_info($pre)->{attrs}{accessor}
1143 or $class->throw_exception("No accessor for prefetched $pre");
1146 if (ref $prefetch->{$pre}[0] eq 'ARRAY') {
1147 @pre_vals = @{$prefetch->{$pre}};
1149 elsif ($accessor eq 'multi') {
1150 $class->throw_exception("Implicit prefetch (via select/columns) not supported with accessor 'multi'");
1153 @pre_vals = $prefetch->{$pre};
1157 for my $me_pref (@pre_vals) {
1159 # FIXME - this should not be necessary
1160 # the collapser currently *could* return bogus elements with all
1161 # columns set to undef
1163 for (values %{$me_pref->[0]}) {
1169 next unless $has_def;
1171 push @pre_objects, $pre_source->result_class->inflate_result(
1172 $pre_source, @$me_pref
1176 if ($accessor eq 'single') {
1177 $new->{_relationship_data}{$pre} = $pre_objects[0];
1179 elsif ($accessor eq 'filter') {
1180 $new->{_inflated_column}{$pre} = $pre_objects[0];
1183 $new->related_resultset($pre)->set_cache(\@pre_objects);
1186 $new->in_storage (1);
1190 =head2 update_or_insert
1192 $row->update_or_insert
1196 =item Arguments: none
1198 =item Returns: Result of update or insert operation
1202 L</Update>s the object if it's already in the database, according to
1203 L</in_storage>, else L</insert>s it.
1205 =head2 insert_or_update
1207 $obj->insert_or_update
1209 Alias for L</update_or_insert>
1213 sub insert_or_update { shift->update_or_insert(@_) }
1215 sub update_or_insert {
1217 return ($self->in_storage ? $self->update : $self->insert);
1222 my @changed_col_names = $row->is_changed();
1223 if ($row->is_changed()) { ... }
1227 =item Arguments: none
1229 =item Returns: 0|1 or @columnnames
1233 In list context returns a list of columns with uncommited changes, or
1234 in scalar context returns a true value if there are uncommitted
1240 return keys %{shift->{_dirty_columns} || {}};
1243 =head2 is_column_changed
1245 if ($row->is_column_changed('col')) { ... }
1249 =item Arguments: $columname
1255 Returns a true value if the column has uncommitted changes.
1259 sub is_column_changed {
1260 my( $self, $col ) = @_;
1261 return exists $self->{_dirty_columns}->{$col};
1264 =head2 result_source
1266 my $resultsource = $row->result_source;
1270 =item Arguments: none
1272 =item Returns: a ResultSource instance
1276 Accessor to the L<DBIx::Class::ResultSource> this object was created from.
1284 $self->_source_handle($_[0]->handle);
1286 $self->_source_handle->resolve;
1290 =head2 register_column
1292 $column_info = { .... };
1293 $class->register_column($column_name, $column_info);
1297 =item Arguments: $columnname, \%columninfo
1299 =item Returns: undefined
1303 Registers a column on the class. If the column_info has an 'accessor'
1304 key, creates an accessor named after the value if defined; if there is
1305 no such key, creates an accessor with the same name as the column
1307 The column_info attributes are described in
1308 L<DBIx::Class::ResultSource/add_columns>
1312 sub register_column {
1313 my ($class, $col, $info) = @_;
1315 if (exists $info->{accessor}) {
1316 return unless defined $info->{accessor};
1317 $acc = [ $info->{accessor}, $col ];
1319 $class->mk_group_accessors('column' => $acc);
1322 =head2 get_from_storage
1324 my $copy = $row->get_from_storage($attrs)
1328 =item Arguments: \%attrs
1330 =item Returns: A Row object
1334 Fetches a fresh copy of the Row object from the database and returns it.
1335 Throws an exception if a proper WHERE clause identifying the database row
1336 can not be constructed (i.e. if the original object does not contain its
1338 L<primary key|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
1339 ). If passed the \%attrs argument, will first apply these attributes to
1340 the resultset used to find the row.
1342 This copy can then be used to compare to an existing row object, to
1343 determine if any changes have been made in the database since it was
1346 To just update your Row object with any latest changes from the
1347 database, use L</discard_changes> instead.
1349 The \%attrs argument should be compatible with
1350 L<DBIx::Class::ResultSet/ATTRIBUTES>.
1354 sub get_from_storage {
1355 my $self = shift @_;
1356 my $attrs = shift @_;
1357 my $resultset = $self->result_source->resultset;
1359 if(defined $attrs) {
1360 $resultset = $resultset->search(undef, $attrs);
1363 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
1365 $self->throw_exception($self->{_orig_ident_failreason})
1366 if ! keys %$ident_cond;
1368 return $resultset->find($ident_cond);
1371 =head2 discard_changes ($attrs)
1373 Re-selects the row from the database, losing any changes that had
1374 been made. Throws an exception if a proper WHERE clause identifying
1375 the database row can not be constructed (i.e. if the original object
1376 does not contain its entire
1377 L<primary key|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
1380 This method can also be used to refresh from storage, retrieving any
1381 changes made since the row was last read from storage.
1383 $attrs is expected to be a hashref of attributes suitable for passing as the
1384 second argument to $resultset->search($cond, $attrs);
1388 sub discard_changes {
1389 my ($self, $attrs) = @_;
1390 return unless $self->in_storage; # Don't reload if we aren't real!
1392 # add a replication default to read from the master only
1393 $attrs = { force_pool => 'master', %{$attrs||{}} };
1395 if( my $current_storage = $self->get_from_storage($attrs)) {
1397 # Set $self to the current.
1398 %$self = %$current_storage;
1400 # Avoid a possible infinite loop with
1401 # sub DESTROY { $_[0]->discard_changes }
1402 bless $current_storage, 'Do::Not::Exist';
1407 $self->in_storage(0);
1413 =head2 throw_exception
1415 See L<DBIx::Class::Schema/throw_exception>.
1419 sub throw_exception {
1422 if (ref $self && ref $self->result_source && $self->result_source->schema) {
1423 $self->result_source->schema->throw_exception(@_)
1426 DBIx::Class::Exception->throw(@_);
1436 =item Arguments: none
1438 =item Returns: A list of primary key values
1442 Returns the primary key(s) for a row. Can't be called as a class method.
1443 Actually implemented in L<DBIx::Class::PK>
1445 =head2 discard_changes
1447 $row->discard_changes
1451 =item Arguments: none
1453 =item Returns: nothing (updates object in-place)
1457 Retrieves and sets the row object data from the database, losing any
1460 This method can also be used to refresh from storage, retrieving any
1461 changes made since the row was last read from storage. Actually
1462 implemented in L<DBIx::Class::PK>
1464 Note: If you are using L<DBIx::Class::Storage::DBI::Replicated> as your
1465 storage, please kept in mind that if you L</discard_changes> on a row that you
1466 just updated or created, you should wrap the entire bit inside a transaction.
1467 Otherwise you run the risk that you insert or update to the master database
1468 but read from a replicant database that has not yet been updated from the
1469 master. This will result in unexpected results.
1477 Matt S. Trout <mst@shadowcatsystems.co.uk>
1481 You may distribute this code under the same terms as Perl itself.