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 (
139 "Unable to determine relationship '$relname' direction from '$us', "
140 . "possibly due to a missing reverse-relationship on '$relname' to '$us'."
145 sub __their_pk_needs_us { # this should maybe be in resultsource.
146 my ($self, $relname) = @_;
147 my $source = $self->result_source;
148 my $reverse = $source->reverse_relationship_info($relname);
149 my $rel_source = $source->related_source($relname);
150 my $us = { $self->get_columns };
151 foreach my $key (keys %$reverse) {
152 # if their primary key depends on us, then we have to
153 # just create a result and we'll fill it out afterwards
154 return 1 if $rel_source->_pk_depends_on($key, $us);
160 my ($class, $attrs) = @_;
161 $class = ref $class if ref $class;
168 if (my $handle = delete $attrs->{-source_handle}) {
169 $new->_source_handle($handle);
173 if ($source = delete $attrs->{-result_source}) {
174 $new->result_source($source);
177 if (my $related = delete $attrs->{-cols_from_relations}) {
178 @{$new->{_ignore_at_insert}={}}{@$related} = ();
182 $new->throw_exception("attrs must be a hashref")
183 unless ref($attrs) eq 'HASH';
185 my ($related,$inflated);
187 foreach my $key (keys %$attrs) {
188 if (ref $attrs->{$key}) {
189 ## Can we extract this lot to use with update(_or .. ) ?
190 $new->throw_exception("Can't do multi-create without result source")
192 my $info = $source->relationship_info($key);
193 my $acc_type = $info->{attrs}{accessor} || '';
194 if ($acc_type eq 'single') {
195 my $rel_obj = delete $attrs->{$key};
196 if(!blessed $rel_obj) {
197 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
200 if ($rel_obj->in_storage) {
201 $new->{_rel_in_storage}{$key} = 1;
202 $new->set_from_related($key, $rel_obj);
204 MULTICREATE_DEBUG and warn "MC $new uninserted $key $rel_obj\n";
207 $related->{$key} = $rel_obj;
210 elsif ($acc_type eq 'multi' && ref $attrs->{$key} eq 'ARRAY' ) {
211 my $others = delete $attrs->{$key};
212 my $total = @$others;
214 foreach my $idx (0 .. $#$others) {
215 my $rel_obj = $others->[$idx];
216 if(!blessed $rel_obj) {
217 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
220 if ($rel_obj->in_storage) {
221 $rel_obj->throw_exception ('A multi relationship can not be pre-existing when doing multicreate. Something went wrong');
223 MULTICREATE_DEBUG and
224 warn "MC $new uninserted $key $rel_obj (${\($idx+1)} of $total)\n";
226 push(@objects, $rel_obj);
228 $related->{$key} = \@objects;
231 elsif ($acc_type eq 'filter') {
232 ## 'filter' should disappear and get merged in with 'single' above!
233 my $rel_obj = delete $attrs->{$key};
234 if(!blessed $rel_obj) {
235 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
237 if ($rel_obj->in_storage) {
238 $new->{_rel_in_storage}{$key} = 1;
241 MULTICREATE_DEBUG and warn "MC $new uninserted $key $rel_obj";
243 $inflated->{$key} = $rel_obj;
245 } elsif ($class->has_column($key)
246 && $class->column_info($key)->{_inflate_info}) {
247 $inflated->{$key} = $attrs->{$key};
251 $new->throw_exception("No such column $key on $class")
252 unless $class->has_column($key);
253 $new->store_column($key => $attrs->{$key});
256 $new->{_relationship_data} = $related if $related;
257 $new->{_inflated_column} = $inflated if $inflated;
269 =item Arguments: none
271 =item Returns: The Row object
275 Inserts an object previously created by L</new> into the database if
276 it isn't already in there. Returns the object itself. Requires the
277 object's result source to be set, or the class to have a
278 result_source_instance method. To insert an entirely new row into
279 the database, use C<create> (see L<DBIx::Class::ResultSet/create>).
281 To fetch an uninserted row object, call
282 L<new|DBIx::Class::ResultSet/new> on a resultset.
284 This will also insert any uninserted, related objects held inside this
285 one, see L<DBIx::Class::ResultSet/create> for more details.
291 return $self if $self->in_storage;
292 my $source = $self->result_source;
293 $source ||= $self->result_source($self->result_source_instance)
294 if $self->can('result_source_instance');
295 $self->throw_exception("No result_source set on this object; can't insert")
300 # Check if we stored uninserted relobjs here in new()
301 my %related_stuff = (%{$self->{_relationship_data} || {}},
302 %{$self->{_inflated_column} || {}});
304 # insert what needs to be inserted before us
306 for my $relname (keys %related_stuff) {
307 my $rel_obj = $related_stuff{$relname};
309 if (! $self->{_rel_in_storage}{$relname}) {
310 next unless (blessed $rel_obj && $rel_obj->isa('DBIx::Class::Row'));
312 next unless $source->_pk_depends_on(
313 $relname, { $rel_obj->get_columns }
316 # The guard will save us if we blow out of this scope via die
317 $rollback_guard ||= $source->storage->txn_scope_guard;
319 MULTICREATE_DEBUG and warn "MC $self pre-reconstructing $relname $rel_obj\n";
321 my $them = { %{$rel_obj->{_relationship_data} || {} }, $rel_obj->get_columns };
324 # if there are no keys - nothing to search for
325 if (keys %$them and $existing = $self->result_source
326 ->related_source($relname)
330 %{$rel_obj} = %{$existing};
336 $self->{_rel_in_storage}{$relname} = 1;
339 $self->set_from_related($relname, $rel_obj);
340 delete $related_stuff{$relname};
343 # start a transaction here if not started yet and there is more stuff
345 if (keys %related_stuff) {
346 $rollback_guard ||= $source->storage->txn_scope_guard
352 for ($self->primary_columns) {
354 not defined $self->get_column($_)
356 (ref($self->get_column($_)) eq 'SCALAR')
358 my $col_info = $source->column_info($_);
359 $auto_pri{$_} = $auto_idx++ unless $col_info->{auto_nextval}; # auto_nextval's are pre-fetched in the storage
363 MULTICREATE_DEBUG and do {
364 no warnings 'uninitialized';
365 warn "MC $self inserting (".join(', ', $self->get_columns).")\n";
367 my $updated_cols = $source->storage->insert(
369 { $self->get_columns },
370 (keys %auto_pri) && $source->storage->_use_insert_returning
371 ? { returning => [ sort { $auto_pri{$a} <=> $auto_pri{$b} } keys %auto_pri ] }
376 foreach my $col (keys %$updated_cols) {
377 $self->store_column($col, $updated_cols->{$col});
378 delete $auto_pri{$col};
381 if (keys %auto_pri) {
382 my @missing = sort { $auto_pri{$a} <=> $auto_pri{$b} } keys %auto_pri;
383 MULTICREATE_DEBUG and warn "MC $self fetching missing PKs ".join(', ', @missing )."\n";
384 my $storage = $self->result_source->storage;
385 $self->throw_exception( "Missing primary key but Storage doesn't support last_insert_id" )
386 unless $storage->can('last_insert_id');
387 my @ids = $storage->last_insert_id($self->result_source, @missing);
388 $self->throw_exception( "Can't get last insert id" )
389 unless (@ids == @missing);
390 $self->store_column($missing[$_] => $ids[$_]) for 0 .. $#missing;
393 $self->{_dirty_columns} = {};
394 $self->{related_resultsets} = {};
396 foreach my $relname (keys %related_stuff) {
397 next unless $source->has_relationship ($relname);
399 my @cands = ref $related_stuff{$relname} eq 'ARRAY'
400 ? @{$related_stuff{$relname}}
401 : $related_stuff{$relname}
404 if (@cands && blessed $cands[0] && $cands[0]->isa('DBIx::Class::Row')
406 my $reverse = $source->reverse_relationship_info($relname);
407 foreach my $obj (@cands) {
408 $obj->set_from_related($_, $self) for keys %$reverse;
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";
414 MULTICREATE_DEBUG and warn "MC $self inserting $relname $obj";
418 MULTICREATE_DEBUG and warn "MC $self post-inserting $obj";
425 $self->in_storage(1);
426 delete $self->{_orig_ident};
427 delete $self->{_orig_ident_failreason};
428 delete $self->{_ignore_at_insert};
429 $rollback_guard->commit if $rollback_guard;
436 $row->in_storage; # Get value
437 $row->in_storage(1); # Set value
441 =item Arguments: none or 1|0
447 Indicates whether the object exists as a row in the database or
448 not. This is set to true when L<DBIx::Class::ResultSet/find>,
449 L<DBIx::Class::ResultSet/create> or L<DBIx::Class::ResultSet/insert>
452 Creating a row object using L<DBIx::Class::ResultSet/new>, or calling
453 L</delete> on one, sets it to false.
458 my ($self, $val) = @_;
459 $self->{_in_storage} = $val if @_ > 1;
460 return $self->{_in_storage} ? 1 : 0;
465 $row->update(\%columns?)
469 =item Arguments: none or a hashref
471 =item Returns: The Row object
475 Throws an exception if the row object is not yet in the database,
476 according to L</in_storage>.
478 This method issues an SQL UPDATE query to commit any changes to the
479 object to the database if required (see L</get_dirty_columns>).
480 It throws an exception if a proper WHERE clause uniquely identifying
481 the database row can not be constructed (see
482 L<significance of primary keys|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
485 Also takes an optional hashref of C<< column_name => value >> pairs
486 to update on the object first. Be aware that the hashref will be
487 passed to C<set_inflated_columns>, which might edit it in place, so
488 don't rely on it being the same after a call to C<update>. If you
489 need to preserve the hashref, it is sufficient to pass a shallow copy
490 to C<update>, e.g. ( { %{ $href } } )
492 If the values passed or any of the column values set on the object
493 contain scalar references, e.g.:
495 $row->last_modified(\'NOW()');
497 $row->update({ last_modified => \'NOW()' });
499 The update will pass the values verbatim into SQL. (See
500 L<SQL::Abstract> docs). The values in your Row object will NOT change
501 as a result of the update call, if you want the object to be updated
502 with the actual values from the database, call L</discard_changes>
505 $row->update()->discard_changes();
507 To determine before calling this method, which column values have
508 changed and will be updated, call L</get_dirty_columns>.
510 To check if any columns will be updated, call L</is_changed>.
512 To force a column to be updated, call L</make_column_dirty> before
518 my ($self, $upd) = @_;
520 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
522 $self->set_inflated_columns($upd) if $upd;
523 my %to_update = $self->get_dirty_columns;
524 return $self unless keys %to_update;
526 $self->throw_exception( "Not in database" ) unless $self->in_storage;
528 $self->throw_exception($self->{_orig_ident_failreason})
529 if ! keys %$ident_cond;
531 my $rows = $self->result_source->storage->update(
532 $self->result_source, \%to_update, $ident_cond
535 $self->throw_exception( "Can't update ${self}: row not found" );
536 } elsif ($rows > 1) {
537 $self->throw_exception("Can't update ${self}: updated more than one row");
539 $self->{_dirty_columns} = {};
540 $self->{related_resultsets} = {};
541 delete $self->{_orig_ident};
551 =item Arguments: none
553 =item Returns: The Row object
557 Throws an exception if the object is not in the database according to
558 L</in_storage>. Also throws an exception if a proper WHERE clause
559 uniquely identifying the database row can not be constructed (see
560 L<significance of primary keys|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
563 The object is still perfectly usable, but L</in_storage> will
564 now return 0 and the object must be reinserted using L</insert>
565 before it can be used to L</update> the row again.
567 If you delete an object in a class with a C<has_many> relationship, an
568 attempt is made to delete all the related objects as well. To turn
569 this behaviour off, pass C<< cascade_delete => 0 >> in the C<$attr>
570 hashref of the relationship, see L<DBIx::Class::Relationship>. Any
571 database-level cascade or restrict will take precedence over a
572 DBIx-Class-based cascading delete, since DBIx-Class B<deletes the
573 main row first> and only then attempts to delete any remaining related
576 If you delete an object within a txn_do() (see L<DBIx::Class::Storage/txn_do>)
577 and the transaction subsequently fails, the row object will remain marked as
578 not being in storage. If you know for a fact that the object is still in
579 storage (i.e. by inspecting the cause of the transaction's failure), you can
580 use C<< $obj->in_storage(1) >> to restore consistency between the object and
581 the database. This would allow a subsequent C<< $obj->delete >> to work
584 See also L<DBIx::Class::ResultSet/delete>.
591 $self->throw_exception( "Not in database" ) unless $self->in_storage;
593 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
594 $self->throw_exception($self->{_orig_ident_failreason})
595 if ! keys %$ident_cond;
597 $self->result_source->storage->delete(
598 $self->result_source, $ident_cond
601 delete $self->{_orig_ident}; # no longer identifiable
602 $self->in_storage(undef);
605 $self->throw_exception("Can't do class delete without a ResultSource instance")
606 unless $self->can('result_source_instance');
607 my $attrs = @_ > 1 && ref $_[$#_] eq 'HASH' ? { %{pop(@_)} } : {};
608 my $query = ref $_[0] eq 'HASH' ? $_[0] : {@_};
609 $self->result_source_instance->resultset->search(@_)->delete;
616 my $val = $row->get_column($col);
620 =item Arguments: $columnname
622 =item Returns: The value of the column
626 Throws an exception if the column name given doesn't exist according
629 Returns a raw column value from the row object, if it has already
630 been fetched from the database or set by an accessor.
632 If an L<inflated value|DBIx::Class::InflateColumn> has been set, it
633 will be deflated and returned.
635 Note that if you used the C<columns> or the C<select/as>
636 L<search attributes|DBIx::Class::ResultSet/ATTRIBUTES> on the resultset from
637 which C<$row> was derived, and B<did not include> C<$columnname> in the list,
638 this method will return C<undef> even if the database contains some value.
640 To retrieve all loaded column values as a hash, use L</get_columns>.
645 my ($self, $column) = @_;
646 $self->throw_exception( "Can't fetch data as class method" ) unless ref $self;
647 return $self->{_column_data}{$column} if exists $self->{_column_data}{$column};
648 if (exists $self->{_inflated_column}{$column}) {
649 return $self->store_column($column,
650 $self->_deflated_column($column, $self->{_inflated_column}{$column}));
652 $self->throw_exception( "No such column '${column}'" ) unless $self->has_column($column);
656 =head2 has_column_loaded
658 if ( $row->has_column_loaded($col) ) {
659 print "$col has been loaded from db";
664 =item Arguments: $columnname
670 Returns a true value if the column value has been loaded from the
671 database (or set locally).
675 sub has_column_loaded {
676 my ($self, $column) = @_;
677 $self->throw_exception( "Can't call has_column data as class method" ) unless ref $self;
678 return 1 if exists $self->{_inflated_column}{$column};
679 return exists $self->{_column_data}{$column};
684 my %data = $row->get_columns;
688 =item Arguments: none
690 =item Returns: A hash of columnname, value pairs.
694 Returns all loaded column data as a hash, containing raw values. To
695 get just one value for a particular column, use L</get_column>.
697 See L</get_inflated_columns> to get the inflated values.
703 if (exists $self->{_inflated_column}) {
704 foreach my $col (keys %{$self->{_inflated_column}}) {
705 $self->store_column($col, $self->_deflated_column($col, $self->{_inflated_column}{$col}))
706 unless exists $self->{_column_data}{$col};
709 return %{$self->{_column_data}};
712 =head2 get_dirty_columns
714 my %data = $row->get_dirty_columns;
718 =item Arguments: none
720 =item Returns: A hash of column, value pairs
724 Only returns the column, value pairs for those columns that have been
725 changed on this object since the last L</update> or L</insert> call.
727 See L</get_columns> to fetch all column/value pairs.
731 sub get_dirty_columns {
733 return map { $_ => $self->{_column_data}{$_} }
734 keys %{$self->{_dirty_columns}};
737 =head2 make_column_dirty
739 $row->make_column_dirty($col)
743 =item Arguments: $columnname
745 =item Returns: undefined
749 Throws an exception if the column does not exist.
751 Marks a column as having been changed regardless of whether it has
755 sub make_column_dirty {
756 my ($self, $column) = @_;
758 $self->throw_exception( "No such column '${column}'" )
759 unless exists $self->{_column_data}{$column} || $self->has_column($column);
761 # the entire clean/dirty code relies on exists, not on true/false
762 return 1 if exists $self->{_dirty_columns}{$column};
764 $self->{_dirty_columns}{$column} = 1;
766 # if we are just now making the column dirty, and if there is an inflated
767 # value, force it over the deflated one
768 if (exists $self->{_inflated_column}{$column}) {
769 $self->store_column($column,
770 $self->_deflated_column(
771 $column, $self->{_inflated_column}{$column}
777 =head2 get_inflated_columns
779 my %inflated_data = $obj->get_inflated_columns;
783 =item Arguments: none
785 =item Returns: A hash of column, object|value pairs
789 Returns a hash of all column keys and associated values. Values for any
790 columns set to use inflation will be inflated and returns as objects.
792 See L</get_columns> to get the uninflated values.
794 See L<DBIx::Class::InflateColumn> for how to setup inflation.
798 sub get_inflated_columns {
801 my %loaded_colinfo = (map
802 { $_ => $self->column_info($_) }
803 (grep { $self->has_column_loaded($_) } $self->columns)
807 for my $col (keys %loaded_colinfo) {
808 if (exists $loaded_colinfo{$col}{accessor}) {
809 my $acc = $loaded_colinfo{$col}{accessor};
810 $inflated{$col} = $self->$acc if defined $acc;
813 $inflated{$col} = $self->$col;
817 # return all loaded columns with the inflations overlayed on top
818 return ($self->get_columns, %inflated);
821 sub _is_column_numeric {
822 my ($self, $column) = @_;
823 my $colinfo = $self->column_info ($column);
825 # cache for speed (the object may *not* have a resultsource instance)
826 if (! defined $colinfo->{is_numeric} && $self->_source_handle) {
827 $colinfo->{is_numeric} =
828 $self->result_source->schema->storage->is_datatype_numeric ($colinfo->{data_type})
834 return $colinfo->{is_numeric};
839 $row->set_column($col => $val);
843 =item Arguments: $columnname, $value
845 =item Returns: $value
849 Sets a raw column value. If the new value is different from the old one,
850 the column is marked as dirty for when you next call L</update>.
852 If passed an object or reference as a value, this method will happily
853 attempt to store it, and a later L</insert> or L</update> will try and
854 stringify/numify as appropriate. To set an object to be deflated
855 instead, see L</set_inflated_columns>.
860 my ($self, $column, $new_value) = @_;
862 # if we can't get an ident condition on first try - mark the object as unidentifiable
863 # (by using an empty hashref) and store the error for further diag
864 unless ($self->{_orig_ident}) {
866 $self->{_orig_ident} = $self->ident_condition
869 $self->{_orig_ident_failreason} = $_;
870 $self->{_orig_ident} = {};
874 my $old_value = $self->get_column($column);
875 $new_value = $self->store_column($column, $new_value);
878 $self->{_dirty_columns}{$column}
880 $self->in_storage # no point tracking dirtyness on uninserted data
881 ? ! $self->_eq_column_values ($column, $old_value, $new_value)
885 # FIXME sadly the update code just checks for keys, not for their value
886 $self->{_dirty_columns}{$column} = 1 if $dirty;
888 # XXX clear out the relation cache for this column
889 delete $self->{related_resultsets}{$column};
894 sub _eq_column_values {
895 my ($self, $col, $old, $new) = @_;
897 if (defined $old xor defined $new) {
900 elsif (not defined $old) { # both undef
903 elsif ($old eq $new) {
906 elsif ($self->_is_column_numeric($col)) { # do a numeric comparison if datatype allows it
916 $row->set_columns({ $col => $val, ... });
920 =item Arguments: \%columndata
922 =item Returns: The Row object
926 Sets multiple column, raw value pairs at once.
928 Works as L</set_column>.
933 my ($self,$data) = @_;
934 foreach my $col (keys %$data) {
935 $self->set_column($col,$data->{$col});
940 =head2 set_inflated_columns
942 $row->set_inflated_columns({ $col => $val, $relname => $obj, ... });
946 =item Arguments: \%columndata
948 =item Returns: The Row object
952 Sets more than one column value at once. Any inflated values are
953 deflated and the raw values stored.
955 Any related values passed as Row objects, using the relation name as a
956 key, are reduced to the appropriate foreign key values and stored. If
957 instead of related row objects, a hashref of column, value data is
958 passed, will create the related object first then store.
960 Will even accept arrayrefs of data as a value to a
961 L<DBIx::Class::Relationship/has_many> key, and create the related
962 objects if necessary.
964 Be aware that the input hashref might be edited in place, so don't rely
965 on it being the same after a call to C<set_inflated_columns>. If you
966 need to preserve the hashref, it is sufficient to pass a shallow copy
967 to C<set_inflated_columns>, e.g. ( { %{ $href } } )
969 See also L<DBIx::Class::Relationship::Base/set_from_related>.
973 sub set_inflated_columns {
974 my ( $self, $upd ) = @_;
975 foreach my $key (keys %$upd) {
976 if (ref $upd->{$key}) {
977 my $info = $self->relationship_info($key);
978 my $acc_type = $info->{attrs}{accessor} || '';
979 if ($acc_type eq 'single') {
980 my $rel = delete $upd->{$key};
981 $self->set_from_related($key => $rel);
982 $self->{_relationship_data}{$key} = $rel;
984 elsif ($acc_type eq 'multi') {
985 $self->throw_exception(
986 "Recursive update is not supported over relationships of type '$acc_type' ($key)"
989 elsif ($self->has_column($key) && exists $self->column_info($key)->{_inflate_info}) {
990 $self->set_inflated_column($key, delete $upd->{$key});
994 $self->set_columns($upd);
999 my $copy = $orig->copy({ change => $to, ... });
1003 =item Arguments: \%replacementdata
1005 =item Returns: The Row object copy
1009 Inserts a new row into the database, as a copy of the original
1010 object. If a hashref of replacement data is supplied, these will take
1011 precedence over data in the original. Also any columns which have
1012 the L<column info attribute|DBIx::Class::ResultSource/add_columns>
1013 C<< is_auto_increment => 1 >> are explicitly removed before the copy,
1014 so that the database can insert its own autoincremented values into
1017 Relationships will be followed by the copy procedure B<only> if the
1018 relationship specifies a true value for its
1019 L<cascade_copy|DBIx::Class::Relationship::Base> attribute. C<cascade_copy>
1020 is set by default on C<has_many> relationships and unset on all others.
1025 my ($self, $changes) = @_;
1027 my $col_data = { %{$self->{_column_data}} };
1028 foreach my $col (keys %$col_data) {
1029 delete $col_data->{$col}
1030 if $self->result_source->column_info($col)->{is_auto_increment};
1033 my $new = { _column_data => $col_data };
1034 bless $new, ref $self;
1036 $new->result_source($self->result_source);
1037 $new->set_inflated_columns($changes);
1040 # Its possible we'll have 2 relations to the same Source. We need to make
1041 # sure we don't try to insert the same row twice else we'll violate unique
1043 my $rels_copied = {};
1045 foreach my $rel ($self->result_source->relationships) {
1046 my $rel_info = $self->result_source->relationship_info($rel);
1048 next unless $rel_info->{attrs}{cascade_copy};
1050 my $resolved = $self->result_source->_resolve_condition(
1051 $rel_info->{cond}, $rel, $new
1054 my $copied = $rels_copied->{ $rel_info->{source} } ||= {};
1055 foreach my $related ($self->search_related($rel)) {
1056 my $id_str = join("\0", $related->id);
1057 next if $copied->{$id_str};
1058 $copied->{$id_str} = 1;
1059 my $rel_copy = $related->copy($resolved);
1068 $row->store_column($col => $val);
1072 =item Arguments: $columnname, $value
1074 =item Returns: The value sent to storage
1078 Set a raw value for a column without marking it as changed. This
1079 method is used internally by L</set_column> which you should probably
1082 This is the lowest level at which data is set on a row object,
1083 extend this method to catch all data setting methods.
1088 my ($self, $column, $value) = @_;
1089 $self->throw_exception( "No such column '${column}'" )
1090 unless exists $self->{_column_data}{$column} || $self->has_column($column);
1091 $self->throw_exception( "set_column called for ${column} without value" )
1093 return $self->{_column_data}{$column} = $value;
1096 =head2 inflate_result
1098 Class->inflate_result($result_source, \%me, \%prefetch?)
1102 =item Arguments: $result_source, \%columndata, \%prefetcheddata
1104 =item Returns: A Row object
1108 All L<DBIx::Class::ResultSet> methods that retrieve data from the
1109 database and turn it into row objects call this method.
1111 Extend this method in your Result classes to hook into this process,
1112 for example to rebless the result into a different class.
1114 Reblessing can also be done more easily by setting C<result_class> in
1115 your Result class. See L<DBIx::Class::ResultSource/result_class>.
1117 Different types of results can also be created from a particular
1118 L<DBIx::Class::ResultSet>, see L<DBIx::Class::ResultSet/result_class>.
1122 sub inflate_result {
1123 my ($class, $source, $me, $prefetch) = @_;
1125 my ($source_handle) = $source;
1127 if ($source->isa('DBIx::Class::ResultSourceHandle')) {
1128 $source = $source_handle->resolve
1131 $source_handle = $source->handle
1135 _source_handle => $source_handle,
1136 _column_data => $me,
1138 bless $new, (ref $class || $class);
1140 foreach my $pre (keys %{$prefetch||{}}) {
1142 my $pre_source = $source->related_source($pre)
1143 or $class->throw_exception("Can't prefetch non-existent relationship ${pre}");
1145 my $accessor = $source->relationship_info($pre)->{attrs}{accessor}
1146 or $class->throw_exception("No accessor for prefetched $pre");
1149 if (ref $prefetch->{$pre}[0] eq 'ARRAY') {
1150 @pre_vals = @{$prefetch->{$pre}};
1152 elsif ($accessor eq 'multi') {
1153 $class->throw_exception("Implicit prefetch (via select/columns) not supported with accessor 'multi'");
1156 @pre_vals = $prefetch->{$pre};
1160 for my $me_pref (@pre_vals) {
1162 # FIXME - this should not be necessary
1163 # the collapser currently *could* return bogus elements with all
1164 # columns set to undef
1166 for (values %{$me_pref->[0]}) {
1172 next unless $has_def;
1174 push @pre_objects, $pre_source->result_class->inflate_result(
1175 $pre_source, @$me_pref
1179 if ($accessor eq 'single') {
1180 $new->{_relationship_data}{$pre} = $pre_objects[0];
1182 elsif ($accessor eq 'filter') {
1183 $new->{_inflated_column}{$pre} = $pre_objects[0];
1186 $new->related_resultset($pre)->set_cache(\@pre_objects);
1189 $new->in_storage (1);
1193 =head2 update_or_insert
1195 $row->update_or_insert
1199 =item Arguments: none
1201 =item Returns: Result of update or insert operation
1205 L</Update>s the object if it's already in the database, according to
1206 L</in_storage>, else L</insert>s it.
1208 =head2 insert_or_update
1210 $obj->insert_or_update
1212 Alias for L</update_or_insert>
1216 sub insert_or_update { shift->update_or_insert(@_) }
1218 sub update_or_insert {
1220 return ($self->in_storage ? $self->update : $self->insert);
1225 my @changed_col_names = $row->is_changed();
1226 if ($row->is_changed()) { ... }
1230 =item Arguments: none
1232 =item Returns: 0|1 or @columnnames
1236 In list context returns a list of columns with uncommited changes, or
1237 in scalar context returns a true value if there are uncommitted
1243 return keys %{shift->{_dirty_columns} || {}};
1246 =head2 is_column_changed
1248 if ($row->is_column_changed('col')) { ... }
1252 =item Arguments: $columname
1258 Returns a true value if the column has uncommitted changes.
1262 sub is_column_changed {
1263 my( $self, $col ) = @_;
1264 return exists $self->{_dirty_columns}->{$col};
1267 =head2 result_source
1269 my $resultsource = $row->result_source;
1273 =item Arguments: none
1275 =item Returns: a ResultSource instance
1279 Accessor to the L<DBIx::Class::ResultSource> this object was created from.
1287 $self->_source_handle($_[0]->handle);
1289 $self->_source_handle->resolve;
1293 =head2 register_column
1295 $column_info = { .... };
1296 $class->register_column($column_name, $column_info);
1300 =item Arguments: $columnname, \%columninfo
1302 =item Returns: undefined
1306 Registers a column on the class. If the column_info has an 'accessor'
1307 key, creates an accessor named after the value if defined; if there is
1308 no such key, creates an accessor with the same name as the column
1310 The column_info attributes are described in
1311 L<DBIx::Class::ResultSource/add_columns>
1315 sub register_column {
1316 my ($class, $col, $info) = @_;
1318 if (exists $info->{accessor}) {
1319 return unless defined $info->{accessor};
1320 $acc = [ $info->{accessor}, $col ];
1322 $class->mk_group_accessors('column' => $acc);
1325 =head2 get_from_storage
1327 my $copy = $row->get_from_storage($attrs)
1331 =item Arguments: \%attrs
1333 =item Returns: A Row object
1337 Fetches a fresh copy of the Row object from the database and returns it.
1338 Throws an exception if a proper WHERE clause identifying the database row
1339 can not be constructed (i.e. if the original object does not contain its
1341 L<primary key|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
1342 ). If passed the \%attrs argument, will first apply these attributes to
1343 the resultset used to find the row.
1345 This copy can then be used to compare to an existing row object, to
1346 determine if any changes have been made in the database since it was
1349 To just update your Row object with any latest changes from the
1350 database, use L</discard_changes> instead.
1352 The \%attrs argument should be compatible with
1353 L<DBIx::Class::ResultSet/ATTRIBUTES>.
1357 sub get_from_storage {
1358 my $self = shift @_;
1359 my $attrs = shift @_;
1360 my $resultset = $self->result_source->resultset;
1362 if(defined $attrs) {
1363 $resultset = $resultset->search(undef, $attrs);
1366 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
1368 $self->throw_exception($self->{_orig_ident_failreason})
1369 if ! keys %$ident_cond;
1371 return $resultset->find($ident_cond);
1374 =head2 discard_changes ($attrs)
1376 Re-selects the row from the database, losing any changes that had
1377 been made. Throws an exception if a proper WHERE clause identifying
1378 the database row can not be constructed (i.e. if the original object
1379 does not contain its entire
1380 L<primary key|DBIx::Class::Manual::Intro/The Significance and Importance of Primary Keys>
1383 This method can also be used to refresh from storage, retrieving any
1384 changes made since the row was last read from storage.
1386 $attrs is expected to be a hashref of attributes suitable for passing as the
1387 second argument to $resultset->search($cond, $attrs);
1391 sub discard_changes {
1392 my ($self, $attrs) = @_;
1393 return unless $self->in_storage; # Don't reload if we aren't real!
1395 # add a replication default to read from the master only
1396 $attrs = { force_pool => 'master', %{$attrs||{}} };
1398 if( my $current_storage = $self->get_from_storage($attrs)) {
1400 # Set $self to the current.
1401 %$self = %$current_storage;
1403 # Avoid a possible infinite loop with
1404 # sub DESTROY { $_[0]->discard_changes }
1405 bless $current_storage, 'Do::Not::Exist';
1410 $self->in_storage(0);
1416 =head2 throw_exception
1418 See L<DBIx::Class::Schema/throw_exception>.
1422 sub throw_exception {
1425 if (ref $self && ref $self->result_source && $self->result_source->schema) {
1426 $self->result_source->schema->throw_exception(@_)
1429 DBIx::Class::Exception->throw(@_);
1439 =item Arguments: none
1441 =item Returns: A list of primary key values
1445 Returns the primary key(s) for a row. Can't be called as a class method.
1446 Actually implemented in L<DBIx::Class::PK>
1448 =head2 discard_changes
1450 $row->discard_changes
1454 =item Arguments: none
1456 =item Returns: nothing (updates object in-place)
1460 Retrieves and sets the row object data from the database, losing any
1463 This method can also be used to refresh from storage, retrieving any
1464 changes made since the row was last read from storage. Actually
1465 implemented in L<DBIx::Class::PK>
1467 Note: If you are using L<DBIx::Class::Storage::DBI::Replicated> as your
1468 storage, please kept in mind that if you L</discard_changes> on a row that you
1469 just updated or created, you should wrap the entire bit inside a transaction.
1470 Otherwise you run the risk that you insert or update to the master database
1471 but read from a replicant database that has not yet been updated from the
1472 master. This will result in unexpected results.
1480 Matt S. Trout <mst@shadowcatsystems.co.uk>
1484 You may distribute this code under the same terms as Perl itself.