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 SQL::Abstract
168 docs). The values in your Result object will NOT change as a result of
169 the update call, if you want the object to be updated with the actual
170 values from the database, call "discard_changes" after the update.
171 $result->update()->discard_changes();
173 To determine before calling this method, which column values have
175 changed and will be updated, call "get_dirty_columns".
176 To check if any columns will be updated, call "is_changed".
178 To force a column to be updated, call "make_column_dirty" before this
180 method.
181 delete
183 $result->delete
184 Arguments: none
186 Return Value: $result
187 Throws an exception if the object is not in the database according to
189 "in_storage". Also throws an exception if a proper WHERE clause
190 uniquely identifying the database row can not be constructed (see
191 significance of primary keys for more details).
192 The object is still perfectly usable, but "in_storage" will now return
194 0 and the object must be reinserted using "insert" before it can be
195 used to "update" the row again.
196 If you delete an object in a class with a "has_many" relationship, an
198 attempt is made to delete all the related objects as well. To turn this
199 behaviour off, pass "cascade_delete => 0" in the $attr hashref of the
200 relationship, see DBIx::Class::Relationship. Any database-level cascade
201 or restrict will take precedence over a DBIx-Class-based cascading
202 delete, since DBIx-Class deletes the main row first and only then
203 attempts to delete any remaining related rows.
204 If you delete an object within a txn_do() (see "txn_do" in
206 DBIx::Class::Storage) and the transaction subsequently fails, the
207 result object will remain marked as not being in storage. If you know
208 for a fact that the object is still in storage (i.e. by inspecting the
209 cause of the transaction's failure), you can use "$obj->in_storage(1)"
210 to restore consistency between the object and the database. This would
211 allow a subsequent "$obj->delete" to work as expected.
212 See also "delete" in DBIx::Class::ResultSet.
214 get_column
216 my $val = $result->get_column($col);
217 Arguments: $columnname
219 Return Value: The value of the column
220 Throws an exception if the column name given doesn't exist according to
222 has_column.
223 Returns a raw column value from the result object, if it has already
225 been fetched from the database or set by an accessor.
226 If an inflated value has been set, it will be deflated and returned.
228 Note that if you used the "columns" or the "select/as" search
230 attributes on the resultset from which $result was derived, and did not
231 include $columnname in the list, this method will return "undef" even
232 if the database contains some value.
233 To retrieve all loaded column values as a hash, use "get_columns".
235 has_column_loaded
237 if ( $result->has_column_loaded($col) ) {
238 print "$col has been loaded from db";
239 }
240 Arguments: $columnname
242 Return Value: 0|1
243 Returns a true value if the column value has been loaded from the
245 database (or set locally).
246 get_columns
248 my %data = $result->get_columns;
249 Arguments: none
251 Return Value: A hash of columnname, value pairs.
252 Returns all loaded column data as a hash, containing raw values. To get
254 just one value for a particular column, use "get_column".
255 See "get_inflated_columns" to get the inflated values.
257 get_dirty_columns
259 my %data = $result->get_dirty_columns;
260 Arguments: none
262 Return Value: A hash of column, value pairs
263 Only returns the column, value pairs for those columns that have been
265 changed on this object since the last "update" or "insert" call.
266 See "get_columns" to fetch all column/value pairs.
268 make_column_dirty
270 $result->make_column_dirty($col)
271 Arguments: $columnname
273 Return Value: not defined
274 Throws an exception if the column does not exist.
276 Marks a column as having been changed regardless of whether it has
278 really changed.
279 get_inflated_columns
281 my %inflated_data = $obj->get_inflated_columns;
282 Arguments: none
284 Return Value: A hash of column, object|value pairs
285 Returns a hash of all column keys and associated values. Values for any
287 columns set to use inflation will be inflated and returns as objects.
288 See "get_columns" to get the uninflated values.
290 See DBIx::Class::InflateColumn for how to setup inflation.
292 set_column
294 $result->set_column($col => $val);
295 Arguments: $columnname, $value
297 Return Value: $value
298 Sets a raw column value. If the new value is different from the old
300 one, the column is marked as dirty for when you next call "update".
301 If passed an object or reference as a value, this method will happily
303 attempt to store it, and a later "insert" or "update" will try and
304 stringify/numify as appropriate. To set an object to be deflated
305 instead, see "set_inflated_columns", or better yet, use
306 "$column_accessor".
307 set_columns
309 $result->set_columns({ $col => $val, ... });
310 Arguments: \%columndata
312 Return Value: $result
313 Sets multiple column, raw value pairs at once.
315 Works as "set_column".
317 set_inflated_columns
319 $result->set_inflated_columns({ $col => $val, $rel_name => $obj, ... });
320 Arguments: \%columndata
322 Return Value: $result
323 Sets more than one column value at once. Any inflated values are
325 deflated and the raw values stored.
326 Any related values passed as Result objects, using the relation name as
328 a key, are reduced to the appropriate foreign key values and stored. If
329 instead of related result objects, a hashref of column, value data is
330 passed, will create the related object first then store.
331 Will even accept arrayrefs of data as a value to a "has_many" in
333 DBIx::Class::Relationship key, and create the related objects if
334 necessary.
335 Be aware that the input hashref might be edited in place, so don't rely
337 on it being the same after a call to "set_inflated_columns". If you
338 need to preserve the hashref, it is sufficient to pass a shallow copy
339 to "set_inflated_columns", e.g. ( { %{ $href } } )
340 See also "set_from_related" in DBIx::Class::Relationship::Base.
342 copy
344 my $copy = $orig->copy({ change => $to, ... });
345 Arguments: \%replacementdata
347 Return Value: $result copy
348 Inserts a new row into the database, as a copy of the original object.
350 If a hashref of replacement data is supplied, these will take
351 precedence over data in the original. Also any columns which have the
352 column info attribute "is_auto_increment => 1" are explicitly removed
353 before the copy, so that the database can insert its own
354 autoincremented values into the new object.
355 Relationships will be followed by the copy procedure only if the
357 relationship specifies a true value for its cascade_copy attribute.
358 "cascade_copy" is set by default on "has_many" relationships and unset
359 on all others.
360 store_column
362 $result->store_column($col => $val);
363 Arguments: $columnname, $value
365 Return Value: The value sent to storage
366 Set a raw value for a column without marking it as changed. This method
368 is used internally by "set_column" which you should probably be using.
369 This is the lowest level at which data is set on a result object,
371 extend this method to catch all data setting methods.
372 inflate_result
374 Class->inflate_result($result_source, \%me, \%prefetch?)
375 Arguments: $result_source, \%columndata, \%prefetcheddata
377 Return Value: $result
378 All DBIx::Class::ResultSet methods that retrieve data from the database
380 and turn it into result objects call this method.
381 Extend this method in your Result classes to hook into this process,
383 for example to rebless the result into a different class.
384 Reblessing can also be done more easily by setting "result_class" in
386 your Result class. See "result_class" in DBIx::Class::ResultSource.
387 Different types of results can also be created from a particular
389 DBIx::Class::ResultSet, see "result_class" in DBIx::Class::ResultSet.
390 update_or_insert
392 $result->update_or_insert
393 Arguments: none
395 Return Value: Result of update or insert operation
396 "update"s the object if it's already in the database, according to
398 "in_storage", else "insert"s it.
399 insert_or_update
401 $obj->insert_or_update
402 Alias for "update_or_insert"
404 is_changed
406 my @changed_col_names = $result->is_changed();
407 if ($result->is_changed()) { ... }
408 Arguments: none
410 Return Value: 0|1 or @columnnames
411 In list context returns a list of columns with uncommited changes, or
413 in scalar context returns a true value if there are uncommitted
414 changes.
415 is_column_changed
417 if ($result->is_column_changed('col')) { ... }
418 Arguments: $columname
420 Return Value: 0|1
421 Returns a true value if the column has uncommitted changes.
423 result_source
425 my $resultsource = $result->result_source;
426 Arguments: $result_source?
428 Return Value: $result_source
429 Accessor to the DBIx::Class::ResultSource this object was created from.
431 register_column
433 $column_info = { .... };
434 $class->register_column($column_name, $column_info);
435 Arguments: $columnname, \%columninfo
437 Return Value: not defined
438 Registers a column on the class. If the column_info has an 'accessor'
440 key, creates an accessor named after the value if defined; if there is
441 no such key, creates an accessor with the same name as the column
442 The column_info attributes are described in "add_columns" in
444 DBIx::Class::ResultSource
445 get_from_storage
447 my $copy = $result->get_from_storage($attrs)
448 Arguments: \%attrs
450 Return Value: A Result object
451 Fetches a fresh copy of the Result object from the database and returns
453 it. Throws an exception if a proper WHERE clause identifying the
454 database row can not be constructed (i.e. if the original object does
455 not contain its entire
456 primary key ). If passed the \%attrs argument, will first apply these
457 attributes to the resultset used to find the row.
458 This copy can then be used to compare to an existing result object, to
460 determine if any changes have been made in the database since it was
461 created.
462 To just update your Result object with any latest changes from the
464 database, use "discard_changes" instead.
465 The \%attrs argument should be compatible with "ATTRIBUTES" in
467 DBIx::Class::ResultSet.
468 discard_changes
470 $result->discard_changes
471 Arguments: none or $attrs
473 Return Value: self (updates object in-place)
474 Re-selects the row from the database, losing any changes that had been
476 made. Throws an exception if a proper "WHERE" clause identifying the
477 database row can not be constructed (i.e. if the original object does
478 not contain its entire primary key).
479 This method can also be used to refresh from storage, retrieving any
481 changes made since the row was last read from storage.
482 $attrs, if supplied, is expected to be a hashref of attributes suitable
484 for passing as the second argument to "$resultset->search($cond,
485 $attrs)";
486 Note: If you are using DBIx::Class::Storage::DBI::Replicated as your
488 storage, a default of "{ force_pool => 'master' }"
489 is automatically set for you. Prior to "DBIx::Class 0.08109" (before
490 2010) one would have been required to explicitly wrap the entire
491 operation in a transaction to guarantee that up-to-date results are
492 read from the master database.
493 throw_exception
495 See "throw_exception" in DBIx::Class::Schema.
496 id
498 my @pk = $result->id;
499 Arguments: none
501 Returns: A list of primary key values
502 Returns the primary key(s) for a row. Can't be called as a class
504 method. Actually implemented in DBIx::Class::PK
505
507 Check the list of additional DBIC resources.
508
510 This module is free software copyright by the DBIx::Class (DBIC)
511 authors. You can redistribute it and/or modify it under the same terms
512 as the DBIx::Class library.
513perl v5.30.1 2020-01-29 DBIx::Class::Row(3)