NAME
DBIO::Row - Basic row methods
VERSION
version 0.900004
SYNOPSIS
DESCRIPTION
DBIO::Row implements the basic row lifecycle for DBIO result objects: construction, column updates, inserts, deletes, refreshes, and related-object handling.
Result objects are returned from DBIO::ResultSet instances using the create, find, next and all methods, as well as invocations of 'single' ( belongs_to, has_one or might_have) relationship accessors of Result objects.
METHODS
new
my $result = My::Class->new(\%attrs);
my $result = $schema->resultset('MySource')->new(\%colsandvalues);- Arguments: \%attrs or \%colsandvalues
- Return Value: $result
While you can create a new result object by calling new directly on this class, you are better off calling it on a DBIO::ResultSet object.
When calling it directly, you will not get a complete, usable row object until you pass the -result_source attribute or call "result_source" with a DBIO::ResultSource instance that is attached to a DBIO::Schema with a valid connection.
$attrs is a hashref of column name, value data. It can also contain some other attributes such as -result_source.
Passing an object, or an arrayref of objects as a value will call "set_from_related" in DBIO::Relationship::Base for you. When passed a hashref or an arrayref of hashrefs as the value, these will be turned into objects via new_related, and treated as if you had passed objects.
For a more involved explanation, see "create" in DBIO::ResultSet.
Passing a request hash to new is mass assignment: what ends up in the columns is what is checked. A column or relationship marked is_guarded takes no value or data from the hash, and neither does a relationship value that resolves to a guarded foreign key column. A hash of related data is looked up with "find" in DBIO::ResultSet only for a belongs_to relationship when it gives every column of a unique constraint of the related source, any other related data is created: being unique is no permission to link a row, so mark the relationship or its foreign key is_guarded where a caller may not link existing rows. When the row is built by a resultset with a condition, a value of the caller's that contradicts an equality of the condition throws, see "create" in DBIO::ResultSet.
Please note that if a value is not passed to new, no value will be sent in the SQL INSERT call, and the column will therefore assume whatever default value was specified in your database. While DBIO will retrieve the value of autoincrement columns, it will never make an explicit database trip to retrieve default values assigned by the RDBMS. You can explicitly request that all values be fetched back from the database by calling "discard_changes", or you can supply an explicit undef to columns with NULL as the default, and save yourself a SELECT.
CAVEAT:
The behavior described above will backfire if you use a foreign key column
with a database-defined default. If you call the relationship accessor on
an object that doesn't have a set value for the FK column, DBIO will throw
an exception, as it has no way of knowing the PK of the related object (if
there is one).$column_accessor
# Each pair does the same thing
# (un-inflated, regular column)
my $val = $result->get_column('first_name');
my $val = $result->first_name;
$result->set_column('first_name' => $val);
$result->first_name($val);
# (inflated column via DBIO::InflateColumn::DateTime)
my $val = $result->get_inflated_column('last_modified');
my $val = $result->last_modified;
$result->set_inflated_column('last_modified' => $val);
$result->last_modified($val);A column accessor method is created for each column, which is used for getting/setting the value for that column.
The actual method name is based on the accessor name given during the Result Class column definition . Like "set_column", this will not store the data in the database until "insert" or "update" is called on the row.
insert
$result->insert;- Arguments: none
- Return Value: $result
Inserts an object previously created by "new" into the database if it isn't already in there. Returns the object itself. To insert an entirely new row into the database, use "create" in DBIO::ResultSet.
To fetch an uninserted result object, call new_result on a resultset.
This will also insert any uninserted, related objects held inside this one, see "create" in DBIO::ResultSet for more details.
with_context
$row->with_context($ctx)->update_async(\%changes);Returns a clone of this row bound to a pinned async context -- the object handed to a "txn_do_async" in DBIO::Storage::Async or pipeline coderef. Once bound, every *_async method on the clone routes onto the context's pinned connection instead of the pool. If the row carries eagerly-prefetched children, the pin cascades through them: the clone gets a fresh set of bound child resultsets (and bound cached grandchildren), so a prefetched child fetched off the clone stays pinned too, while the unbound source's rows and related resultsets are left untouched. See "with_context" in DBIO::ResultSet for the full picture; a row inherits this binding automatically when it is derived from a context-bound resultset.
What is derived from a bound row is bound as well (ADR 0045): its related resultsets and rows ("related_resultset" in DBIO::Relationship::Base, "search_related" in DBIO::Relationship::Base, the relationship accessors, the row a many-to-many add_to_$rel finds or creates), "self_rs" and "clean_rs", the row "get_from_storage" or "get_from_storage_async" returns, the copy "copy" or "copy_async" returns, and -- with those components loaded -- the sibling resultsets and rows of DBIO::Ordered and "changelog" in DBIO::ChangeLog. "discard_changes" and "discard_changes_async" leave the row bound.
The synchronous methods among these do their own reading and writing through the synchronous storage, outside the pinned transaction or pipeline; it is the object they hand back that keeps the binding for a *_async called on it.
In the immediate mode the context txn_do_async hands its coderef is the storage itself, and with_context takes it; see "with_context" in DBIO::ResultSet for what is particular to that mode.
_has_storage_value
Returns true if the given column opts in via keep_storage_value. Override on a Result class to enable snapshotting by other criteria (e.g. "all integer columns").
storage_value_columns
Arrayref of columns that will be snapshotted on this row.
store_storage_values
Refresh the snapshot from the current accessor values.
get_storage_value
$row->get_storage_value('title')Returns the snapshotted value for a column.
before_column_change
__PACKAGE__->before_column_change(col => { method => ..., txn_wrap => 0 });around_column_change
__PACKAGE__->around_column_change(col => { method => ..., txn_wrap => 0 });after_column_change
__PACKAGE__->after_column_change(col => { method => ..., txn_wrap => 0 });on_column_change_allow_override_args
Override and return true on your Result class if a before_column_change callback should be able to replace values passed to update($upd). Defaults to false to preserve historic behaviour.
proxy_resultset_method
__PACKAGE__->proxy_resultset_method($name, {
slot => $slot, # defaults to $name
resultset_method => $rs_method, # defaults to "with_$name"
});NOTE
All row objects produced from a schema-attached DBIO::ResultSet (for example via search->next) are actually instances of your application's Result Class.
DBIO::Row implements most of the row-level communication with the underlying storage, but a Result class should not inherit from it directly. Result classes normally inherit from DBIO::Core, which composes DBIO::Row together with other core behavior. Therefore, while many of the methods available to a DBIO::Core-derived Result class are described in the following documentation, it does not detail all of the methods available to Result objects. Refer to DBIO::Manual::ResultClass for more info.
insert_async
my $future = $row->insert_async;
$future->then(sub { my $row = shift; ... });Async variant of "insert". For a plain single-row insert the storage write is routed through the backend's insert_async and the returned columns are folded back into the object in the Future's then (reusing the same store-back as the synchronous "insert"), resolving with $self.
What counts as a plain single-row insert is what "insert" sends as one INSERT. A row may carry an object for a column with an inflator -- it is deflated into the statement -- and a related row for a belongs_to that was already in storage when the row was built -- it lends its key as the foreign key. Both go out as that one INSERT, with the values "insert" writes.
An insert that involves related-object multi-create does not: a related row that has to be looked up or inserted before this one (a belongs_to given as a hashref or as a row not yet in storage), or related rows that are inserted after it (a has_many given as an arrayref, a has_one / might_have row). On an unbound row that is performed synchronously and the Future is returned settled: resolved with $self, or failed with what the insert threw. On a row bound to an async context ("with_context", or inherited from a bound resultset) it throws insert_async cannot run on a bound async context instead -- an exception out of insert_async, not a failed Future, naming the relationship that makes it a cascade -- since the synchronous insert would run outside the pinned transaction or pipeline (ADR 0045).
Two edges follow "insert" rather than what one might expect. A related row in storage that is put on the row after it was built (by accessor or "set_inflated_columns") is looked up again by "insert" before it inserts, so it counts as a cascade here too; pass it when building the row. And a belongs_to given as a hashref is looked up while the row is built, by a synchronous statement, before insert_async is reached at all -- on a bound resultset that statement has run outside the transaction by the time the insert is refused.
A class on whose MRO a package defines insert itself without defining insert_async in that same package (a component such as DBIO::Ordered or DBIO::ChangeLog, the result class itself, a Moo around) has that override run: insert_async goes through the full "insert". On an unbound row that is performed synchronously and the Future is returned settled, as for a multi-create. On a row bound to an async context it throws insert_async cannot run on a bound async context, naming the class and the method, instead -- the override would run outside the pinned transaction or pipeline. An override whose work lies before the write moves it into "prepare_insert", which insert_async calls itself; one that has its own insert_async in the same package is taken as written. DBIO::Relationship::CascadeActions is not counted.
Requires an async connection; on a sync instance it croaks, and in the immediate mode it degrades to a synchronous insert wrapped in an immediately-resolved Future. See ADR 0030/0031.
update_async
my $future = $row->update_async(\%columns?)
$future->then(sub { my $row = shift; ... });Async variant of "update". A simple flat write -- no OnColumnChange callback registered on this class, and no cascade_update relationship (see "cascade_update" in DBIO::Relationship::Base, on by default for has_one/might_have) actually touched on this row instance -- is always genuinely async: it applies %columns exactly like "update" (via set_inflated_columns, which includes the ADR 0034 set_from_related guard) and dispatches the actual UPDATE statement through the backend's update_async, folding the same post-update bookkeeping back onto the object (clearing dirty columns, refreshing the storage-values snapshot) in the Future's then, and resolving with $self. This holds even for a row whose class has a has_one/might_have relationship declared -- what matters is whether that relationship's accessor has actually been touched on this row (assigned, or fetched at least once), which is the same condition DBIO::Relationship::CascadeActions's own update wrap checks before it does any related work.
A row whose class has an OnColumnChange callback, or whose source has a cascade_update relationship that update()'s CascadeActions wrap would actually cascade to (per the paragraph above), cannot be expressed as a single async statement: both wrap "update" itself (a before/around/after chain built inline in update, or CascadeActions's component-composition wrap) -- a layer update_async, being a new method name, cannot reach into without duplicating that wrapping. Such a row is updated synchronously instead (through the full "update", so the callbacks and cascades still fire correctly) and the Future resolves immediately, exactly like "insert_async"'s related-object multi-create punt and "delete_async"'s cascade-delete punt. The OnColumnChange half of this check is class-level, not per-call -- it does not attempt to predict whether a callback registered for a specific column will actually fire for a given %columns before running set_inflated_columns.
A class with an override of update that has no update_async in the same package -- a component such as DBIO::ChangeLog or DBIO::Ordered, the result class, a Moo around -- is updated through the full "update", so the override runs: on an unbound row synchronously, with the Future settled; on a row bound to an async context update_async throws update_async cannot run on a bound async context, naming the class and the method. Work that lies before the write belongs in "prepare_update", which "update" and update_async both call once. See "insert_async".
Requires an async connection; on a sync instance it croaks, and in the immediate mode it degrades to a synchronous update wrapped in an immediately-resolved Future. See ADR 0030/0031.
in_storage
$result->in_storage; # Get value
$result->in_storage(1); # Set valueIndicates whether the object exists as a row in the database or not. This is set to true when "find" in DBIO::ResultSet, "create" in DBIO::ResultSet or "insert" in DBIO::Row are invoked.
Creating a result object using "new_result" in DBIO::ResultSet, or calling "delete" on one, sets it to false.
update
$result->update(\%columns?)- Arguments: none or a hashref
- Return Value: $result
Throws an exception if the result object is not yet in the database, according to "in_storage". Returns the object itself.
This method issues an SQL UPDATE query to commit any changes to the object to the database if required (see "get_dirty_columns"). It throws an exception if a proper WHERE clause uniquely identifying the database row can not be constructed (see significance of primary keys for more details).
Also takes an optional hashref of column_name => value pairs to update on the object first. Be aware that the hashref will be passed to set_inflated_columns, which might edit it in place, so don't rely on it being the same after a call to update. If you need to preserve the hashref, it is sufficient to pass a shallow copy to update, e.g. ( { %{ $href } } )
A column value is a value: a plain scalar, undef, an object, an arrayref (an array data type, always bound), explicit literal SQL, or what an inflated column type deflates. A hash, code or glob reference, or a reference to a reference, is no value and throws, naming the column and the type.
The hashref is mass assignment: a column marked is_guarded, and a relationship value that resolves to one as foreign key, make update throw. The accessor, "set_column" and update without a hashref set a guarded column.
If the values passed or any of the column values set on the object contain scalar references, e.g.:
$result->last_modified(\'NOW()')->update();
# OR
$result->update({ last_modified => \'NOW()' });The update will pass the values verbatim into SQL. (See SQL::Abstract docs). The values in your Result object will NOT change as a result of the update call, if you want the object to be updated with the actual values from the database, call "discard_changes" after the update.
$result->update()->discard_changes();To determine before calling this method, which column values have changed and will be updated, call "get_dirty_columns".
To check if any columns will be updated, call "is_changed".
To force a column to be updated, call "make_column_dirty" before this method.
delete
$result->delete- Arguments: none
- Return Value: $result
Throws an exception if the object is not in the database according to "in_storage". Also throws an exception if a proper WHERE clause uniquely identifying the database row can not be constructed (see significance of primary keys for more details).
The object is still perfectly usable, but "in_storage" will now return 0 and the object must be reinserted using "insert" before it can be used to "update" the row again.
If you delete an object in a class with a has_many relationship, an attempt is made to delete all the related objects as well. To turn this behaviour off, pass cascade_delete => 0 in the $attr hashref of the relationship, see DBIO::Relationship. Any database-level cascade or restrict will take precedence over a DBIO-based cascading delete, since DBIO deletes the main row first and only then attempts to delete any remaining related rows.
If you delete an object within a txn_do() (see "txn_do" in DBIO::Storage) and the transaction subsequently fails, the result object will remain marked as not being in storage. If you know for a fact that the object is still in storage (i.e. by inspecting the cause of the transaction's failure), you can use $obj->in_storage(1) to restore consistency between the object and the database. This would allow a subsequent $obj->delete to work as expected.
Called on the class (MyApp::Schema::Result::CD->delete(\%cond)), it deletes the rows matching the condition through "delete" in DBIO::ResultSet. A class call without a condition throws (delete on an unrestricted resultset: pass { all = 1 }>): the class call takes no options, so the whole table is deleted through $schema->resultset('CD')->delete({ all => 1 }) (ADR 0069).
See also "delete" in DBIO::ResultSet.
delete_async
my $future = $row->delete_async;
$future->then(sub { my $row = shift; ... });Async variant of "delete". For a flat row -- no relationship on this row's source with cascade_delete set (see "cascade_delete" in DBIO::Relationship::Base, on by default for has_many/has_one/might_have) -- deletes it through the backend's delete_async, then marks the object as no longer "in_storage", resolving with $self in the Future's then -- exactly like sync "delete".
A row whose source has a cascade_delete relationship cannot be expressed as a single async statement: cascading to the related rows is itself a further, transactional operation that DBIO::Relationship::CascadeActions performs by wrapping "delete" at the component-composition layer, a layer delete_async, being a new method name, cannot reach into without duplicating that wrapping. Such a row is deleted synchronously instead (through the full "delete", so any cascade still fires correctly) and the Future resolves immediately, exactly like "insert_async"'s related-object multi-create punt.
Unlike "update_async"'s cascade_update check, this is a per-class gate, not a per-instance one: CascadeActions's delete wrap issues the related delete_all unconditionally for every cascade_delete relationship whenever it fires, with no cache to consult first (unlike cascade_update's cached-related-object check) -- a class declaring any cascade_delete relationship is genuinely never single-table for delete, so every delete_async call on that class punts, not just some.
Operator-facing guidance: if your schema drives cascade_delete entirely from the database's own ON DELETE CASCADE constraints rather than from DBIO's own cascading, set cascade_delete => 0 on those relationships (see "cascade_delete" in DBIO::Relationship::Base) -- this restores fully async delete_async for that class, since the database performs the cascade for you and DBIO no longer needs to.
An override of delete without a delete_async in the same package (a component such as DBIO::Ordered or DBIO::ChangeLog, the result class, a Moo around) is run through the full "delete" likewise: synchronously with the Future settled on an unbound row, refused by name (delete_async cannot run on a bound async context, with class and method) on a bound one. Work before the write belongs in "prepare_delete". See "insert_async".
Requires an async connection; on a sync instance it croaks, and in the immediate mode it degrades to a synchronous delete wrapped in an immediately-resolved Future. See ADR 0030/0031.
prepare_insert
sub prepare_insert {
my $self = shift;
$self->created_by($self->current_user) unless defined $self->created_by;
return $self->next::method(@_);
}The hook for what a component or result class has to do to a row before it is written by "insert": set a column, generate a key, stamp a time. It does nothing here. "insert" calls it once, and so does "insert_async" when it sends the statement itself, in both cases before the columns are read; a row already in storage is not prepared. A component overrides it and calls $self->next::method.
Prefer it over overriding "insert" where the work lies before the write: an override of insert is not on the way of "insert_async" (see there), the hook is. DBIO::Timestamp and DBIO::UUIDColumns work through it.
prepare_update
sub prepare_update {
my ($self, $upd) = @_;
$self->modified_by($self->current_user);
return $self->next::method($upd);
}The same for "update". It is called once, first, with the hashref given to "update" / "update_async" (or undef) before it is applied, and may change it in place -- take keys out of it and set them another way, as DBIO::FilterColumn does for a filtered column and DBIO::Timestamp for a set_on_update column. Whatever is left in it is applied afterwards. It does nothing here.
prepare_delete
sub prepare_delete {
my $self = shift;
# ... a row that is going away
return $self->next::method(@_);
}The same for "delete", called once on a row in storage before the statement is sent. It does nothing here.
Work that writes other rows or reads the siblings of this one (what DBIO::Ordered and DBIO::ChangeLog do) is not before-the-write work in this sense: it needs the transaction and the synchronous reads of the override, stays an override of insert / update / delete and is bound by the rule given under "insert_async".
get_column
my $val = $result->get_column($col);Throws an exception if the column name given doesn't exist according to has_column.
Returns a raw column value from the result object, if it has already been fetched from the database or set by an accessor.
If an inflated value has been set, it will be deflated and returned.
Note that if you used the columns or the select/as search attributes on the resultset from which $result was derived, and did not include $columnname in the list, this method will return undef even if the database contains some value.
To retrieve all loaded column values as a hash, use "get_columns".
has_column_loaded
if ( $result->has_column_loaded($col) ) {
print "$col has been loaded from db";
}Returns a true value if the column value has been loaded from the database (or set locally).
get_columns
my %data = $result->get_columns;Returns all loaded column data as a hash, containing raw values. To get just one value for a particular column, use "get_column".
See "get_inflated_columns" to get the inflated values.
get_dirty_columns
my %data = $result->get_dirty_columns;Only returns the column, value pairs for those columns that have been changed on this object since the last "update" or "insert" call.
See "get_columns" to fetch all column/value pairs.
make_column_dirty
$result->make_column_dirty($col)Throws an exception if the column does not exist.
Marks a column as having been changed regardless of whether it has really changed.
get_inflated_columns
my %inflated_data = $obj->get_inflated_columns;Returns a hash of all column keys and associated values. Values for any columns set to use inflation will be inflated and returns as objects.
See "get_columns" to get the uninflated values.
See DBIO::InflateColumn for how to setup inflation.
set_column
$result->set_column($col => $val);Sets a raw column value. If the new value is different from the old one, the column is marked as dirty for when you next call "update".
If passed an object or reference as a value, this method will happily attempt to store it, and a later "insert" or "update" will try and stringify/numify as appropriate. To set an object to be deflated instead, see "set_inflated_columns", or better yet, use "$column_accessor".
set_columns
$result->set_columns({ $col => $val, ... });- Arguments: \%columndata
- Return Value: $result
Sets multiple column, raw value pairs at once.
Works as "set_column".
set_inflated_columns
$result->set_inflated_columns({ $col => $val, $rel_name => $obj, ... });- Arguments: \%columndata
- Return Value: $result
Sets more than one column value at once. Any inflated values are deflated and the raw values stored.
Any related values passed as Result objects, using the relation name as a key, are reduced to the appropriate foreign key values and stored.
A hashref passed in place of a related result object is taken as column values of the related row and reduced the same way, so it has to carry the columns the relationship is keyed on:
$cd->set_inflated_columns({ artist => { artistid => 7 } }); # sets the foreign key
$cd->set_inflated_columns({ artist => { name => 'Ann' } }); # throwsA hashref that leaves one of this row's columns undetermined throws Relationship '...' does not resolve to a concrete column condition and sets nothing, see "set_from_related" in DBIO::Relationship::Base. No related row is looked up, created or changed for it: related rows are created along with a row only when that row is built, see "create" in DBIO::ResultSet.
A value passed for a "has_many" in DBIO::Relationship key throws an exception: recursive update is not supported over relationships of type multi.
Be aware that the input hashref might be edited in place, so don't rely on it being the same after a call to set_inflated_columns. If you need to preserve the hashref, it is sufficient to pass a shallow copy to set_inflated_columns, e.g. ( { %{ $href } } )
See also "set_from_related" in DBIO::Relationship::Base.
copy
my $copy = $orig->copy({ change => $to, ... });- Arguments: \%replacementdata
- Return Value: $result copy
Inserts a new row into the database, as a copy of the original object. If a hashref of replacement data is supplied, these will take precedence over data in the original. Also any columns which have the column info attribute is_auto_increment => 1 are explicitly removed before the copy, so that the database can insert its own autoincremented values into the new object.
Relationships will be followed by the copy procedure only if the relationship specifies a true value for its cascade_copy attribute. cascade_copy is set by default on has_many relationships and unset on all others.
copy_async
my $future = $orig->copy_async({ change => $to, ... });
$future->then(sub { my $copy = shift; ... });Async variant of "copy". For a flat copy -- no relationship on this row's source with cascade_copy set (on by default for has_many, unset on all others) -- applies the same pre-insert work as "copy" (proxy-slot stripping, dropping auto-increment columns, building the new row's column set, set_inflated_columns with the supplied %replacementdata) and dispatches the insert through "insert_async", resolving with the new row.
A row whose source has a cascade_copy relationship cannot be expressed as a single async statement: copying the related rows is itself a recursive, multi-row operation that "copy" performs directly in its own loop (not a component wrap this time, but the same "more than one statement" shape as "insert_async"'s related-object multi-create punt). Such a row is copied synchronously instead (through the full "copy", so the cascade still runs) and the Future resolves immediately. Like sync "copy", no transaction is opened, even for the cascading case.
Requires an async connection; on a sync instance it croaks, and in the immediate mode it degrades to a synchronous copy wrapped in an immediately-resolved Future. See ADR 0030/0031.
store_column
$result->store_column($col => $val);Set a raw value for a column without marking it as changed. This method is used internally by "set_column" which you should probably be using.
This is the lowest level at which data is set on a result object, extend this method to catch all data setting methods.
inflate_result
Class->inflate_result($result_source, \%me, \%prefetch?)- Arguments: $result_source, \%columndata, \%prefetcheddata
- Return Value: $result
All DBIO::ResultSet methods that retrieve data from the database and turn it into result objects call this method.
Extend this method in your Result classes to hook into this process, for example to rebless the result into a different class.
Reblessing can also be done more easily by setting result_class in your Result class. See "result_class" in DBIO::ResultSource.
Different types of results can also be created from a particular DBIO::ResultSet, see "result_class" in DBIO::ResultSet.
update_or_insert
$result->update_or_insert"update"s the object if it's already in the database, according to "in_storage", else "insert"s it.
insert_or_update
$obj->insert_or_updateAlias for "update_or_insert"
insert_or_update_async
my $future = $obj->insert_or_update_async;Alias for "update_or_insert_async"
update_or_insert_async
my $future = $result->update_or_insert_async;
$future->then(sub { my $row = shift; ... });Async variant of "update_or_insert". Delegates to "update_async" for rows already in storage, else "insert_async" -- exactly like the sync method, this takes no arguments. Carries whichever of the two methods' own backend routing, immediate degrade, and croak-on-sync-instance contract applies with no further wrapping needed here. See ADR 0030/0031.
is_changed
my @changed_col_names = $result->is_changed();
if ($result->is_changed()) { ... }In list context returns a list of columns with uncommited changes, or in scalar context returns a true value if there are uncommitted changes.
is_column_changed
if ($result->is_column_changed('col')) { ... }Returns a true value if the column has uncommitted changes.
result_source
my $resultsource = $result->result_source;- Arguments: $result_source?
- Return Value: $result_source
Accessor to the DBIO::ResultSource this object was created from.
register_column
$column_info = { .... };
$class->register_column($column_name, $column_info);Registers a column on the class. If the column_info has an 'accessor' key, creates an accessor named after the value if defined; if there is no such key, creates an accessor with the same name as the column
The column_info attributes are described in "add_columns" in DBIO::ResultSource
get_from_storage
my $copy = $result->get_from_storage($attrs)Fetches a fresh copy of the Result object from the database and returns it.
On a source that declares a primary key the row is looked up by that primary key, and an exception is thrown if a proper WHERE clause identifying the database row can not be constructed (i.e. if the original object does not contain its entire primary key).
On a source without a primary key the lookup falls back to "find" in DBIO::ResultSet's heuristics mode: the WHERE clause is built from every loaded column, so any unique constraint declared on the source can be matched, and a source declaring none at all is looked up by all of its loaded columns (in which case the first matching row is returned). This is a deliberate extension -- prior to it get_from_storage died outright on primary-keyless sources.
Each column contributes its last known in-storage value in preference to a locally modified one, so a Result carrying unsaved changes still identifies the row it was loaded from rather than searching for its own new values. This is the same precedence the primary-key path applies, and it shares that path's one limit: a column that never carried a storage-side value at all -- because it was never loaded, or was changed while the Result was not "in_storage" -- has no previous value to fall back on and contributes its current one.
If passed the \%attrs argument, will first apply these attributes to the resultset used to find the row.
This copy can then be used to compare to an existing result object, to determine if any changes have been made in the database since it was created.
To just update your Result object with any latest changes from the database, use "discard_changes" instead.
The \%attrs argument should be compatible with "ATTRIBUTES" in DBIO::ResultSet.
get_from_storage_async
my $future = $result->get_from_storage_async($attrs)
$future->then(sub { my $copy = shift; ... });Async variant of "get_from_storage". Shares its exact lookup -- built on "find_async" in DBIO::ResultSet rather than "get_from_storage"'s own "find" in DBIO::ResultSet, so it carries find_async's own backend routing, immediate degrade, and croak-on-sync-instance contract with no further wrapping needed here. See ADR 0030/0031.
That includes the primary-keyless fallback described under "get_from_storage", with the same column-value precedence and the same limit on columns that never carried a storage-side value.
discard_changes
$result->discard_changes- Arguments: none or $attrs
- Return Value: $result (updated in-place), but only when the row is in storage
Re-selects the row from the database, losing any changes that had been made. Throws an exception if a proper WHERE clause identifying the database row can not be constructed (i.e. if the original object does not contain its entire primary key).
This method can also be used to refresh from storage, retrieving any changes made since the row was last read from storage.
If the row is not in storage ($result->in_storage is false) the method returns immediately without re-selecting and yields nothing (an empty list, or undef in scalar context), so do not rely on it returning $result for chaining in that case.
$attrs, if supplied, is expected to be a hashref of attributes suitable for passing as the second argument to $resultset->search($cond, $attrs);
Note: If you are using DBIO::Replicated::Storage as your storage, a default of { force_pool => 'master' } is automatically set for you.
discard_changes_async
my $future = $result->discard_changes_async;
$future->then(sub { my $row = shift; ... }); # $row is $self, refreshed in placeAsync variant of "discard_changes". If the row is not "in_storage", resolves with undef and issues no query at all -- exactly like sync "discard_changes". Otherwise re-fetches via "get_from_storage_async" and, in the Future's then, either refreshes $self in place from the fresh copy (row still exists) or marks $self no longer "in_storage" (row has vanished), resolving with $self either way.
Requires an async connection; on a sync instance it croaks, and in the immediate mode it degrades to a synchronous refresh wrapped in an immediately-resolved Future. See ADR 0030/0031.
throw_exception
See "throw_exception" in DBIO::Schema.
TO_JSON
my $hashref = $row->TO_JSON;Returns a hashref of the row's column values suitable for JSON serialization. Automatically excludes text, ntext, and blob columns unless is_serializable => 1 is set in the column info. Numeric columns are numified for correct JSON output.
self_rs
my $rs = $row->self_rs;Returns a ResultSet containing only this row, useful for applying ResultSet methods to a single row. A binding made with "with_context" goes with it.
clean_rs
my $rs = $row->clean_rs;Returns a fresh, unsearched ResultSet for this row's result source. A binding made with "with_context" goes with it.
StorageValues
Per-column opt-in snapshot of the values as last seen in storage. Mark a column with keep_storage_value => 1 and DBIO will record its current stored value at insert, update and inflate_result time. The snapshot uses the column accessor, so inflated / filtered values are captured rather than raw storage values.
__PACKAGE__->add_column(title => {
data_type => 'varchar',
keep_storage_value => 1,
});
$row->title('New');
$row->get_storage_value('title'); # the old value
$row->update;
$row->get_storage_value('title'); # now 'New'OnColumnChange
Register before_column_change, after_column_change, and around_column_change callbacks on a Result class. Callbacks fire from "update" only if the named column is actually dirty. The "old" value comes from "get_storage_value", so pair this with keep_storage_value => 1 on the column if you need a real previous value; otherwise it will be undef.
__PACKAGE__->before_column_change(
amount => { method => 'bank_transfer', txn_wrap => 1 },
);Callback signatures:
before: $self->$method($old, $new)
after: $self->$method($old, $new) # $old may now equal $new
around: $self->$method($next, $old, $new)before callbacks fire in definition order, after callbacks fire in reverse order, around callbacks wrap in definition order (the first declared being the outermost, the last declared wrapping the actual update). If any registered arg has txn_wrap => 1 the whole update is wrapped in a txn_scope_guard.
See "on_column_change_allow_override_args" for what it controls.
ProxyResultSetMethod
Expose a with_foo ResultSet method as a row accessor with a transparent fallback: if the column was already selected via the ResultSet method it is returned from the cached row data; otherwise the ResultSet method is re-run for this row.
package MyApp::Schema::ResultSet::Foo;
sub with_friend_count { ... }
package MyApp::Schema::Result::Foo;
__PACKAGE__->proxy_resultset_method('friend_count');
$foo_rs->first->friend_count; # lazy fetch
$foo_rs->with_friend_count->first->friend_count; # cachedThe generated accessor stores the fetched value under the slot name in _column_data as a cache. Proxied slots are excluded from copy and update so they are never written as actual columns.
id
my @pk = $result->id;Returns the primary key(s) for a row. Can't be called as a class method. Actually implemented in DBIO::PK
AUTHOR
DBIO & DBIx::Class Authors
COPYRIGHT AND LICENSE
Copyright (C) 2026 DBIO Authors Portions Copyright (C) 2005-2025 DBIx::Class Authors Based on DBIx::Class, heavily modified.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.