1DBIx::Class::Row(3) User Contributed Perl Documentation DBIx::Class::Row(3)
2
6 DBIx::Class::Row - Basic row methods
7
10 This class is responsible for defining and doing basic operations on
11 rows derived from DBIx::Class::ResultSource objects.
12 Result objects are returned from DBIx::Class::ResultSets using the
14 create, find, next and all methods, as well as invocations of 'single'
15 ( belongs_to, has_one or might_have) relationship accessors of Result
16 objects.
17
19 All "Row objects" derived from a Schema-attached DBIx::Class::ResultSet
20 object (such as a typical "search-> next" call) are actually Result
21 instances, based on your application's Result Class.
22 DBIx::Class::Row implements most of the row-based communication with
24 the underlying storage, but a Result class should not inherit from it
25 directly. Usually, Result classes inherit from DBIx::Class::Core,
26 which in turn combines the methods from several classes, one of them
27 being DBIx::Class::Row. Therefore, while many of the methods available
28 to a DBIx::Class::Core-derived Result class are described in the
29 following documentation, it does not detail all of the methods
30 available to Result objects. Refer to DBIx::Class::Manual::ResultClass
31 for more info.
32
34 new
35 my $result = My::Class->new(\%attrs);
36 my $result = $schema->resultset('MySource')->new(\%colsandvalues);
38 Arguments: \%attrs or \%colsandvalues
40 Return Value: $result
41 While you can create a new result object by calling "new" directly on
43 this class, you are better off calling it on a DBIx::Class::ResultSet
44 object.
45 When calling it directly, you will not get a complete, usable row
47 object until you pass or set the "result_source" attribute, to a
48 DBIx::Class::ResultSource instance that is attached to a
49 DBIx::Class::Schema with a valid connection.
50 $attrs is a hashref of column name, value data. It can also contain
52 some other attributes such as the "result_source".
53 Passing an object, or an arrayref of objects as a value will call
55 "set_from_related" in DBIx::Class::Relationship::Base for you. When
56 passed a hashref or an arrayref of hashrefs as the value, these will be
57 turned into objects via new_related, and treated as if you had passed
58 objects.
59 For a more involved explanation, see "create" in
61 DBIx::Class::ResultSet.
62 Please note that if a value is not passed to new, no value will be sent
64 in the SQL INSERT call, and the column will therefore assume whatever
65 default value was specified in your database. While DBIC will retrieve
66 the value of autoincrement columns, it will never make an explicit
67 database trip to retrieve default values assigned by the RDBMS. You can
68 explicitly request that all values be fetched back from the database by
69 calling "discard_changes", or you can supply an explicit "undef" to
70 columns with NULL as the default, and save yourself a SELECT.
71 CAVEAT:
73 The behavior described above will backfire if you use a foreign key column
75 with a database-defined default. If you call the relationship accessor on
76 an object that doesn't have a set value for the FK column, DBIC will throw
77 an exception, as it has no way of knowing the PK of the related object (if
78 there is one).
79 $column_accessor
81 # Each pair does the same thing
82 # (un-inflated, regular column)
84 my $val = $result->get_column('first_name');
85 my $val = $result->first_name;
86 $result->set_column('first_name' => $val);
88 $result->first_name($val);
89 # (inflated column via DBIx::Class::InflateColumn::DateTime)
91 my $val = $result->get_inflated_column('last_modified');
92 my $val = $result->last_modified;
93 $result->set_inflated_column('last_modified' => $val);
95 $result->last_modified($val);
96 Arguments: $value?
98 Return Value: $value
99 A column accessor method is created for each column, which is used for
101 getting/setting the value for that column.
102 The actual method name is based on the accessor name given during the
104 Result Class column definition . Like "set_column", this will not store
105 the data in the database until "insert" or "update" is called on the
106 row.
107 insert
109 $result->insert;
110 Arguments: none
112 Return Value: $result
113 Inserts an object previously created by "new" into the database if it
115 isn't already in there. Returns the object itself. To insert an
116 entirely new row into the database, use "create" in
117 DBIx::Class::ResultSet.
118 To fetch an uninserted result object, call new_result on a resultset.
120 This will also insert any uninserted, related objects held inside this
122 one, see "create" in DBIx::Class::ResultSet for more details.
123 in_storage
125 $result->in_storage; # Get value
126 $result->in_storage(1); # Set value
127 Arguments: none or 1|0
129 Return Value: 1|0
130 Indicates whether the object exists as a row in the database or not.
132 This is set to true when "find" in DBIx::Class::ResultSet, "create" in
133 DBIx::Class::ResultSet or "insert" in DBIx::Class::Row are invoked.
134 Creating a result object using "new_result" in DBIx::Class::ResultSet,
136 or calling "delete" on one, sets it to false.
137 update
139 $result->update(\%columns?)
140 Arguments: none or a hashref
142 Return Value: $result
143 Throws an exception if the result object is not yet in the database,
145 according to "in_storage". Returns the object itself.
146 This method issues an SQL UPDATE query to commit any changes to the
148 object to the database if required (see "get_dirty_columns"). It
149 throws an exception if a proper WHERE clause uniquely identifying the
150 database row can not be constructed (see significance of primary keys
151 for more details).
152 Also takes an optional hashref of "column_name => value" pairs to
154 update on the object first. Be aware that the hashref will be passed to
155 "set_inflated_columns", which might edit it in place, so don't rely on
156 it being the same after a call to "update". If you need to preserve
157 the hashref, it is sufficient to pass a shallow copy to "update", e.g.
158 ( { %{ $href } } )
159 If the values passed or any of the column values set on the object
161 contain scalar references, e.g.:
162 $result->last_modified(\'NOW()')->update();
164 # OR
165 $result->update({ last_modified => \'NOW()' });
166 The update will pass the values verbatim into SQL. (See
168 SQL::Abstract::Classic docs). The values in your Result object will
169 NOT change as a result of the update call, if you want the object to be
170 updated with the actual values from the database, call
171 "discard_changes" after the update.
172 $result->update()->discard_changes();
174 To determine before calling this method, which column values have
176 changed and will be updated, call "get_dirty_columns".
177 To check if any columns will be updated, call "is_changed".
179 To force a column to be updated, call "make_column_dirty" before this
181 method.
182 delete
184 $result->delete
185 Arguments: none
187 Return Value: $result
188 Throws an exception if the object is not in the database according to
190 "in_storage". Also throws an exception if a proper WHERE clause
191 uniquely identifying the database row can not be constructed (see
192 significance of primary keys for more details).
193 The object is still perfectly usable, but "in_storage" will now return
195 0 and the object must be reinserted using "insert" before it can be
196 used to "update" the row again.
197 If you delete an object in a class with a "has_many" relationship, an
199 attempt is made to delete all the related objects as well. To turn this
200 behaviour off, pass "cascade_delete => 0" in the $attr hashref of the
201 relationship, see DBIx::Class::Relationship. Any database-level cascade
202 or restrict will take precedence over a DBIx-Class-based cascading
203 delete, since DBIx-Class deletes the main row first and only then
204 attempts to delete any remaining related rows.
205 If you delete an object within a txn_do() (see "txn_do" in
207 DBIx::Class::Storage) and the transaction subsequently fails, the
208 result object will remain marked as not being in storage. If you know
209 for a fact that the object is still in storage (i.e. by inspecting the
210 cause of the transaction's failure), you can use "$obj->in_storage(1)"
211 to restore consistency between the object and the database. This would
212 allow a subsequent "$obj->delete" to work as expected.
213 See also "delete" in DBIx::Class::ResultSet.
215 get_column
217 my $val = $result->get_column($col);
218 Arguments: $columnname
220 Return Value: The value of the column
221 Throws an exception if the column name given doesn't exist according to
223 has_column.
224 Returns a raw column value from the result object, if it has already
226 been fetched from the database or set by an accessor.
227 If an inflated value has been set, it will be deflated and returned.
229 Note that if you used the "columns" or the "select/as" search
231 attributes on the resultset from which $result was derived, and did not
232 include $columnname in the list, this method will return "undef" even
233 if the database contains some value.
234 To retrieve all loaded column values as a hash, use "get_columns".
236 has_column_loaded
238 if ( $result->has_column_loaded($col) ) {
239 print "$col has been loaded from db";
240 }
241 Arguments: $columnname
243 Return Value: 0|1
244 Returns a true value if the column value has been loaded from the
246 database (or set locally).
247 get_columns
249 my %data = $result->get_columns;
250 Arguments: none
252 Return Value: A hash of columnname, value pairs.
253 Returns all loaded column data as a hash, containing raw values. To get
255 just one value for a particular column, use "get_column".
256 See "get_inflated_columns" to get the inflated values.
258 get_dirty_columns
260 my %data = $result->get_dirty_columns;
261 Arguments: none
263 Return Value: A hash of column, value pairs
264 Only returns the column, value pairs for those columns that have been
266 changed on this object since the last "update" or "insert" call.
267 See "get_columns" to fetch all column/value pairs.
269 make_column_dirty
271 $result->make_column_dirty($col)
272 Arguments: $columnname
274 Return Value: not defined
275 Throws an exception if the column does not exist.
277 Marks a column as having been changed regardless of whether it has
279 really changed.
280 get_inflated_columns
282 my %inflated_data = $obj->get_inflated_columns;
283 Arguments: none
285 Return Value: A hash of column, object|value pairs
286 Returns a hash of all column keys and associated values. Values for any
288 columns set to use inflation will be inflated and returns as objects.
289 See "get_columns" to get the uninflated values.
291 See DBIx::Class::InflateColumn for how to setup inflation.
293 set_column
295 $result->set_column($col => $val);
296 Arguments: $columnname, $value
298 Return Value: $value
299 Sets a raw column value. If the new value is different from the old
301 one, the column is marked as dirty for when you next call "update".
302 If passed an object or reference as a value, this method will happily
304 attempt to store it, and a later "insert" or "update" will try and
305 stringify/numify as appropriate. To set an object to be deflated
306 instead, see "set_inflated_columns", or better yet, use
307 "$column_accessor".
308 set_columns
310 $result->set_columns({ $col => $val, ... });
311 Arguments: \%columndata
313 Return Value: $result
314 Sets multiple column, raw value pairs at once.
316 Works as "set_column".
318 set_inflated_columns
320 $result->set_inflated_columns({ $col => $val, $rel_name => $obj, ... });
321 Arguments: \%columndata
323 Return Value: $result
324 Sets more than one column value at once. Any inflated values are
326 deflated and the raw values stored.
327 Any related values passed as Result objects, using the relation name as
329 a key, are reduced to the appropriate foreign key values and stored. If
330 instead of related result objects, a hashref of column, value data is
331 passed, will create the related object first then store.
332 Will even accept arrayrefs of data as a value to a "has_many" in
334 DBIx::Class::Relationship key, and create the related objects if
335 necessary.
336 Be aware that the input hashref might be edited in place, so don't rely
338 on it being the same after a call to "set_inflated_columns". If you
339 need to preserve the hashref, it is sufficient to pass a shallow copy
340 to "set_inflated_columns", e.g. ( { %{ $href } } )
341 See also "set_from_related" in DBIx::Class::Relationship::Base.
343 copy
345 my $copy = $orig->copy({ change => $to, ... });
346 Arguments: \%replacementdata
348 Return Value: $result copy
349 Inserts a new row into the database, as a copy of the original object.
351 If a hashref of replacement data is supplied, these will take
352 precedence over data in the original. Also any columns which have the
353 column info attribute "is_auto_increment => 1" are explicitly removed
354 before the copy, so that the database can insert its own
355 autoincremented values into the new object.
356 Relationships will be followed by the copy procedure only if the
358 relationship specifies a true value for its cascade_copy attribute.
359 "cascade_copy" is set by default on "has_many" relationships and unset
360 on all others.
361 store_column
363 $result->store_column($col => $val);
364 Arguments: $columnname, $value
366 Return Value: The value sent to storage
367 Set a raw value for a column without marking it as changed. This method
369 is used internally by "set_column" which you should probably be using.
370 This is the lowest level at which data is set on a result object,
372 extend this method to catch all data setting methods.
373 inflate_result
375 Class->inflate_result($result_source, \%me, \%prefetch?)
376 Arguments: $result_source, \%columndata, \%prefetcheddata
378 Return Value: $result
379 All DBIx::Class::ResultSet methods that retrieve data from the database
381 and turn it into result objects call this method.
382 Extend this method in your Result classes to hook into this process,
384 for example to rebless the result into a different class.
385 Reblessing can also be done more easily by setting "result_class" in
387 your Result class. See "result_class" in DBIx::Class::ResultSource.
388 Different types of results can also be created from a particular
390 DBIx::Class::ResultSet, see "result_class" in DBIx::Class::ResultSet.
391 update_or_insert
393 $result->update_or_insert
394 Arguments: none
396 Return Value: Result of update or insert operation
397 "update"s the object if it's already in the database, according to
399 "in_storage", else "insert"s it.
400 insert_or_update
402 $obj->insert_or_update
403 Alias for "update_or_insert"
405 is_changed
407 my @changed_col_names = $result->is_changed();
408 if ($result->is_changed()) { ... }
409 Arguments: none
411 Return Value: 0|1 or @columnnames
412 In list context returns a list of columns with uncommited changes, or
414 in scalar context returns a true value if there are uncommitted
415 changes.
416 is_column_changed
418 if ($result->is_column_changed('col')) { ... }
419 Arguments: $columname
421 Return Value: 0|1
422 Returns a true value if the column has uncommitted changes.
424 result_source
426 my $resultsource = $result->result_source;
427 Arguments: $result_source?
429 Return Value: $result_source
430 Accessor to the DBIx::Class::ResultSource this object was created from.
432 register_column
434 $column_info = { .... };
435 $class->register_column($column_name, $column_info);
436 Arguments: $columnname, \%columninfo
438 Return Value: not defined
439 Registers a column on the class. If the column_info has an 'accessor'
441 key, creates an accessor named after the value if defined; if there is
442 no such key, creates an accessor with the same name as the column
443 The column_info attributes are described in "add_columns" in
445 DBIx::Class::ResultSource
446 get_from_storage
448 my $copy = $result->get_from_storage($attrs)
449 Arguments: \%attrs
451 Return Value: A Result object
452 Fetches a fresh copy of the Result object from the database and returns
454 it. Throws an exception if a proper WHERE clause identifying the
455 database row can not be constructed (i.e. if the original object does
456 not contain its entire
457 primary key ). If passed the \%attrs argument, will first apply these
458 attributes to the resultset used to find the row.
459 This copy can then be used to compare to an existing result object, to
461 determine if any changes have been made in the database since it was
462 created.
463 To just update your Result object with any latest changes from the
465 database, use "discard_changes" instead.
466 The \%attrs argument should be compatible with "ATTRIBUTES" in
468 DBIx::Class::ResultSet.
469 discard_changes
471 $result->discard_changes
472 Arguments: none or $attrs
474 Return Value: self (updates object in-place)
475 Re-selects the row from the database, losing any changes that had been
477 made. Throws an exception if a proper "WHERE" clause identifying the
478 database row can not be constructed (i.e. if the original object does
479 not contain its entire primary key).
480 This method can also be used to refresh from storage, retrieving any
482 changes made since the row was last read from storage.
483 $attrs, if supplied, is expected to be a hashref of attributes suitable
485 for passing as the second argument to "$resultset->search($cond,
486 $attrs)";
487 Note: If you are using DBIx::Class::Storage::DBI::Replicated as your
489 storage, a default of "{ force_pool => 'master' }"
490 is automatically set for you. Prior to "DBIx::Class 0.08109" (before
491 2010) one would have been required to explicitly wrap the entire
492 operation in a transaction to guarantee that up-to-date results are
493 read from the master database.
494 throw_exception
496 See "throw_exception" in DBIx::Class::Schema.
497 id
499 my @pk = $result->id;
500 Arguments: none
502 Returns: A list of primary key values
503 Returns the primary key(s) for a row. Can't be called as a class
505 method. Actually implemented in DBIx::Class::PK
506
508 Check the list of additional DBIC resources.
509
511 This module is free software copyright by the DBIx::Class (DBIC)
512 authors. You can redistribute it and/or modify it under the same terms
513 as the DBIx::Class library.
514perl v5.36.0 2023-01-20 DBIx::Class::Row(3)