1 package DBIx::Class::Row;
6 use base qw/DBIx::Class/;
8 use DBIx::Class::Exception;
18 $ENV{DBIC_MULTICREATE_DEBUG}
23 __PACKAGE__->mk_group_accessors('simple' => qw/_source_handle/);
27 DBIx::Class::Row - Basic row methods
33 This class is responsible for defining and doing basic operations on rows
34 derived from L<DBIx::Class::ResultSource> objects.
36 Row objects are returned from L<DBIx::Class::ResultSet>s using the
37 L<create|DBIx::Class::ResultSet/create>, L<find|DBIx::Class::ResultSet/find>,
38 L<next|DBIx::Class::ResultSet/next> and L<all|DBIx::Class::ResultSet/all> methods,
39 as well as invocations of 'single' (
40 L<belongs_to|DBIx::Class::Relationship/belongs_to>,
41 L<has_one|DBIx::Class::Relationship/has_one> or
42 L<might_have|DBIx::Class::Relationship/might_have>)
43 relationship accessors of L<DBIx::Class::Row> objects.
49 my $row = My::Class->new(\%attrs);
51 my $row = $schema->resultset('MySource')->new(\%colsandvalues);
55 =item Arguments: \%attrs or \%colsandvalues
57 =item Returns: A Row object
61 While you can create a new row object by calling C<new> directly on
62 this class, you are better off calling it on a
63 L<DBIx::Class::ResultSet> object.
65 When calling it directly, you will not get a complete, usable row
66 object until you pass or set the C<source_handle> attribute, to a
67 L<DBIx::Class::ResultSource> instance that is attached to a
68 L<DBIx::Class::Schema> with a valid connection.
70 C<$attrs> is a hashref of column name, value data. It can also contain
71 some other attributes such as the C<source_handle>.
73 Passing an object, or an arrayref of objects as a value will call
74 L<DBIx::Class::Relationship::Base/set_from_related> for you. When
75 passed a hashref or an arrayref of hashrefs as the value, these will
76 be turned into objects via new_related, and treated as if you had
79 For a more involved explanation, see L<DBIx::Class::ResultSet/create>.
81 Please note that if a value is not passed to new, no value will be sent
82 in the SQL INSERT call, and the column will therefore assume whatever
83 default value was specified in your database. While DBIC will retrieve the
84 value of autoincrement columns, it will never make an explicit database
85 trip to retrieve default values assigned by the RDBMS. You can explicitly
86 request that all values be fetched back from the database by calling
87 L</discard_changes>, or you can supply an explicit C<undef> to columns
88 with NULL as the default, and save yourself a SELECT.
92 The behavior described above will backfire if you use a foreign key column
93 with a database-defined default. If you call the relationship accessor on
94 an object that doesn't have a set value for the FK column, DBIC will throw
95 an exception, as it has no way of knowing the PK of the related object (if
100 ## 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().
101 ## This only works because DBIC doesnt yet care to check whether the new_related objects have been passed all their mandatory columns
102 ## When doing the later insert, we need to make sure the PKs are set.
103 ## using _relationship_data in new and funky ways..
104 ## check Relationship::CascadeActions and Relationship::Accessor for compat
107 sub __new_related_find_or_new_helper {
108 my ($self, $relname, $data) = @_;
110 my $rsrc = $self->result_source;
112 # create a mock-object so all new/set_column component overrides will run:
113 my $rel_rs = $rsrc->related_source($relname)->resultset;
114 my $new_rel_obj = $rel_rs->new_result($data);
115 my $proc_data = { $new_rel_obj->get_columns };
117 if ($self->__their_pk_needs_us($relname)) {
118 MULTICREATE_DEBUG and warn "MC $self constructing $relname via new_result";
121 elsif ($rsrc->_pk_depends_on($relname, $proc_data )) {
122 if (! keys %$proc_data) {
123 # there is nothing to search for - blind create
124 MULTICREATE_DEBUG and warn "MC $self constructing default-insert $relname";
127 MULTICREATE_DEBUG and warn "MC $self constructing $relname via find_or_new";
128 # this is not *really* find or new, as we don't want to double-new the
129 # data (thus potentially double encoding or whatever)
130 my $exists = $rel_rs->find ($proc_data);
131 return $exists if $exists;
136 my $us = $rsrc->source_name;
137 $self->throw_exception ("'$us' neither depends nor is depended on by '$relname', something is wrong...");
141 sub __their_pk_needs_us { # this should maybe be in resultsource.
142 my ($self, $relname) = @_;
143 my $source = $self->result_source;
144 my $reverse = $source->reverse_relationship_info($relname);
145 my $rel_source = $source->related_source($relname);
146 my $us = { $self->get_columns };
147 foreach my $key (keys %$reverse) {
148 # if their primary key depends on us, then we have to
149 # just create a result and we'll fill it out afterwards
150 return 1 if $rel_source->_pk_depends_on($key, $us);
156 my ($class, $attrs) = @_;
157 $class = ref $class if ref $class;
164 if (my $handle = delete $attrs->{-source_handle}) {
165 $new->_source_handle($handle);
169 if ($source = delete $attrs->{-result_source}) {
170 $new->result_source($source);
173 if (my $related = delete $attrs->{-cols_from_relations}) {
174 @{$new->{_ignore_at_insert}={}}{@$related} = ();
178 $new->throw_exception("attrs must be a hashref")
179 unless ref($attrs) eq 'HASH';
181 my ($related,$inflated);
183 foreach my $key (keys %$attrs) {
184 if (ref $attrs->{$key}) {
185 ## Can we extract this lot to use with update(_or .. ) ?
186 $new->throw_exception("Can't do multi-create without result source")
188 my $info = $source->relationship_info($key);
189 my $acc_type = $info->{attrs}{accessor} || '';
190 if ($acc_type eq 'single') {
191 my $rel_obj = delete $attrs->{$key};
192 if(!Scalar::Util::blessed($rel_obj)) {
193 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
196 if ($rel_obj->in_storage) {
197 $new->{_rel_in_storage}{$key} = 1;
198 $new->set_from_related($key, $rel_obj);
200 MULTICREATE_DEBUG and warn "MC $new uninserted $key $rel_obj\n";
203 $related->{$key} = $rel_obj;
206 elsif ($acc_type eq 'multi' && ref $attrs->{$key} eq 'ARRAY' ) {
207 my $others = delete $attrs->{$key};
208 my $total = @$others;
210 foreach my $idx (0 .. $#$others) {
211 my $rel_obj = $others->[$idx];
212 if(!Scalar::Util::blessed($rel_obj)) {
213 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
216 if ($rel_obj->in_storage) {
217 $rel_obj->throw_exception ('A multi relationship can not be pre-existing when doing multicreate. Something went wrong');
219 MULTICREATE_DEBUG and
220 warn "MC $new uninserted $key $rel_obj (${\($idx+1)} of $total)\n";
222 push(@objects, $rel_obj);
224 $related->{$key} = \@objects;
227 elsif ($acc_type eq 'filter') {
228 ## 'filter' should disappear and get merged in with 'single' above!
229 my $rel_obj = delete $attrs->{$key};
230 if(!Scalar::Util::blessed($rel_obj)) {
231 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
233 if ($rel_obj->in_storage) {
234 $new->{_rel_in_storage}{$key} = 1;
237 MULTICREATE_DEBUG and warn "MC $new uninserted $key $rel_obj";
239 $inflated->{$key} = $rel_obj;
241 } elsif ($class->has_column($key)
242 && $class->column_info($key)->{_inflate_info}) {
243 $inflated->{$key} = $attrs->{$key};
247 $new->throw_exception("No such column $key on $class")
248 unless $class->has_column($key);
249 $new->store_column($key => $attrs->{$key});
252 $new->{_relationship_data} = $related if $related;
253 $new->{_inflated_column} = $inflated if $inflated;
265 =item Arguments: none
267 =item Returns: The Row object
271 Inserts an object previously created by L</new> into the database if
272 it isn't already in there. Returns the object itself. Requires the
273 object's result source to be set, or the class to have a
274 result_source_instance method. To insert an entirely new row into
275 the database, use C<create> (see L<DBIx::Class::ResultSet/create>).
277 To fetch an uninserted row object, call
278 L<new|DBIx::Class::ResultSet/new> on a resultset.
280 This will also insert any uninserted, related objects held inside this
281 one, see L<DBIx::Class::ResultSet/create> for more details.
287 return $self if $self->in_storage;
288 my $source = $self->result_source;
289 $source ||= $self->result_source($self->result_source_instance)
290 if $self->can('result_source_instance');
291 $self->throw_exception("No result_source set on this object; can't insert")
296 # Check if we stored uninserted relobjs here in new()
297 my %related_stuff = (%{$self->{_relationship_data} || {}},
298 %{$self->{_inflated_column} || {}});
300 # insert what needs to be inserted before us
302 for my $relname (keys %related_stuff) {
303 my $rel_obj = $related_stuff{$relname};
305 if (! $self->{_rel_in_storage}{$relname}) {
306 next unless (Scalar::Util::blessed($rel_obj)
307 && $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}
402 && Scalar::Util::blessed($cands[0])
403 && $cands[0]->isa('DBIx::Class::Row')
405 my $reverse = $source->reverse_relationship_info($relname);
406 foreach my $obj (@cands) {
407 $obj->set_from_related($_, $self) for keys %$reverse;
408 my $them = { %{$obj->{_relationship_data} || {} }, $obj->get_inflated_columns };
409 if ($self->__their_pk_needs_us($relname)) {
410 if (exists $self->{_ignore_at_insert}{$relname}) {
411 MULTICREATE_DEBUG and warn "MC $self skipping post-insert on $relname";
413 MULTICREATE_DEBUG and warn "MC $self re-creating $relname $obj";
414 my $re = $self->result_source
415 ->related_source($relname)
419 MULTICREATE_DEBUG and warn "MC $self new $relname $obj";
422 MULTICREATE_DEBUG and warn "MC $self post-inserting $obj";
429 $self->in_storage(1);
430 delete $self->{_orig_ident};
431 delete $self->{_ignore_at_insert};
432 $rollback_guard->commit if $rollback_guard;
439 $row->in_storage; # Get value
440 $row->in_storage(1); # Set value
444 =item Arguments: none or 1|0
450 Indicates whether the object exists as a row in the database or
451 not. This is set to true when L<DBIx::Class::ResultSet/find>,
452 L<DBIx::Class::ResultSet/create> or L<DBIx::Class::ResultSet/insert>
455 Creating a row object using L<DBIx::Class::ResultSet/new>, or calling
456 L</delete> on one, sets it to false.
461 my ($self, $val) = @_;
462 $self->{_in_storage} = $val if @_ > 1;
463 return $self->{_in_storage} ? 1 : 0;
468 $row->update(\%columns?)
472 =item Arguments: none or a hashref
474 =item Returns: The Row object
478 Throws an exception if the row object is not yet in the database,
479 according to L</in_storage>.
481 This method issues an SQL UPDATE query to commit any changes to the
482 object to the database if required (see L</get_dirty_columns>).
483 It throws an exception if a proper WHERE clause uniquely identifying
484 the database row can not be constructed (see
485 L<significance of primary keys|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
488 Also takes an optional hashref of C<< column_name => value >> pairs
489 to update on the object first. Be aware that the hashref will be
490 passed to C<set_inflated_columns>, which might edit it in place, so
491 don't rely on it being the same after a call to C<update>. If you
492 need to preserve the hashref, it is sufficient to pass a shallow copy
493 to C<update>, e.g. ( { %{ $href } } )
495 If the values passed or any of the column values set on the object
496 contain scalar references, e.g.:
498 $row->last_modified(\'NOW()');
500 $row->update({ last_modified => \'NOW()' });
502 The update will pass the values verbatim into SQL. (See
503 L<SQL::Abstract> docs). The values in your Row object will NOT change
504 as a result of the update call, if you want the object to be updated
505 with the actual values from the database, call L</discard_changes>
508 $row->update()->discard_changes();
510 To determine before calling this method, which column values have
511 changed and will be updated, call L</get_dirty_columns>.
513 To check if any columns will be updated, call L</is_changed>.
515 To force a column to be updated, call L</make_column_dirty> before
521 my ($self, $upd) = @_;
523 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
525 $self->set_inflated_columns($upd) if $upd;
526 my %to_update = $self->get_dirty_columns;
527 return $self unless keys %to_update;
529 $self->throw_exception( "Not in database" ) unless $self->in_storage;
531 $self->throw_exception('Unable to update a row with incomplete or no identity')
532 if ! keys %$ident_cond;
534 my $rows = $self->result_source->storage->update(
535 $self->result_source, \%to_update, $ident_cond
538 $self->throw_exception( "Can't update ${self}: row not found" );
539 } elsif ($rows > 1) {
540 $self->throw_exception("Can't update ${self}: updated more than one row");
542 $self->{_dirty_columns} = {};
543 $self->{related_resultsets} = {};
544 delete $self->{_orig_ident};
554 =item Arguments: none
556 =item Returns: The Row object
560 Throws an exception if the object is not in the database according to
561 L</in_storage>. Also throws an exception if a proper WHERE clause
562 uniquely identifying the database row can not be constructed (see
563 L<significance of primary keys|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
566 The object is still perfectly usable, but L</in_storage> will
567 now return 0 and the object must be reinserted using L</insert>
568 before it can be used to L</update> the row again.
570 If you delete an object in a class with a C<has_many> relationship, an
571 attempt is made to delete all the related objects as well. To turn
572 this behaviour off, pass C<< cascade_delete => 0 >> in the C<$attr>
573 hashref of the relationship, see L<DBIx::Class::Relationship>. Any
574 database-level cascade or restrict will take precedence over a
575 DBIx-Class-based cascading delete, since DBIx-Class B<deletes the
576 main row first> and only then attempts to delete any remaining related
579 If you delete an object within a txn_do() (see L<DBIx::Class::Storage/txn_do>)
580 and the transaction subsequently fails, the row object will remain marked as
581 not being in storage. If you know for a fact that the object is still in
582 storage (i.e. by inspecting the cause of the transaction's failure), you can
583 use C<< $obj->in_storage(1) >> to restore consistency between the object and
584 the database. This would allow a subsequent C<< $obj->delete >> to work
587 See also L<DBIx::Class::ResultSet/delete>.
594 $self->throw_exception( "Not in database" ) unless $self->in_storage;
596 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
597 $self->throw_exception('Unable to delete a row with incomplete or no identity')
598 if ! keys %$ident_cond;
600 $self->result_source->storage->delete(
601 $self->result_source, $ident_cond
604 delete $self->{_orig_ident};
605 $self->in_storage(undef);
608 $self->throw_exception("Can't do class delete without a ResultSource instance")
609 unless $self->can('result_source_instance');
610 my $attrs = @_ > 1 && ref $_[$#_] eq 'HASH' ? { %{pop(@_)} } : {};
611 my $query = ref $_[0] eq 'HASH' ? $_[0] : {@_};
612 $self->result_source_instance->resultset->search(@_)->delete;
619 my $val = $row->get_column($col);
623 =item Arguments: $columnname
625 =item Returns: The value of the column
629 Throws an exception if the column name given doesn't exist according
632 Returns a raw column value from the row object, if it has already
633 been fetched from the database or set by an accessor.
635 If an L<inflated value|DBIx::Class::InflateColumn> has been set, it
636 will be deflated and returned.
638 Note that if you used the C<columns> or the C<select/as>
639 L<search attributes|DBIx::Class::ResultSet/ATTRIBUTES> on the resultset from
640 which C<$row> was derived, and B<did not include> C<$columnname> in the list,
641 this method will return C<undef> even if the database contains some value.
643 To retrieve all loaded column values as a hash, use L</get_columns>.
648 my ($self, $column) = @_;
649 $self->throw_exception( "Can't fetch data as class method" ) unless ref $self;
650 return $self->{_column_data}{$column} if exists $self->{_column_data}{$column};
651 if (exists $self->{_inflated_column}{$column}) {
652 return $self->store_column($column,
653 $self->_deflated_column($column, $self->{_inflated_column}{$column}));
655 $self->throw_exception( "No such column '${column}'" ) unless $self->has_column($column);
659 =head2 has_column_loaded
661 if ( $row->has_column_loaded($col) ) {
662 print "$col has been loaded from db";
667 =item Arguments: $columnname
673 Returns a true value if the column value has been loaded from the
674 database (or set locally).
678 sub has_column_loaded {
679 my ($self, $column) = @_;
680 $self->throw_exception( "Can't call has_column data as class method" ) unless ref $self;
681 return 1 if exists $self->{_inflated_column}{$column};
682 return exists $self->{_column_data}{$column};
687 my %data = $row->get_columns;
691 =item Arguments: none
693 =item Returns: A hash of columnname, value pairs.
697 Returns all loaded column data as a hash, containing raw values. To
698 get just one value for a particular column, use L</get_column>.
700 See L</get_inflated_columns> to get the inflated values.
706 if (exists $self->{_inflated_column}) {
707 foreach my $col (keys %{$self->{_inflated_column}}) {
708 $self->store_column($col, $self->_deflated_column($col, $self->{_inflated_column}{$col}))
709 unless exists $self->{_column_data}{$col};
712 return %{$self->{_column_data}};
715 =head2 get_dirty_columns
717 my %data = $row->get_dirty_columns;
721 =item Arguments: none
723 =item Returns: A hash of column, value pairs
727 Only returns the column, value pairs for those columns that have been
728 changed on this object since the last L</update> or L</insert> call.
730 See L</get_columns> to fetch all column/value pairs.
734 sub get_dirty_columns {
736 return map { $_ => $self->{_column_data}{$_} }
737 keys %{$self->{_dirty_columns}};
740 =head2 make_column_dirty
742 $row->make_column_dirty($col)
746 =item Arguments: $columnname
748 =item Returns: undefined
752 Throws an exception if the column does not exist.
754 Marks a column as having been changed regardless of whether it has
758 sub make_column_dirty {
759 my ($self, $column) = @_;
761 $self->throw_exception( "No such column '${column}'" )
762 unless exists $self->{_column_data}{$column} || $self->has_column($column);
764 # the entire clean/dirty code relies on exists, not on true/false
765 return 1 if exists $self->{_dirty_columns}{$column};
767 $self->{_dirty_columns}{$column} = 1;
769 # if we are just now making the column dirty, and if there is an inflated
770 # value, force it over the deflated one
771 if (exists $self->{_inflated_column}{$column}) {
772 $self->store_column($column,
773 $self->_deflated_column(
774 $column, $self->{_inflated_column}{$column}
780 =head2 get_inflated_columns
782 my %inflated_data = $obj->get_inflated_columns;
786 =item Arguments: none
788 =item Returns: A hash of column, object|value pairs
792 Returns a hash of all column keys and associated values. Values for any
793 columns set to use inflation will be inflated and returns as objects.
795 See L</get_columns> to get the uninflated values.
797 See L<DBIx::Class::InflateColumn> for how to setup inflation.
801 sub get_inflated_columns {
804 my %loaded_colinfo = (map
805 { $_ => $self->column_info($_) }
806 (grep { $self->has_column_loaded($_) } $self->columns)
810 for my $col (keys %loaded_colinfo) {
811 if (exists $loaded_colinfo{$col}{accessor}) {
812 my $acc = $loaded_colinfo{$col}{accessor};
813 $inflated{$col} = $self->$acc if defined $acc;
816 $inflated{$col} = $self->$col;
820 # return all loaded columns with the inflations overlayed on top
821 return ($self->get_columns, %inflated);
824 sub _is_column_numeric {
825 my ($self, $column) = @_;
826 my $colinfo = $self->column_info ($column);
828 # cache for speed (the object may *not* have a resultsource instance)
829 if (not defined $colinfo->{is_numeric} && $self->_source_handle) {
830 $colinfo->{is_numeric} =
831 $self->result_source->schema->storage->is_datatype_numeric ($colinfo->{data_type})
837 return $colinfo->{is_numeric};
842 $row->set_column($col => $val);
846 =item Arguments: $columnname, $value
848 =item Returns: $value
852 Sets a raw column value. If the new value is different from the old one,
853 the column is marked as dirty for when you next call L</update>.
855 If passed an object or reference as a value, this method will happily
856 attempt to store it, and a later L</insert> or L</update> will try and
857 stringify/numify as appropriate. To set an object to be deflated
858 instead, see L</set_inflated_columns>.
863 my ($self, $column, $new_value) = @_;
865 # if we can't get an ident condition on first try - mark the object as unidentifiable
866 $self->{_orig_ident} ||= (try { $self->ident_condition }) || {};
868 my $old_value = $self->get_column($column);
869 $new_value = $self->store_column($column, $new_value);
872 $self->{_dirty_columns}{$column}
874 $self->in_storage # no point tracking dirtyness on uninserted data
875 ? ! $self->_eq_column_values ($column, $old_value, $new_value)
879 # FIXME sadly the update code just checks for keys, not for their value
880 $self->{_dirty_columns}{$column} = 1 if $dirty;
882 # XXX clear out the relation cache for this column
883 delete $self->{related_resultsets}{$column};
888 sub _eq_column_values {
889 my ($self, $col, $old, $new) = @_;
891 if (defined $old xor defined $new) {
894 elsif (not defined $old) { # both undef
897 elsif ($old eq $new) {
900 elsif ($self->_is_column_numeric($col)) { # do a numeric comparison if datatype allows it
910 $row->set_columns({ $col => $val, ... });
914 =item Arguments: \%columndata
916 =item Returns: The Row object
920 Sets multiple column, raw value pairs at once.
922 Works as L</set_column>.
927 my ($self,$data) = @_;
928 foreach my $col (keys %$data) {
929 $self->set_column($col,$data->{$col});
934 =head2 set_inflated_columns
936 $row->set_inflated_columns({ $col => $val, $relname => $obj, ... });
940 =item Arguments: \%columndata
942 =item Returns: The Row object
946 Sets more than one column value at once. Any inflated values are
947 deflated and the raw values stored.
949 Any related values passed as Row objects, using the relation name as a
950 key, are reduced to the appropriate foreign key values and stored. If
951 instead of related row objects, a hashref of column, value data is
952 passed, will create the related object first then store.
954 Will even accept arrayrefs of data as a value to a
955 L<DBIx::Class::Relationship/has_many> key, and create the related
956 objects if necessary.
958 Be aware that the input hashref might be edited in place, so don't rely
959 on it being the same after a call to C<set_inflated_columns>. If you
960 need to preserve the hashref, it is sufficient to pass a shallow copy
961 to C<set_inflated_columns>, e.g. ( { %{ $href } } )
963 See also L<DBIx::Class::Relationship::Base/set_from_related>.
967 sub set_inflated_columns {
968 my ( $self, $upd ) = @_;
969 foreach my $key (keys %$upd) {
970 if (ref $upd->{$key}) {
971 my $info = $self->relationship_info($key);
972 my $acc_type = $info->{attrs}{accessor} || '';
973 if ($acc_type eq 'single') {
974 my $rel = delete $upd->{$key};
975 $self->set_from_related($key => $rel);
976 $self->{_relationship_data}{$key} = $rel;
978 elsif ($acc_type eq 'multi') {
979 $self->throw_exception(
980 "Recursive update is not supported over relationships of type '$acc_type' ($key)"
983 elsif ($self->has_column($key) && exists $self->column_info($key)->{_inflate_info}) {
984 $self->set_inflated_column($key, delete $upd->{$key});
988 $self->set_columns($upd);
993 my $copy = $orig->copy({ change => $to, ... });
997 =item Arguments: \%replacementdata
999 =item Returns: The Row object copy
1003 Inserts a new row into the database, as a copy of the original
1004 object. If a hashref of replacement data is supplied, these will take
1005 precedence over data in the original. Also any columns which have
1006 the L<column info attribute|DBIx::Class::ResultSource/add_columns>
1007 C<< is_auto_increment => 1 >> are explicitly removed before the copy,
1008 so that the database can insert its own autoincremented values into
1011 Relationships will be followed by the copy procedure B<only> if the
1012 relationship specifies a true value for its
1013 L<cascade_copy|DBIx::Class::Relationship::Base> attribute. C<cascade_copy>
1014 is set by default on C<has_many> relationships and unset on all others.
1019 my ($self, $changes) = @_;
1021 my $col_data = { %{$self->{_column_data}} };
1022 foreach my $col (keys %$col_data) {
1023 delete $col_data->{$col}
1024 if $self->result_source->column_info($col)->{is_auto_increment};
1027 my $new = { _column_data => $col_data };
1028 bless $new, ref $self;
1030 $new->result_source($self->result_source);
1031 $new->set_inflated_columns($changes);
1034 # Its possible we'll have 2 relations to the same Source. We need to make
1035 # sure we don't try to insert the same row twice else we'll violate unique
1037 my $rels_copied = {};
1039 foreach my $rel ($self->result_source->relationships) {
1040 my $rel_info = $self->result_source->relationship_info($rel);
1042 next unless $rel_info->{attrs}{cascade_copy};
1044 my $resolved = $self->result_source->_resolve_condition(
1045 $rel_info->{cond}, $rel, $new
1048 my $copied = $rels_copied->{ $rel_info->{source} } ||= {};
1049 foreach my $related ($self->search_related($rel)) {
1050 my $id_str = join("\0", $related->id);
1051 next if $copied->{$id_str};
1052 $copied->{$id_str} = 1;
1053 my $rel_copy = $related->copy($resolved);
1062 $row->store_column($col => $val);
1066 =item Arguments: $columnname, $value
1068 =item Returns: The value sent to storage
1072 Set a raw value for a column without marking it as changed. This
1073 method is used internally by L</set_column> which you should probably
1076 This is the lowest level at which data is set on a row object,
1077 extend this method to catch all data setting methods.
1082 my ($self, $column, $value) = @_;
1083 $self->throw_exception( "No such column '${column}'" )
1084 unless exists $self->{_column_data}{$column} || $self->has_column($column);
1085 $self->throw_exception( "set_column called for ${column} without value" )
1087 return $self->{_column_data}{$column} = $value;
1090 =head2 inflate_result
1092 Class->inflate_result($result_source, \%me, \%prefetch?)
1096 =item Arguments: $result_source, \%columndata, \%prefetcheddata
1098 =item Returns: A Row object
1102 All L<DBIx::Class::ResultSet> methods that retrieve data from the
1103 database and turn it into row objects call this method.
1105 Extend this method in your Result classes to hook into this process,
1106 for example to rebless the result into a different class.
1108 Reblessing can also be done more easily by setting C<result_class> in
1109 your Result class. See L<DBIx::Class::ResultSource/result_class>.
1111 Different types of results can also be created from a particular
1112 L<DBIx::Class::ResultSet>, see L<DBIx::Class::ResultSet/result_class>.
1116 sub inflate_result {
1117 my ($class, $source, $me, $prefetch) = @_;
1119 my ($source_handle) = $source;
1121 if ($source->isa('DBIx::Class::ResultSourceHandle')) {
1122 $source = $source_handle->resolve
1125 $source_handle = $source->handle
1129 _source_handle => $source_handle,
1130 _column_data => $me,
1132 bless $new, (ref $class || $class);
1134 foreach my $pre (keys %{$prefetch||{}}) {
1136 my $pre_source = $source->related_source($pre)
1137 or $class->throw_exception("Can't prefetch non-existent relationship ${pre}");
1139 my $accessor = $source->relationship_info($pre)->{attrs}{accessor}
1140 or $class->throw_exception("No accessor for prefetched $pre");
1143 if (ref $prefetch->{$pre}[0] eq 'ARRAY') {
1144 @pre_vals = @{$prefetch->{$pre}};
1146 elsif ($accessor eq 'multi') {
1147 $class->throw_exception("Implicit prefetch (via select/columns) not supported with accessor 'multi'");
1150 @pre_vals = $prefetch->{$pre};
1154 for my $me_pref (@pre_vals) {
1156 # FIXME - this should not be necessary
1157 # the collapser currently *could* return bogus elements with all
1158 # columns set to undef
1160 for (values %{$me_pref->[0]}) {
1166 next unless $has_def;
1168 push @pre_objects, $pre_source->result_class->inflate_result(
1169 $pre_source, @$me_pref
1173 if ($accessor eq 'single') {
1174 $new->{_relationship_data}{$pre} = $pre_objects[0];
1176 elsif ($accessor eq 'filter') {
1177 $new->{_inflated_column}{$pre} = $pre_objects[0];
1180 $new->related_resultset($pre)->set_cache(\@pre_objects);
1183 $new->in_storage (1);
1187 =head2 update_or_insert
1189 $row->update_or_insert
1193 =item Arguments: none
1195 =item Returns: Result of update or insert operation
1199 L</Update>s the object if it's already in the database, according to
1200 L</in_storage>, else L</insert>s it.
1202 =head2 insert_or_update
1204 $obj->insert_or_update
1206 Alias for L</update_or_insert>
1210 sub insert_or_update { shift->update_or_insert(@_) }
1212 sub update_or_insert {
1214 return ($self->in_storage ? $self->update : $self->insert);
1219 my @changed_col_names = $row->is_changed();
1220 if ($row->is_changed()) { ... }
1224 =item Arguments: none
1226 =item Returns: 0|1 or @columnnames
1230 In list context returns a list of columns with uncommited changes, or
1231 in scalar context returns a true value if there are uncommitted
1237 return keys %{shift->{_dirty_columns} || {}};
1240 =head2 is_column_changed
1242 if ($row->is_column_changed('col')) { ... }
1246 =item Arguments: $columname
1252 Returns a true value if the column has uncommitted changes.
1256 sub is_column_changed {
1257 my( $self, $col ) = @_;
1258 return exists $self->{_dirty_columns}->{$col};
1261 =head2 result_source
1263 my $resultsource = $row->result_source;
1267 =item Arguments: none
1269 =item Returns: a ResultSource instance
1273 Accessor to the L<DBIx::Class::ResultSource> this object was created from.
1281 $self->_source_handle($_[0]->handle);
1283 $self->_source_handle->resolve;
1287 =head2 register_column
1289 $column_info = { .... };
1290 $class->register_column($column_name, $column_info);
1294 =item Arguments: $columnname, \%columninfo
1296 =item Returns: undefined
1300 Registers a column on the class. If the column_info has an 'accessor'
1301 key, creates an accessor named after the value if defined; if there is
1302 no such key, creates an accessor with the same name as the column
1304 The column_info attributes are described in
1305 L<DBIx::Class::ResultSource/add_columns>
1309 sub register_column {
1310 my ($class, $col, $info) = @_;
1312 if (exists $info->{accessor}) {
1313 return unless defined $info->{accessor};
1314 $acc = [ $info->{accessor}, $col ];
1316 $class->mk_group_accessors('column' => $acc);
1319 =head2 get_from_storage
1321 my $copy = $row->get_from_storage($attrs)
1325 =item Arguments: \%attrs
1327 =item Returns: A Row object
1331 Fetches a fresh copy of the Row object from the database and returns it.
1332 Throws an exception if a proper WHERE clause identifying the database row
1333 can not be constructed (i.e. if the original object does not contain its
1335 L<primary key|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
1336 ). If passed the \%attrs argument, will first apply these attributes to
1337 the resultset used to find the row.
1339 This copy can then be used to compare to an existing row object, to
1340 determine if any changes have been made in the database since it was
1343 To just update your Row object with any latest changes from the
1344 database, use L</discard_changes> instead.
1346 The \%attrs argument should be compatible with
1347 L<DBIx::Class::ResultSet/ATTRIBUTES>.
1351 sub get_from_storage {
1352 my $self = shift @_;
1353 my $attrs = shift @_;
1354 my $resultset = $self->result_source->resultset;
1356 if(defined $attrs) {
1357 $resultset = $resultset->search(undef, $attrs);
1360 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
1362 $self->throw_exception('Unable to requery a row with incomplete or no identity')
1363 if ! keys %$ident_cond;
1365 return $resultset->find($ident_cond);
1368 =head2 discard_changes ($attrs)
1370 Re-selects the row from the database, losing any changes that had
1371 been made. Throws an exception if a proper WHERE clause identifying
1372 the database row can not be constructed (i.e. if the original object
1373 does not contain its entire
1374 L<primary key|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
1377 This method can also be used to refresh from storage, retrieving any
1378 changes made since the row was last read from storage.
1380 $attrs is expected to be a hashref of attributes suitable for passing as the
1381 second argument to $resultset->search($cond, $attrs);
1385 sub discard_changes {
1386 my ($self, $attrs) = @_;
1387 return unless $self->in_storage; # Don't reload if we aren't real!
1389 # add a replication default to read from the master only
1390 $attrs = { force_pool => 'master', %{$attrs||{}} };
1392 if( my $current_storage = $self->get_from_storage($attrs)) {
1394 # Set $self to the current.
1395 %$self = %$current_storage;
1397 # Avoid a possible infinite loop with
1398 # sub DESTROY { $_[0]->discard_changes }
1399 bless $current_storage, 'Do::Not::Exist';
1404 $self->in_storage(0);
1410 =head2 throw_exception
1412 See L<DBIx::Class::Schema/throw_exception>.
1416 sub throw_exception {
1419 if (ref $self && ref $self->result_source && $self->result_source->schema) {
1420 $self->result_source->schema->throw_exception(@_)
1423 DBIx::Class::Exception->throw(@_);
1433 =item Arguments: none
1435 =item Returns: A list of primary key values
1439 Returns the primary key(s) for a row. Can't be called as a class method.
1440 Actually implemented in L<DBIx::Class::PK>
1442 =head2 discard_changes
1444 $row->discard_changes
1448 =item Arguments: none
1450 =item Returns: nothing (updates object in-place)
1454 Retrieves and sets the row object data from the database, losing any
1457 This method can also be used to refresh from storage, retrieving any
1458 changes made since the row was last read from storage. Actually
1459 implemented in L<DBIx::Class::PK>
1461 Note: If you are using L<DBIx::Class::Storage::DBI::Replicated> as your
1462 storage, please kept in mind that if you L</discard_changes> on a row that you
1463 just updated or created, you should wrap the entire bit inside a transaction.
1464 Otherwise you run the risk that you insert or update to the master database
1465 but read from a replicant database that has not yet been updated from the
1466 master. This will result in unexpected results.
1474 Matt S. Trout <mst@shadowcatsystems.co.uk>
1478 You may distribute this code under the same terms as Perl itself.