/ 
DBIx-Class-0.08099_04
River stage three • 349 direct dependents • 459 total dependents
/ DBIx::Class::Row

NAME

DBIx::Class::Row - Basic row methods

SYNOPSIS

DESCRIPTION

This class is responsible for defining and doing basic operations on rows derived from DBIx::Class::ResultSource objects.

METHODS

new

my $obj = My::Class->new($attrs);

Creates a new row object from column => value mappings passed as a hash ref

Passing an object, or an arrayref of objects as a value will call "set_from_related" in DBIx::Class::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 DBIx::Class::ResultSet.

insert

$obj->insert;

Inserts an object into the database if it isn't already in there. Returns the object itself. Requires the object's result source to be set, or the class to have a result_source_instance method. To insert an entirely new object into the database, use create (see "create" in DBIx::Class::ResultSet).

To fetch an uninserted row object, call new on a resultset.

This will also insert any uninserted, related objects held inside this one, see "create" in DBIx::Class::ResultSet for more details.

in_storage

$obj->in_storage; # Get value
$obj->in_storage(1); # Set value

Indicates whether the object exists as a row in the database or not. This is set to true when "find" in DBIx::Class::ResultSet, "create" in DBIx::Class::ResultSet or "insert" in DBIx::Class::ResultSet are used.

Creating a row object using "new" in DBIx::Class::ResultSet, or calling "delete" on one, sets it to false.

update

$obj->update \%columns?;

Must be run on an object that is already in the database; issues an SQL UPDATE query to commit any changes to the object to the database if required.

Also takes an options hashref of column_name => value> pairs to update first. But be aware that the hashref will be passed to set_inflated_columns, which might edit it in place, so dont 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 } } )

If the values passed or any of the column values set on the object contain scalar references, eg:

$obj->last_modified(\'NOW()');
# OR
$obj->update({ last_modified => \'NOW()' });

The update will pass the values verbatim into SQL. (See SQL::Abstract docs). The values in your Row 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.

$obj->update()->discard_changes();

delete

$obj->delete

Deletes the object from the database. The object is still perfectly usable, but ->in_storage() will now return 0 and the object must reinserted using ->insert() before ->update() can be used on it. If you delete an object in a class with a has_many relationship, all the related objects will be deleted as well. To turn this behavior off, pass cascade_delete => 0 in the $attr hashref. Any database-level cascade or restrict will take precedence over a DBIx-Class-based cascading delete. See also "delete" in DBIx::Class::ResultSet.

get_column

my $val = $obj->get_column($col);

Returns a raw column value from the row 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.

has_column_loaded

if ( $obj->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 = $obj->get_columns;

Does get_column, for all loaded column values at once.

get_dirty_columns

my %data = $obj->get_dirty_columns;

Identical to get_columns but only returns those that have been changed.

make_column_dirty

Marks a column dirty regardless if it has really changed. Throws an exception if the column does not exist.

get_inflated_columns

my %inflated_data = $obj->get_inflated_columns;

Similar to get_columns but objects are returned for inflated columns instead of their raw non-inflated values.

set_column

$obj->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 $obj->update.

If passed an object or reference, this will happily attempt store the value, and a later insert/update will try and stringify/numify as appropriate.

set_columns

my $copy = $orig->set_columns({ $col => $val, ... });

Sets more than one column value at once.

set_inflated_columns

my $copy = $orig->set_inflated_columns({ $col => $val, $rel => $obj, ... });

Sets more than one column value at once, taking care to respect inflations and relationships if relevant. Be aware that this hashref might be edited in place, so dont 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 } } )

copy

my $copy = $orig->copy({ change => $to, ... });

Inserts a new row with the specified changes. If the row has related objects in a has_many then those objects may be copied too depending on the cascade_copy relationship attribute.

store_column

$obj->store_column($col => $val);

Sets a column value without marking it as dirty.

inflate_result

Class->inflate_result($result_source, \%me, \%prefetch?)

Called by ResultSet to inflate a result from storage

update_or_insert

$obj->update_or_insert

Updates the object if it's already in the database, according to "in_storage", else inserts it.

insert_or_update

$obj->insert_or_update

Alias for "update_or_insert"

is_changed

my @changed_col_names = $obj->is_changed();
if ($obj->is_changed()) { ... }

In array 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 ($obj->is_column_changed('col')) { ... }

Returns a true value if the column has uncommitted changes.

result_source

my $resultsource = $object->result_source;

Accessor to the 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 DBIx::Class::ResultSource

get_from_storage ($attrs)

Returns a new Row which is whatever the Storage has for the currently created Row object. You can use this to see if the storage has become inconsistent with whatever your Row object is.

$attrs is expected to be a hashref of attributes suitable for passing as the second argument to $resultset->search($cond, $attrs);

throw_exception

See Schema's throw_exception.

id

Returns the primary key(s) for a row. Can't be called as a class method. Actually implemented in DBIx::Class::PK

discard_changes

Re-selects the row from the database, losing any changes that had been made.

This method can also be used to refresh from storage, retrieving any changes made since the row was last read from storage. Actually implemented in DBIx::Class::PK

AUTHORS

Matt S. Trout <mst@shadowcatsystems.co.uk>

LICENSE

You may distribute this code under the same terms as Perl itself.