minor fixups
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Row.pm
CommitLineData
7624b19f 1package DBIx::Class::Row;
2
3use strict;
4use warnings;
5
1edd1722 6use base qw/DBIx::Class/;
1a58752c 7
8use DBIx::Class::Exception;
33dd4e80 9use Scalar::Util ();
1edd1722 10
0d5d1f12 11###
12### Internal method
13### Do not use
14###
e0cdf2cb 15BEGIN {
16 *MULTICREATE_DEBUG =
17 $ENV{DBIC_MULTICREATE_DEBUG}
18 ? sub () { 1 }
19 : sub () { 0 };
20}
21
aec3eff1 22__PACKAGE__->mk_group_accessors('simple' => qw/_source_handle/);
8c49f629 23
75d07914 24=head1 NAME
7624b19f 25
26DBIx::Class::Row - Basic row methods
27
28=head1 SYNOPSIS
29
30=head1 DESCRIPTION
31
32This class is responsible for defining and doing basic operations on rows
1ea77c14 33derived from L<DBIx::Class::ResultSource> objects.
7624b19f 34
a2531bf2 35Row objects are returned from L<DBIx::Class::ResultSet>s using the
ea36f4e4 36L<create|DBIx::Class::ResultSet/create>, L<find|DBIx::Class::ResultSet/find>,
37L<next|DBIx::Class::ResultSet/next> and L<all|DBIx::Class::ResultSet/all> methods,
38as well as invocations of 'single' (
39L<belongs_to|DBIx::Class::Relationship/belongs_to>,
40L<has_one|DBIx::Class::Relationship/has_one> or
41L<might_have|DBIx::Class::Relationship/might_have>)
42relationship accessors of L<DBIx::Class::Row> objects.
a2531bf2 43
7624b19f 44=head1 METHODS
45
8091aa91 46=head2 new
7624b19f 47
a2531bf2 48 my $row = My::Class->new(\%attrs);
49
50 my $row = $schema->resultset('MySource')->new(\%colsandvalues);
51
52=over
53
54=item Arguments: \%attrs or \%colsandvalues
55
56=item Returns: A Row object
7624b19f 57
a2531bf2 58=back
59
60While you can create a new row object by calling C<new> directly on
61this class, you are better off calling it on a
62L<DBIx::Class::ResultSet> object.
63
64When calling it directly, you will not get a complete, usable row
65object until you pass or set the C<source_handle> attribute, to a
66L<DBIx::Class::ResultSource> instance that is attached to a
67L<DBIx::Class::Schema> with a valid connection.
68
69C<$attrs> is a hashref of column name, value data. It can also contain
70some other attributes such as the C<source_handle>.
7624b19f 71
33dd4e80 72Passing an object, or an arrayref of objects as a value will call
73L<DBIx::Class::Relationship::Base/set_from_related> for you. When
74passed a hashref or an arrayref of hashrefs as the value, these will
75be turned into objects via new_related, and treated as if you had
76passed objects.
77
264f1571 78For a more involved explanation, see L<DBIx::Class::ResultSet/create>.
79
dc5f0ad3 80Please note that if a value is not passed to new, no value will be sent
81in the SQL INSERT call, and the column will therefore assume whatever
82default value was specified in your database. While DBIC will retrieve the
83value of autoincrement columns, it will never make an explicit database
84trip to retrieve default values assigned by the RDBMS. You can explicitly
85request that all values be fetched back from the database by calling
86L</discard_changes>, or you can supply an explicit C<undef> to columns
87with NULL as the default, and save yourself a SELECT.
88
89 CAVEAT:
90
91 The behavior described above will backfire if you use a foreign key column
92 with a database-defined default. If you call the relationship accessor on
93 an object that doesn't have a set value for the FK column, DBIC will throw
94 an exception, as it has no way of knowing the PK of the related object (if
95 there is one).
96
7624b19f 97=cut
98
33dd4e80 99## It needs to store the new objects somewhere, and call insert on that list later when insert is called on this object. We may need an accessor for these so the user can retrieve them, if just doing ->new().
100## This only works because DBIC doesnt yet care to check whether the new_related objects have been passed all their mandatory columns
101## When doing the later insert, we need to make sure the PKs are set.
102## using _relationship_data in new and funky ways..
103## check Relationship::CascadeActions and Relationship::Accessor for compat
104## tests!
105
370f2ba2 106sub __new_related_find_or_new_helper {
107 my ($self, $relname, $data) = @_;
108 if ($self->__their_pk_needs_us($relname, $data)) {
de404241 109 MULTICREATE_DEBUG and warn "MC $self constructing $relname via new_result";
370f2ba2 110 return $self->result_source
111 ->related_source($relname)
112 ->resultset
113 ->new_result($data);
114 }
6d0ee587 115 if ($self->result_source->_pk_depends_on($relname, $data)) {
de404241 116 MULTICREATE_DEBUG and warn "MC $self constructing $relname via find_or_new";
370f2ba2 117 return $self->result_source
118 ->related_source($relname)
119 ->resultset
de404241 120 ->find_or_new($data);
370f2ba2 121 }
de404241 122 MULTICREATE_DEBUG and warn "MC $self constructing $relname via find_or_new_related";
370f2ba2 123 return $self->find_or_new_related($relname, $data);
124}
125
126sub __their_pk_needs_us { # this should maybe be in resultsource.
127 my ($self, $relname, $data) = @_;
128 my $source = $self->result_source;
129 my $reverse = $source->reverse_relationship_info($relname);
130 my $rel_source = $source->related_source($relname);
131 my $us = { $self->get_columns };
132 foreach my $key (keys %$reverse) {
133 # if their primary key depends on us, then we have to
134 # just create a result and we'll fill it out afterwards
6d0ee587 135 return 1 if $rel_source->_pk_depends_on($key, $us);
370f2ba2 136 }
137 return 0;
138}
139
7624b19f 140sub new {
448f820f 141 my ($class, $attrs) = @_;
7624b19f 142 $class = ref $class if ref $class;
04786a4c 143
e60dc79f 144 my $new = {
145 _column_data => {},
146 };
04786a4c 147 bless $new, $class;
148
448f820f 149 if (my $handle = delete $attrs->{-source_handle}) {
150 $new->_source_handle($handle);
151 }
370f2ba2 152
153 my $source;
154 if ($source = delete $attrs->{-result_source}) {
e9fe476b 155 $new->result_source($source);
156 }
a6a280b9 157
fa7a51af 158 if (my $related = delete $attrs->{-cols_from_relations}) {
09e1f723 159 @{$new->{_ignore_at_insert}={}}{@$related} = ();
160 }
161
7624b19f 162 if ($attrs) {
27f01d1f 163 $new->throw_exception("attrs must be a hashref")
164 unless ref($attrs) eq 'HASH';
b6d347e0 165
61a622ee 166 my ($related,$inflated);
8222f722 167
61a622ee 168 foreach my $key (keys %$attrs) {
169 if (ref $attrs->{$key}) {
af2d42c0 170 ## Can we extract this lot to use with update(_or .. ) ?
1a58752c 171 $new->throw_exception("Can't do multi-create without result source")
172 unless $source;
370f2ba2 173 my $info = $source->relationship_info($key);
61a622ee 174 if ($info && $info->{attrs}{accessor}
c4a30d56 175 && $info->{attrs}{accessor} eq 'single')
61a622ee 176 {
de7c7c53 177 my $rel_obj = delete $attrs->{$key};
33dd4e80 178 if(!Scalar::Util::blessed($rel_obj)) {
370f2ba2 179 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
33dd4e80 180 }
2bc3c81e 181
e0cdf2cb 182 if ($rel_obj->in_storage) {
d4fe33d0 183 $new->{_rel_in_storage}{$key} = 1;
e0cdf2cb 184 $new->set_from_related($key, $rel_obj);
185 } else {
09e1f723 186 MULTICREATE_DEBUG and warn "MC $new uninserted $key $rel_obj\n";
e0cdf2cb 187 }
2bc3c81e 188
de7c7c53 189 $related->{$key} = $rel_obj;
61a622ee 190 next;
33dd4e80 191 } elsif ($info && $info->{attrs}{accessor}
192 && $info->{attrs}{accessor} eq 'multi'
193 && ref $attrs->{$key} eq 'ARRAY') {
2ec8e594 194 my $others = delete $attrs->{$key};
e0cdf2cb 195 my $total = @$others;
196 my @objects;
197 foreach my $idx (0 .. $#$others) {
198 my $rel_obj = $others->[$idx];
2ec8e594 199 if(!Scalar::Util::blessed($rel_obj)) {
370f2ba2 200 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
33dd4e80 201 }
2bc3c81e 202
e0cdf2cb 203 if ($rel_obj->in_storage) {
d4fe33d0 204 $rel_obj->throw_exception ('A multi relationship can not be pre-existing when doing multicreate. Something went wrong');
e0cdf2cb 205 } else {
e0cdf2cb 206 MULTICREATE_DEBUG and
09e1f723 207 warn "MC $new uninserted $key $rel_obj (${\($idx+1)} of $total)\n";
e0cdf2cb 208 }
e0cdf2cb 209 push(@objects, $rel_obj);
2ec8e594 210 }
e0cdf2cb 211 $related->{$key} = \@objects;
2ec8e594 212 next;
213 } elsif ($info && $info->{attrs}{accessor}
214 && $info->{attrs}{accessor} eq 'filter')
61a622ee 215 {
33dd4e80 216 ## 'filter' should disappear and get merged in with 'single' above!
2ec8e594 217 my $rel_obj = delete $attrs->{$key};
33dd4e80 218 if(!Scalar::Util::blessed($rel_obj)) {
370f2ba2 219 $rel_obj = $new->__new_related_find_or_new_helper($key, $rel_obj);
33dd4e80 220 }
d4fe33d0 221 if ($rel_obj->in_storage) {
222 $new->{_rel_in_storage}{$key} = 1;
223 }
224 else {
09e1f723 225 MULTICREATE_DEBUG and warn "MC $new uninserted $key $rel_obj";
e0cdf2cb 226 }
33dd4e80 227 $inflated->{$key} = $rel_obj;
61a622ee 228 next;
2ec8e594 229 } elsif ($class->has_column($key)
230 && $class->column_info($key)->{_inflate_info}) {
61a622ee 231 $inflated->{$key} = $attrs->{$key};
232 next;
233 }
234 }
235 $new->throw_exception("No such column $key on $class")
236 unless $class->has_column($key);
b6d347e0 237 $new->store_column($key => $attrs->{$key});
7624b19f 238 }
f90375dd 239
61a622ee 240 $new->{_relationship_data} = $related if $related;
241 $new->{_inflated_column} = $inflated if $inflated;
7624b19f 242 }
04786a4c 243
7624b19f 244 return $new;
245}
246
8091aa91 247=head2 insert
7624b19f 248
a2531bf2 249 $row->insert;
250
251=over
7624b19f 252
a2531bf2 253=item Arguments: none
254
255=item Returns: The Row object
256
257=back
258
259Inserts an object previously created by L</new> into the database if
260it isn't already in there. Returns the object itself. Requires the
261object's result source to be set, or the class to have a
262result_source_instance method. To insert an entirely new row into
263the database, use C<create> (see L<DBIx::Class::ResultSet/create>).
7624b19f 264
e91e756c 265To fetch an uninserted row object, call
266L<new|DBIx::Class::ResultSet/new> on a resultset.
267
264f1571 268This will also insert any uninserted, related objects held inside this
269one, see L<DBIx::Class::ResultSet/create> for more details.
270
7624b19f 271=cut
272
273sub insert {
274 my ($self) = @_;
275 return $self if $self->in_storage;
6aba697f 276 my $source = $self->result_source;
277 $source ||= $self->result_source($self->result_source_instance)
097d3227 278 if $self->can('result_source_instance');
aeb1bf75 279 $self->throw_exception("No result_source set on this object; can't insert")
280 unless $source;
6e399b4f 281
9c6d6d93 282 my $rollback_guard;
283
33dd4e80 284 # Check if we stored uninserted relobjs here in new()
b6d347e0 285 my %related_stuff = (%{$self->{_relationship_data} || {}},
33dd4e80 286 %{$self->{_inflated_column} || {}});
9c6d6d93 287
d4fe33d0 288 # insert what needs to be inserted before us
289 my %pre_insert;
290 for my $relname (keys %related_stuff) {
291 my $rel_obj = $related_stuff{$relname};
9c6d6d93 292
d4fe33d0 293 if (! $self->{_rel_in_storage}{$relname}) {
294 next unless (Scalar::Util::blessed($rel_obj)
295 && $rel_obj->isa('DBIx::Class::Row'));
a8c98174 296
d4fe33d0 297 next unless $source->_pk_depends_on(
298 $relname, { $rel_obj->get_columns }
299 );
a8c98174 300
d4fe33d0 301 # The guard will save us if we blow out of this scope via die
302 $rollback_guard ||= $source->storage->txn_scope_guard;
9c6d6d93 303
de404241 304 MULTICREATE_DEBUG and warn "MC $self pre-reconstructing $relname $rel_obj\n";
e0cdf2cb 305
de404241 306 my $them = { %{$rel_obj->{_relationship_data} || {} }, $rel_obj->get_inflated_columns };
8cfe052c 307 my $re = $self->result_source
308 ->related_source($relname)
309 ->resultset
310 ->find_or_create($them);
d4fe33d0 311
de404241 312 %{$rel_obj} = %{$re};
d4fe33d0 313 $self->{_rel_in_storage}{$relname} = 1;
33dd4e80 314 }
d4fe33d0 315
316 $self->set_from_related($relname, $rel_obj);
317 delete $related_stuff{$relname};
318 }
319
320 # start a transaction here if not started yet and there is more stuff
321 # to insert after us
322 if (keys %related_stuff) {
323 $rollback_guard ||= $source->storage->txn_scope_guard
33dd4e80 324 }
6e399b4f 325
09e1f723 326 MULTICREATE_DEBUG and do {
327 no warnings 'uninitialized';
328 warn "MC $self inserting (".join(', ', $self->get_columns).")\n";
329 };
ef5f6b0a 330 my $updated_cols = $source->storage->insert($source, { $self->get_columns });
645de900 331 foreach my $col (keys %$updated_cols) {
332 $self->store_column($col, $updated_cols->{$col});
333 }
ac8e89d7 334
335 ## PK::Auto
3fda409f 336 my @auto_pri = grep {
d4fe33d0 337 (not defined $self->get_column($_))
338 ||
339 (ref($self->get_column($_)) eq 'SCALAR')
3fda409f 340 } $self->primary_columns;
341
342 if (@auto_pri) {
e0cdf2cb 343 MULTICREATE_DEBUG and warn "MC $self fetching missing PKs ".join(', ', @auto_pri)."\n";
ac8e89d7 344 my $storage = $self->result_source->storage;
345 $self->throw_exception( "Missing primary key but Storage doesn't support last_insert_id" )
346 unless $storage->can('last_insert_id');
3fda409f 347 my @ids = $storage->last_insert_id($self->result_source,@auto_pri);
348 $self->throw_exception( "Can't get last insert id" )
349 unless (@ids == @auto_pri);
350 $self->store_column($auto_pri[$_] => $ids[$_]) for 0 .. $#ids;
ac8e89d7 351 }
33dd4e80 352
e0cdf2cb 353
370f2ba2 354 $self->{_dirty_columns} = {};
355 $self->{related_resultsets} = {};
356
d4fe33d0 357 foreach my $relname (keys %related_stuff) {
31c3800e 358 next unless $source->has_relationship ($relname);
359
360 my @cands = ref $related_stuff{$relname} eq 'ARRAY'
361 ? @{$related_stuff{$relname}}
362 : $related_stuff{$relname}
363 ;
d4fe33d0 364
31c3800e 365 if (@cands
366 && Scalar::Util::blessed($cands[0])
367 && $cands[0]->isa('DBIx::Class::Row')
368 ) {
d4fe33d0 369 my $reverse = $source->reverse_relationship_info($relname);
370 foreach my $obj (@cands) {
371 $obj->set_from_related($_, $self) for keys %$reverse;
372 my $them = { %{$obj->{_relationship_data} || {} }, $obj->get_inflated_columns };
373 if ($self->__their_pk_needs_us($relname, $them)) {
374 if (exists $self->{_ignore_at_insert}{$relname}) {
375 MULTICREATE_DEBUG and warn "MC $self skipping post-insert on $relname";
370f2ba2 376 } else {
d4fe33d0 377 MULTICREATE_DEBUG and warn "MC $self re-creating $relname $obj";
378 my $re = $self->result_source
379 ->related_source($relname)
380 ->resultset
381 ->create($them);
382 %{$obj} = %{$re};
383 MULTICREATE_DEBUG and warn "MC $self new $relname $obj";
370f2ba2 384 }
d4fe33d0 385 } else {
386 MULTICREATE_DEBUG and warn "MC $self post-inserting $obj";
387 $obj->insert();
8222f722 388 }
33dd4e80 389 }
390 }
391 }
33dd4e80 392
7624b19f 393 $self->in_storage(1);
d4fe33d0 394 delete $self->{_orig_ident};
395 delete $self->{_ignore_at_insert};
396 $rollback_guard->commit if $rollback_guard;
397
7624b19f 398 return $self;
399}
400
8091aa91 401=head2 in_storage
7624b19f 402
a2531bf2 403 $row->in_storage; # Get value
404 $row->in_storage(1); # Set value
405
406=over
407
408=item Arguments: none or 1|0
409
410=item Returns: 1|0
411
412=back
7624b19f 413
e91e756c 414Indicates whether the object exists as a row in the database or
415not. This is set to true when L<DBIx::Class::ResultSet/find>,
416L<DBIx::Class::ResultSet/create> or L<DBIx::Class::ResultSet/insert>
b6d347e0 417are used.
e91e756c 418
419Creating a row object using L<DBIx::Class::ResultSet/new>, or calling
420L</delete> on one, sets it to false.
7624b19f 421
422=cut
423
424sub in_storage {
425 my ($self, $val) = @_;
426 $self->{_in_storage} = $val if @_ > 1;
63bb9738 427 return $self->{_in_storage} ? 1 : 0;
7624b19f 428}
429
8091aa91 430=head2 update
7624b19f 431
a2531bf2 432 $row->update(\%columns?)
433
434=over
7624b19f 435
a2531bf2 436=item Arguments: none or a hashref
7624b19f 437
a2531bf2 438=item Returns: The Row object
439
440=back
441
442Throws an exception if the row object is not yet in the database,
443according to L</in_storage>.
444
445This method issues an SQL UPDATE query to commit any changes to the
446object to the database if required.
447
448Also takes an optional hashref of C<< column_name => value> >> pairs
449to update on the object first. Be aware that the hashref will be
450passed to C<set_inflated_columns>, which might edit it in place, so
451don't rely on it being the same after a call to C<update>. If you
452need to preserve the hashref, it is sufficient to pass a shallow copy
453to C<update>, e.g. ( { %{ $href } } )
d5d833d9 454
05d1bc9c 455If the values passed or any of the column values set on the object
456contain scalar references, eg:
457
a2531bf2 458 $row->last_modified(\'NOW()');
05d1bc9c 459 # OR
a2531bf2 460 $row->update({ last_modified => \'NOW()' });
05d1bc9c 461
462The update will pass the values verbatim into SQL. (See
463L<SQL::Abstract> docs). The values in your Row object will NOT change
464as a result of the update call, if you want the object to be updated
465with the actual values from the database, call L</discard_changes>
466after the update.
467
a2531bf2 468 $row->update()->discard_changes();
469
470To determine before calling this method, which column values have
471changed and will be updated, call L</get_dirty_columns>.
472
473To check if any columns will be updated, call L</is_changed>.
474
475To force a column to be updated, call L</make_column_dirty> before
476this method.
05d1bc9c 477
7624b19f 478=cut
479
480sub update {
481 my ($self, $upd) = @_;
701da8c4 482 $self->throw_exception( "Not in database" ) unless $self->in_storage;
4b12b3c2 483 my $ident_cond = $self->ident_condition;
484 $self->throw_exception("Cannot safely update a row in a PK-less table")
485 if ! keys %$ident_cond;
6e399b4f 486
bacf6f12 487 $self->set_inflated_columns($upd) if $upd;
5a9e0e60 488 my %to_update = $self->get_dirty_columns;
489 return $self unless keys %to_update;
88cb6a1d 490 my $rows = $self->result_source->storage->update(
f4afcd5d 491 $self->result_source, \%to_update,
492 $self->{_orig_ident} || $ident_cond
493 );
7624b19f 494 if ($rows == 0) {
701da8c4 495 $self->throw_exception( "Can't update ${self}: row not found" );
7624b19f 496 } elsif ($rows > 1) {
701da8c4 497 $self->throw_exception("Can't update ${self}: updated more than one row");
7624b19f 498 }
499 $self->{_dirty_columns} = {};
64acc2bc 500 $self->{related_resultsets} = {};
729b29ae 501 undef $self->{_orig_ident};
7624b19f 502 return $self;
503}
504
8091aa91 505=head2 delete
7624b19f 506
a2531bf2 507 $row->delete
508
509=over
510
511=item Arguments: none
7624b19f 512
a2531bf2 513=item Returns: The Row object
514
515=back
516
517Throws an exception if the object is not in the database according to
518L</in_storage>. Runs an SQL DELETE statement using the primary key
519values to locate the row.
520
521The object is still perfectly usable, but L</in_storage> will
ea36f4e4 522now return 0 and the object must be reinserted using L</insert>
b6d347e0 523before it can be used to L</update> the row again.
a2531bf2 524
525If you delete an object in a class with a C<has_many> relationship, an
526attempt is made to delete all the related objects as well. To turn
527this behaviour off, pass C<< cascade_delete => 0 >> in the C<$attr>
528hashref of the relationship, see L<DBIx::Class::Relationship>. Any
529database-level cascade or restrict will take precedence over a
281e677e 530DBIx-Class-based cascading delete, since DBIx-Class B<deletes the
531main row first> and only then attempts to delete any remaining related
532rows.
a2531bf2 533
b1d16ffd 534If you delete an object within a txn_do() (see L<DBIx::Class::Storage/txn_do>)
535and the transaction subsequently fails, the row object will remain marked as
536not being in storage. If you know for a fact that the object is still in
537storage (i.e. by inspecting the cause of the transaction's failure), you can
538use C<< $obj->in_storage(1) >> to restore consistency between the object and
539the database. This would allow a subsequent C<< $obj->delete >> to work
540as expected.
541
a2531bf2 542See also L<DBIx::Class::ResultSet/delete>.
7624b19f 543
544=cut
545
546sub delete {
547 my $self = shift;
548 if (ref $self) {
701da8c4 549 $self->throw_exception( "Not in database" ) unless $self->in_storage;
728e60a3 550 my $ident_cond = $self->{_orig_ident} || $self->ident_condition;
4b12b3c2 551 $self->throw_exception("Cannot safely delete a row in a PK-less table")
552 if ! keys %$ident_cond;
e0f56292 553 foreach my $column (keys %$ident_cond) {
75d07914 554 $self->throw_exception("Can't delete the object unless it has loaded the primary keys")
555 unless exists $self->{_column_data}{$column};
e0f56292 556 }
88cb6a1d 557 $self->result_source->storage->delete(
7af8b477 558 $self->result_source, $ident_cond);
7624b19f 559 $self->in_storage(undef);
7624b19f 560 } else {
701da8c4 561 $self->throw_exception("Can't do class delete without a ResultSource instance")
097d3227 562 unless $self->can('result_source_instance');
aeb1bf75 563 my $attrs = @_ > 1 && ref $_[$#_] eq 'HASH' ? { %{pop(@_)} } : {};
564 my $query = ref $_[0] eq 'HASH' ? $_[0] : {@_};
097d3227 565 $self->result_source_instance->resultset->search(@_)->delete;
7624b19f 566 }
567 return $self;
568}
569
8091aa91 570=head2 get_column
7624b19f 571
a2531bf2 572 my $val = $row->get_column($col);
573
574=over
575
576=item Arguments: $columnname
577
578=item Returns: The value of the column
579
580=back
581
582Throws an exception if the column name given doesn't exist according
583to L</has_column>.
7624b19f 584
e91e756c 585Returns a raw column value from the row object, if it has already
586been fetched from the database or set by an accessor.
587
588If an L<inflated value|DBIx::Class::InflateColumn> has been set, it
589will be deflated and returned.
7624b19f 590
ea36f4e4 591Note that if you used the C<columns> or the C<select/as>
592L<search attributes|DBIx::Class::ResultSet/ATTRIBUTES> on the resultset from
593which C<$row> was derived, and B<did not include> C<$columnname> in the list,
594this method will return C<undef> even if the database contains some value.
595
a2531bf2 596To retrieve all loaded column values as a hash, use L</get_columns>.
597
7624b19f 598=cut
599
600sub get_column {
601 my ($self, $column) = @_;
701da8c4 602 $self->throw_exception( "Can't fetch data as class method" ) unless ref $self;
aeb1bf75 603 return $self->{_column_data}{$column} if exists $self->{_column_data}{$column};
61a622ee 604 if (exists $self->{_inflated_column}{$column}) {
605 return $self->store_column($column,
b6d347e0 606 $self->_deflated_column($column, $self->{_inflated_column}{$column}));
61a622ee 607 }
701da8c4 608 $self->throw_exception( "No such column '${column}'" ) unless $self->has_column($column);
7624b19f 609 return undef;
610}
611
9b83fccd 612=head2 has_column_loaded
613
a2531bf2 614 if ( $row->has_column_loaded($col) ) {
9b83fccd 615 print "$col has been loaded from db";
616 }
617
a2531bf2 618=over
619
620=item Arguments: $columnname
621
622=item Returns: 0|1
623
624=back
625
9b83fccd 626Returns a true value if the column value has been loaded from the
627database (or set locally).
628
629=cut
630
def81720 631sub has_column_loaded {
632 my ($self, $column) = @_;
633 $self->throw_exception( "Can't call has_column data as class method" ) unless ref $self;
61a622ee 634 return 1 if exists $self->{_inflated_column}{$column};
aeb1bf75 635 return exists $self->{_column_data}{$column};
def81720 636}
637
8091aa91 638=head2 get_columns
076a6864 639
a2531bf2 640 my %data = $row->get_columns;
641
642=over
643
644=item Arguments: none
076a6864 645
a2531bf2 646=item Returns: A hash of columnname, value pairs.
647
648=back
649
650Returns all loaded column data as a hash, containing raw values. To
651get just one value for a particular column, use L</get_column>.
076a6864 652
c0a171bf 653See L</get_inflated_columns> to get the inflated values.
654
076a6864 655=cut
656
657sub get_columns {
658 my $self = shift;
61a622ee 659 if (exists $self->{_inflated_column}) {
660 foreach my $col (keys %{$self->{_inflated_column}}) {
661 $self->store_column($col, $self->_deflated_column($col, $self->{_inflated_column}{$col}))
c4a30d56 662 unless exists $self->{_column_data}{$col};
61a622ee 663 }
664 }
cb5f2eea 665 return %{$self->{_column_data}};
d7156e50 666}
667
668=head2 get_dirty_columns
669
a2531bf2 670 my %data = $row->get_dirty_columns;
671
672=over
673
674=item Arguments: none
d7156e50 675
a2531bf2 676=item Returns: A hash of column, value pairs
677
678=back
679
680Only returns the column, value pairs for those columns that have been
681changed on this object since the last L</update> or L</insert> call.
682
683See L</get_columns> to fetch all column/value pairs.
d7156e50 684
685=cut
686
687sub get_dirty_columns {
688 my $self = shift;
689 return map { $_ => $self->{_column_data}{$_} }
690 keys %{$self->{_dirty_columns}};
076a6864 691}
692
6dbea98e 693=head2 make_column_dirty
694
a2531bf2 695 $row->make_column_dirty($col)
696
697=over
698
699=item Arguments: $columnname
700
701=item Returns: undefined
702
703=back
704
705Throws an exception if the column does not exist.
706
707Marks a column as having been changed regardless of whether it has
b6d347e0 708really changed.
6dbea98e 709
710=cut
711sub make_column_dirty {
712 my ($self, $column) = @_;
713
714 $self->throw_exception( "No such column '${column}'" )
715 unless exists $self->{_column_data}{$column} || $self->has_column($column);
497d874a 716
b6d347e0 717 # the entire clean/dirty code relies on exists, not on true/false
497d874a 718 return 1 if exists $self->{_dirty_columns}{$column};
719
6dbea98e 720 $self->{_dirty_columns}{$column} = 1;
497d874a 721
722 # if we are just now making the column dirty, and if there is an inflated
723 # value, force it over the deflated one
724 if (exists $self->{_inflated_column}{$column}) {
725 $self->store_column($column,
726 $self->_deflated_column(
727 $column, $self->{_inflated_column}{$column}
728 )
729 );
730 }
6dbea98e 731}
732
ba4a6453 733=head2 get_inflated_columns
734
e91e756c 735 my %inflated_data = $obj->get_inflated_columns;
ba4a6453 736
a2531bf2 737=over
738
739=item Arguments: none
740
741=item Returns: A hash of column, object|value pairs
742
743=back
744
745Returns a hash of all column keys and associated values. Values for any
746columns set to use inflation will be inflated and returns as objects.
747
748See L</get_columns> to get the uninflated values.
749
750See L<DBIx::Class::InflateColumn> for how to setup inflation.
ba4a6453 751
752=cut
753
754sub get_inflated_columns {
755 my $self = shift;
d61b2132 756
757 my %loaded_colinfo = (map
758 { $_ => $self->column_info($_) }
759 (grep { $self->has_column_loaded($_) } $self->columns)
760 );
761
762 my %inflated;
763 for my $col (keys %loaded_colinfo) {
764 if (exists $loaded_colinfo{$col}{accessor}) {
765 my $acc = $loaded_colinfo{$col}{accessor};
766 if (defined $acc) {
767 $inflated{$col} = $self->$acc;
768 }
769 }
770 else {
771 $inflated{$col} = $self->$col;
772 }
773 }
774
775 # return all loaded columns with the inflations overlayed on top
776 return ($self->get_columns, %inflated);
ba4a6453 777}
778
8091aa91 779=head2 set_column
7624b19f 780
a2531bf2 781 $row->set_column($col => $val);
782
783=over
784
785=item Arguments: $columnname, $value
786
787=item Returns: $value
788
789=back
7624b19f 790
e91e756c 791Sets a raw column value. If the new value is different from the old one,
a2531bf2 792the column is marked as dirty for when you next call L</update>.
7624b19f 793
ea36f4e4 794If passed an object or reference as a value, this method will happily
795attempt to store it, and a later L</insert> or L</update> will try and
a2531bf2 796stringify/numify as appropriate. To set an object to be deflated
797instead, see L</set_inflated_columns>.
e91e756c 798
7624b19f 799=cut
800
801sub set_column {
1d0057bd 802 my ($self, $column, $new_value) = @_;
803
729b29ae 804 $self->{_orig_ident} ||= $self->ident_condition;
1d0057bd 805 my $old_value = $self->get_column($column);
806
b236052f 807 $new_value = $self->store_column($column, $new_value);
8f9eff75 808
809 my $dirty;
cad745b2 810 if (!$self->in_storage) { # no point tracking dirtyness on uninserted data
811 $dirty = 1;
812 }
813 elsif (defined $old_value xor defined $new_value) {
8f9eff75 814 $dirty = 1;
815 }
816 elsif (not defined $old_value) { # both undef
817 $dirty = 0;
818 }
819 elsif ($old_value eq $new_value) {
820 $dirty = 0;
821 }
822 else { # do a numeric comparison if datatype allows it
823 my $colinfo = $self->column_info ($column);
824
1d613d0c 825 # cache for speed (the object may *not* have a resultsource instance)
84b1ec10 826 if (not defined $colinfo->{is_numeric} && $self->_source_handle) {
8f9eff75 827 $colinfo->{is_numeric} =
828 $self->result_source->schema->storage->is_datatype_numeric ($colinfo->{data_type})
829 ? 1
830 : 0
831 ;
832 }
833
834 if ($colinfo->{is_numeric}) {
0bad1823 835 $dirty = $old_value != $new_value;
8f9eff75 836 }
837 else {
838 $dirty = 1;
839 }
840 }
841
842 # sadly the update code just checks for keys, not for their value
843 $self->{_dirty_columns}{$column} = 1 if $dirty;
e60dc79f 844
845 # XXX clear out the relation cache for this column
846 delete $self->{related_resultsets}{$column};
847
1d0057bd 848 return $new_value;
7624b19f 849}
850
8091aa91 851=head2 set_columns
076a6864 852
a2531bf2 853 $row->set_columns({ $col => $val, ... });
854
b6d347e0 855=over
076a6864 856
a2531bf2 857=item Arguments: \%columndata
858
859=item Returns: The Row object
860
861=back
862
863Sets multiple column, raw value pairs at once.
864
865Works as L</set_column>.
076a6864 866
867=cut
868
869sub set_columns {
870 my ($self,$data) = @_;
a2ca474b 871 foreach my $col (keys %$data) {
872 $self->set_column($col,$data->{$col});
076a6864 873 }
c01ab172 874 return $self;
076a6864 875}
876
bacf6f12 877=head2 set_inflated_columns
878
a2531bf2 879 $row->set_inflated_columns({ $col => $val, $relname => $obj, ... });
880
881=over
882
883=item Arguments: \%columndata
884
885=item Returns: The Row object
886
887=back
888
889Sets more than one column value at once. Any inflated values are
b6d347e0 890deflated and the raw values stored.
bacf6f12 891
a2531bf2 892Any related values passed as Row objects, using the relation name as a
893key, are reduced to the appropriate foreign key values and stored. If
894instead of related row objects, a hashref of column, value data is
895passed, will create the related object first then store.
896
897Will even accept arrayrefs of data as a value to a
898L<DBIx::Class::Relationship/has_many> key, and create the related
899objects if necessary.
900
901Be aware that the input hashref might be edited in place, so dont rely
902on it being the same after a call to C<set_inflated_columns>. If you
903need to preserve the hashref, it is sufficient to pass a shallow copy
904to C<set_inflated_columns>, e.g. ( { %{ $href } } )
905
906See also L<DBIx::Class::Relationship::Base/set_from_related>.
bacf6f12 907
908=cut
909
910sub set_inflated_columns {
911 my ( $self, $upd ) = @_;
912 foreach my $key (keys %$upd) {
913 if (ref $upd->{$key}) {
914 my $info = $self->relationship_info($key);
915 if ($info && $info->{attrs}{accessor}
916 && $info->{attrs}{accessor} eq 'single')
917 {
918 my $rel = delete $upd->{$key};
919 $self->set_from_related($key => $rel);
a7be8807 920 $self->{_relationship_data}{$key} = $rel;
bacf6f12 921 } elsif ($info && $info->{attrs}{accessor}
a7be8807 922 && $info->{attrs}{accessor} eq 'multi') {
923 $self->throw_exception(
924 "Recursive update is not supported over relationships of type multi ($key)"
925 );
bacf6f12 926 }
927 elsif ($self->has_column($key)
928 && exists $self->column_info($key)->{_inflate_info})
929 {
a7be8807 930 $self->set_inflated_column($key, delete $upd->{$key});
bacf6f12 931 }
932 }
933 }
b6d347e0 934 $self->set_columns($upd);
bacf6f12 935}
936
8091aa91 937=head2 copy
076a6864 938
939 my $copy = $orig->copy({ change => $to, ... });
940
a2531bf2 941=over
942
943=item Arguments: \%replacementdata
944
945=item Returns: The Row object copy
946
947=back
948
949Inserts a new row into the database, as a copy of the original
950object. If a hashref of replacement data is supplied, these will take
ce0893e0 951precedence over data in the original. Also any columns which have
952the L<column info attribute|DBIx::Class::ResultSource/add_columns>
953C<< is_auto_increment => 1 >> are explicitly removed before the copy,
954so that the database can insert its own autoincremented values into
955the new object.
a2531bf2 956
f928c965 957Relationships will be followed by the copy procedure B<only> if the
958relationship specifes a true value for its
959L<cascade_copy|DBIx::Class::Relationship::Base> attribute. C<cascade_copy>
960is set by default on C<has_many> relationships and unset on all others.
076a6864 961
962=cut
963
c01ab172 964sub copy {
965 my ($self, $changes) = @_;
333cce60 966 $changes ||= {};
fde6e28e 967 my $col_data = { %{$self->{_column_data}} };
968 foreach my $col (keys %$col_data) {
969 delete $col_data->{$col}
970 if $self->result_source->column_info($col)->{is_auto_increment};
971 }
04786a4c 972
973 my $new = { _column_data => $col_data };
974 bless $new, ref $self;
975
83419ec6 976 $new->result_source($self->result_source);
bacf6f12 977 $new->set_inflated_columns($changes);
333cce60 978 $new->insert;
35688220 979
b6d347e0 980 # Its possible we'll have 2 relations to the same Source. We need to make
35688220 981 # sure we don't try to insert the same row twice esle we'll violate unique
982 # constraints
983 my $rels_copied = {};
984
333cce60 985 foreach my $rel ($self->result_source->relationships) {
986 my $rel_info = $self->result_source->relationship_info($rel);
35688220 987
988 next unless $rel_info->{attrs}{cascade_copy};
b6d347e0 989
6d0ee587 990 my $resolved = $self->result_source->_resolve_condition(
35688220 991 $rel_info->{cond}, $rel, $new
992 );
993
994 my $copied = $rels_copied->{ $rel_info->{source} } ||= {};
995 foreach my $related ($self->search_related($rel)) {
996 my $id_str = join("\0", $related->id);
997 next if $copied->{$id_str};
998 $copied->{$id_str} = 1;
999 my $rel_copy = $related->copy($resolved);
333cce60 1000 }
b6d347e0 1001
333cce60 1002 }
2c4c67b6 1003 return $new;
c01ab172 1004}
1005
8091aa91 1006=head2 store_column
7624b19f 1007
a2531bf2 1008 $row->store_column($col => $val);
7624b19f 1009
a2531bf2 1010=over
1011
1012=item Arguments: $columnname, $value
1013
ea36f4e4 1014=item Returns: The value sent to storage
a2531bf2 1015
1016=back
1017
1018Set a raw value for a column without marking it as changed. This
1019method is used internally by L</set_column> which you should probably
1020be using.
1021
1022This is the lowest level at which data is set on a row object,
1023extend this method to catch all data setting methods.
7624b19f 1024
1025=cut
1026
1027sub store_column {
1028 my ($self, $column, $value) = @_;
75d07914 1029 $self->throw_exception( "No such column '${column}'" )
d7156e50 1030 unless exists $self->{_column_data}{$column} || $self->has_column($column);
75d07914 1031 $self->throw_exception( "set_column called for ${column} without value" )
7624b19f 1032 if @_ < 3;
1033 return $self->{_column_data}{$column} = $value;
1034}
1035
b52e9bf8 1036=head2 inflate_result
1037
c01ab172 1038 Class->inflate_result($result_source, \%me, \%prefetch?)
b52e9bf8 1039
a2531bf2 1040=over
1041
1042=item Arguments: $result_source, \%columndata, \%prefetcheddata
1043
1044=item Returns: A Row object
1045
1046=back
1047
1048All L<DBIx::Class::ResultSet> methods that retrieve data from the
1049database and turn it into row objects call this method.
1050
1051Extend this method in your Result classes to hook into this process,
1052for example to rebless the result into a different class.
1053
1054Reblessing can also be done more easily by setting C<result_class> in
1055your Result class. See L<DBIx::Class::ResultSource/result_class>.
b52e9bf8 1056
db2b2eb6 1057Different types of results can also be created from a particular
1058L<DBIx::Class::ResultSet>, see L<DBIx::Class::ResultSet/result_class>.
1059
b52e9bf8 1060=cut
1061
1062sub inflate_result {
c01ab172 1063 my ($class, $source, $me, $prefetch) = @_;
aec3eff1 1064
1065 my ($source_handle) = $source;
1066
1067 if ($source->isa('DBIx::Class::ResultSourceHandle')) {
1068 $source = $source_handle->resolve
1069 } else {
1070 $source_handle = $source->handle
1071 }
1072
04786a4c 1073 my $new = {
aec3eff1 1074 _source_handle => $source_handle,
04786a4c 1075 _column_data => $me,
04786a4c 1076 };
1077 bless $new, (ref $class || $class);
1078
7fb16f1a 1079 my $schema;
64acc2bc 1080 foreach my $pre (keys %{$prefetch||{}}) {
1081 my $pre_val = $prefetch->{$pre};
f9cc31dd 1082 my $pre_source = $source->related_source($pre);
a86b1efe 1083 $class->throw_exception("Can't prefetch non-existent relationship ${pre}")
1084 unless $pre_source;
0f66a01b 1085 if (ref($pre_val->[0]) eq 'ARRAY') { # multi
a86b1efe 1086 my @pre_objects;
35c77aa3 1087
1088 for my $me_pref (@$pre_val) {
1089
1090 # the collapser currently *could* return bogus elements with all
1091 # columns set to undef
1092 my $has_def;
1093 for (values %{$me_pref->[0]}) {
1094 if (defined $_) {
1095 $has_def++;
1096 last;
1097 }
a86b1efe 1098 }
35c77aa3 1099 next unless $has_def;
1100
1101 push @pre_objects, $pre_source->result_class->inflate_result(
1102 $pre_source, @$me_pref
1103 );
a86b1efe 1104 }
35c77aa3 1105
a86b1efe 1106 $new->related_resultset($pre)->set_cache(\@pre_objects);
62e87ea8 1107 } elsif (defined $pre_val->[0]) {
a86b1efe 1108 my $fetched;
75d07914 1109 unless ($pre_source->primary_columns == grep { exists $pre_val->[0]{$_}
a86b1efe 1110 and !defined $pre_val->[0]{$_} } $pre_source->primary_columns)
1111 {
1112 $fetched = $pre_source->result_class->inflate_result(
75d07914 1113 $pre_source, @{$pre_val});
a86b1efe 1114 }
1115 my $accessor = $source->relationship_info($pre)->{attrs}{accessor};
1116 $class->throw_exception("No accessor for prefetched $pre")
1117 unless defined $accessor;
1118 if ($accessor eq 'single') {
1119 $new->{_relationship_data}{$pre} = $fetched;
1120 } elsif ($accessor eq 'filter') {
1121 $new->{_inflated_column}{$pre} = $fetched;
1122 } else {
2f4d5bef 1123 $class->throw_exception("Implicit prefetch (via select/columns) not supported with accessor '$accessor'");
a86b1efe 1124 }
faf79003 1125 $new->related_resultset($pre)->set_cache([ $fetched ]);
b52e9bf8 1126 }
1127 }
35c77aa3 1128
1129 $new->in_storage (1);
7624b19f 1130 return $new;
1131}
1132
9b465d00 1133=head2 update_or_insert
7624b19f 1134
a2531bf2 1135 $row->update_or_insert
1136
1137=over
7624b19f 1138
a2531bf2 1139=item Arguments: none
1140
1141=item Returns: Result of update or insert operation
1142
1143=back
1144
1145L</Update>s the object if it's already in the database, according to
1146L</in_storage>, else L</insert>s it.
7624b19f 1147
9b83fccd 1148=head2 insert_or_update
1149
1150 $obj->insert_or_update
1151
1152Alias for L</update_or_insert>
1153
7624b19f 1154=cut
1155
370f2ba2 1156sub insert_or_update { shift->update_or_insert(@_) }
1157
9b465d00 1158sub update_or_insert {
7624b19f 1159 my $self = shift;
1160 return ($self->in_storage ? $self->update : $self->insert);
1161}
1162
8091aa91 1163=head2 is_changed
7624b19f 1164
a2531bf2 1165 my @changed_col_names = $row->is_changed();
1166 if ($row->is_changed()) { ... }
1167
1168=over
7624b19f 1169
a2531bf2 1170=item Arguments: none
1171
1172=item Returns: 0|1 or @columnnames
1173
1174=back
1175
1176In list context returns a list of columns with uncommited changes, or
9b83fccd 1177in scalar context returns a true value if there are uncommitted
1178changes.
1179
7624b19f 1180=cut
1181
1182sub is_changed {
1183 return keys %{shift->{_dirty_columns} || {}};
1184}
228dbcb4 1185
1186=head2 is_column_changed
1187
a2531bf2 1188 if ($row->is_column_changed('col')) { ... }
1189
1190=over
1191
1192=item Arguments: $columname
1193
1194=item Returns: 0|1
1195
1196=back
228dbcb4 1197
9b83fccd 1198Returns a true value if the column has uncommitted changes.
1199
228dbcb4 1200=cut
1201
1202sub is_column_changed {
1203 my( $self, $col ) = @_;
1204 return exists $self->{_dirty_columns}->{$col};
1205}
7624b19f 1206
097d3227 1207=head2 result_source
1208
a2531bf2 1209 my $resultsource = $row->result_source;
1210
1211=over
1212
1213=item Arguments: none
097d3227 1214
a2531bf2 1215=item Returns: a ResultSource instance
1216
1217=back
1218
1219Accessor to the L<DBIx::Class::ResultSource> this object was created from.
87c4e602 1220
aec3eff1 1221=cut
1222
1223sub result_source {
1224 my $self = shift;
1225
1226 if (@_) {
1227 $self->_source_handle($_[0]->handle);
1228 } else {
1229 $self->_source_handle->resolve;
1230 }
1231}
1232
9b83fccd 1233=head2 register_column
27f01d1f 1234
9b83fccd 1235 $column_info = { .... };
1236 $class->register_column($column_name, $column_info);
27f01d1f 1237
a2531bf2 1238=over
1239
1240=item Arguments: $columnname, \%columninfo
1241
1242=item Returns: undefined
1243
1244=back
1245
9b83fccd 1246Registers a column on the class. If the column_info has an 'accessor'
1247key, creates an accessor named after the value if defined; if there is
1248no such key, creates an accessor with the same name as the column
1f23a877 1249
9b83fccd 1250The column_info attributes are described in
1251L<DBIx::Class::ResultSource/add_columns>
1f23a877 1252
097d3227 1253=cut
1254
1f23a877 1255sub register_column {
1256 my ($class, $col, $info) = @_;
91b0fbd7 1257 my $acc = $col;
1258 if (exists $info->{accessor}) {
1259 return unless defined $info->{accessor};
1260 $acc = [ $info->{accessor}, $col ];
1261 }
1262 $class->mk_group_accessors('column' => $acc);
1f23a877 1263}
1264
a2531bf2 1265=head2 get_from_storage
1266
1267 my $copy = $row->get_from_storage($attrs)
1268
1269=over
b9b4e52f 1270
a2531bf2 1271=item Arguments: \%attrs
b9b4e52f 1272
a2531bf2 1273=item Returns: A Row object
1274
1275=back
1276
1277Fetches a fresh copy of the Row object from the database and returns it.
1278
1279If passed the \%attrs argument, will first apply these attributes to
1280the resultset used to find the row.
1281
1282This copy can then be used to compare to an existing row object, to
1283determine if any changes have been made in the database since it was
1284created.
1285
1286To just update your Row object with any latest changes from the
1287database, use L</discard_changes> instead.
1288
1289The \%attrs argument should be compatible with
1290L<DBIx::Class::ResultSet/ATTRIBUTES>.
7e38d850 1291
b9b4e52f 1292=cut
1293
a737512c 1294sub get_from_storage {
b9b4e52f 1295 my $self = shift @_;
7e38d850 1296 my $attrs = shift @_;
7e38d850 1297 my $resultset = $self->result_source->resultset;
b6d347e0 1298
7e38d850 1299 if(defined $attrs) {
bbd107cf 1300 $resultset = $resultset->search(undef, $attrs);
7e38d850 1301 }
b6d347e0 1302
728e60a3 1303 return $resultset->find($self->{_orig_ident} || $self->ident_condition);
b9b4e52f 1304}
701da8c4 1305
bbd107cf 1306=head2 discard_changes ($attrs)
1307
1308Re-selects the row from the database, losing any changes that had
1309been made.
1310
1311This method can also be used to refresh from storage, retrieving any
1312changes made since the row was last read from storage.
1313
1314$attrs is expected to be a hashref of attributes suitable for passing as the
1315second argument to $resultset->search($cond, $attrs);
1316
1317=cut
1318
1319sub discard_changes {
1320 my ($self, $attrs) = @_;
1321 delete $self->{_dirty_columns};
1322 return unless $self->in_storage; # Don't reload if we aren't real!
1323
1324 # add a replication default to read from the master only
1325 $attrs = { force_pool => 'master', %{$attrs||{}} };
1326
1327 if( my $current_storage = $self->get_from_storage($attrs)) {
1328
1329 # Set $self to the current.
1330 %$self = %$current_storage;
1331
1332 # Avoid a possible infinite loop with
1333 # sub DESTROY { $_[0]->discard_changes }
1334 bless $current_storage, 'Do::Not::Exist';
1335
1336 return $self;
1337 }
1338 else {
1339 $self->in_storage(0);
1340 return $self;
1341 }
1342}
1343
1344
5160b401 1345=head2 throw_exception
701da8c4 1346
a2531bf2 1347See L<DBIx::Class::Schema/throw_exception>.
701da8c4 1348
1349=cut
1350
1351sub throw_exception {
1352 my $self=shift;
1a58752c 1353
66cab05c 1354 if (ref $self && ref $self->result_source && $self->result_source->schema) {
1a58752c 1355 $self->result_source->schema->throw_exception(@_)
1356 }
1357 else {
1358 DBIx::Class::Exception->throw(@_);
701da8c4 1359 }
1360}
1361
33cf6616 1362=head2 id
1363
a2531bf2 1364 my @pk = $row->id;
1365
1366=over
1367
1368=item Arguments: none
1369
1370=item Returns: A list of primary key values
1371
1372=back
1373
33cf6616 1374Returns the primary key(s) for a row. Can't be called as a class method.
f7043881 1375Actually implemented in L<DBIx::Class::PK>
33cf6616 1376
1377=head2 discard_changes
1378
a2531bf2 1379 $row->discard_changes
1380
1381=over
1382
1383=item Arguments: none
1384
1385=item Returns: nothing (updates object in-place)
1386
1387=back
1388
1389Retrieves and sets the row object data from the database, losing any
1390local changes made.
33cf6616 1391
1392This method can also be used to refresh from storage, retrieving any
1393changes made since the row was last read from storage. Actually
f7043881 1394implemented in L<DBIx::Class::PK>
33cf6616 1395
071bbccb 1396Note: If you are using L<DBIx::Class::Storage::DBI::Replicated> as your
1397storage, please kept in mind that if you L</discard_changes> on a row that you
1398just updated or created, you should wrap the entire bit inside a transaction.
1399Otherwise you run the risk that you insert or update to the master database
1400but read from a replicant database that has not yet been updated from the
1401master. This will result in unexpected results.
1402
33cf6616 1403=cut
1404
7624b19f 14051;
1406
7624b19f 1407=head1 AUTHORS
1408
daec44b8 1409Matt S. Trout <mst@shadowcatsystems.co.uk>
7624b19f 1410
1411=head1 LICENSE
1412
1413You may distribute this code under the same terms as Perl itself.
1414
1415=cut