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 Row objects are returned from DBIx::Class::ResultSets using the create,
14 find, next and all methods, as well as invocations of 'single' (
15 belongs_to, has_one or might_have) relationship accessors of
16 DBIx::Class::Row objects.
17
19 new
20 my $row = My::Class->new(\%attrs);
21 my $row = $schema->resultset('MySource')->new(\%colsandvalues);
23 Arguments: \%attrs or \%colsandvalues
25 Returns: A Row object
26 While you can create a new row object by calling "new" directly on this
28 class, you are better off calling it on a DBIx::Class::ResultSet
29 object.
30 When calling it directly, you will not get a complete, usable row
32 object until you pass or set the "source_handle" attribute, to a
33 DBIx::Class::ResultSource instance that is attached to a
34 DBIx::Class::Schema with a valid connection.
35 $attrs is a hashref of column name, value data. It can also contain
37 some other attributes such as the "source_handle".
38 Passing an object, or an arrayref of objects as a value will call
40 "set_from_related" in DBIx::Class::Relationship::Base for you. When
41 passed a hashref or an arrayref of hashrefs as the value, these will be
42 turned into objects via new_related, and treated as if you had passed
43 objects.
44 For a more involved explanation, see "create" in
46 DBIx::Class::ResultSet.
47 Please note that if a value is not passed to new, no value will be sent
49 in the SQL INSERT call, and the column will therefore assume whatever
50 default value was specified in your database. While DBIC will retrieve
51 the value of autoincrement columns, it will never make an explicit
52 database trip to retrieve default values assigned by the RDBMS. You can
53 explicitly request that all values be fetched back from the database by
54 calling "discard_changes", or you can supply an explicit "undef" to
55 columns with NULL as the default, and save yourself a SELECT.
56 CAVEAT:
58 The behavior described above will backfire if you use a foreign key column
60 with a database-defined default. If you call the relationship accessor on
61 an object that doesn't have a set value for the FK column, DBIC will throw
62 an exception, as it has no way of knowing the PK of the related object (if
63 there is one).
64 insert
66 $row->insert;
67 Arguments: none
69 Returns: The Row object
70 Inserts an object previously created by "new" into the database if it
72 isn't already in there. Returns the object itself. Requires the
73 object's result source to be set, or the class to have a
74 result_source_instance method. To insert an entirely new row into the
75 database, use "create" (see "create" in DBIx::Class::ResultSet).
76 To fetch an uninserted row object, call new on a resultset.
78 This will also insert any uninserted, related objects held inside this
80 one, see "create" in DBIx::Class::ResultSet for more details.
81 in_storage
83 $row->in_storage; # Get value
84 $row->in_storage(1); # Set value
85 Arguments: none or 1|0
87 Returns: 1|0
88 Indicates whether the object exists as a row in the database or not.
90 This is set to true when "find" in DBIx::Class::ResultSet, "create" in
91 DBIx::Class::ResultSet or "insert" in DBIx::Class::ResultSet are used.
92 Creating a row object using "new" in DBIx::Class::ResultSet, or calling
94 "delete" on one, sets it to false.
95 update
97 $row->update(\%columns?)
98 Arguments: none or a hashref
100 Returns: The Row object
101 Throws an exception if the row object is not yet in the database,
103 according to "in_storage".
104 This method issues an SQL UPDATE query to commit any changes to the
106 object to the database if required.
107 Also takes an optional hashref of "column_name => value>" pairs to
109 update on the object first. Be aware that the hashref will be passed to
110 "set_inflated_columns", which might edit it in place, so don't rely on
111 it being the same after a call to "update". If you need to preserve
112 the hashref, it is sufficient to pass a shallow copy to "update", e.g.
113 ( { %{ $href } } )
114 If the values passed or any of the column values set on the object
116 contain scalar references, e.g.:
117 $row->last_modified(\'NOW()');
119 # OR
120 $row->update({ last_modified => \'NOW()' });
121 The update will pass the values verbatim into SQL. (See SQL::Abstract
123 docs). The values in your Row object will NOT change as a result of
124 the update call, if you want the object to be updated with the actual
125 values from the database, call "discard_changes" after the update.
126 $row->update()->discard_changes();
128 To determine before calling this method, which column values have
130 changed and will be updated, call "get_dirty_columns".
131 To check if any columns will be updated, call "is_changed".
133 To force a column to be updated, call "make_column_dirty" before this
135 method.
136 delete
138 $row->delete
139 Arguments: none
141 Returns: The Row object
142 Throws an exception if the object is not in the database according to
144 "in_storage". Runs an SQL DELETE statement using the primary key values
145 to locate the row.
146 The object is still perfectly usable, but "in_storage" will now return
148 0 and the object must be reinserted using "insert" before it can be
149 used to "update" the row again.
150 If you delete an object in a class with a "has_many" relationship, an
152 attempt is made to delete all the related objects as well. To turn this
153 behaviour off, pass "cascade_delete => 0" in the $attr hashref of the
154 relationship, see DBIx::Class::Relationship. Any database-level cascade
155 or restrict will take precedence over a DBIx-Class-based cascading
156 delete, since DBIx-Class deletes the main row first and only then
157 attempts to delete any remaining related rows.
158 If you delete an object within a txn_do() (see "txn_do" in
160 DBIx::Class::Storage) and the transaction subsequently fails, the row
161 object will remain marked as not being in storage. If you know for a
162 fact that the object is still in storage (i.e. by inspecting the cause
163 of the transaction's failure), you can use "$obj->in_storage(1)" to
164 restore consistency between the object and the database. This would
165 allow a subsequent "$obj->delete" to work as expected.
166 See also "delete" in DBIx::Class::ResultSet.
168 get_column
170 my $val = $row->get_column($col);
171 Arguments: $columnname
173 Returns: The value of the column
174 Throws an exception if the column name given doesn't exist according to
176 "has_column".
177 Returns a raw column value from the row object, if it has already been
179 fetched from the database or set by an accessor.
180 If an inflated value has been set, it will be deflated and returned.
182 Note that if you used the "columns" or the "select/as" search
184 attributes on the resultset from which $row was derived, and did not
185 include $columnname in the list, this method will return "undef" even
186 if the database contains some value.
187 To retrieve all loaded column values as a hash, use "get_columns".
189 has_column_loaded
191 if ( $row->has_column_loaded($col) ) {
192 print "$col has been loaded from db";
193 }
194 Arguments: $columnname
196 Returns: 0|1
197 Returns a true value if the column value has been loaded from the
199 database (or set locally).
200 get_columns
202 my %data = $row->get_columns;
203 Arguments: none
205 Returns: A hash of columnname, value pairs.
206 Returns all loaded column data as a hash, containing raw values. To get
208 just one value for a particular column, use "get_column".
209 See "get_inflated_columns" to get the inflated values.
211 get_dirty_columns
213 my %data = $row->get_dirty_columns;
214 Arguments: none
216 Returns: A hash of column, value pairs
217 Only returns the column, value pairs for those columns that have been
219 changed on this object since the last "update" or "insert" call.
220 See "get_columns" to fetch all column/value pairs.
222 make_column_dirty
224 $row->make_column_dirty($col)
225 Arguments: $columnname
227 Returns: undefined
228 Throws an exception if the column does not exist.
230 Marks a column as having been changed regardless of whether it has
232 really changed.
233 get_inflated_columns
235 my %inflated_data = $obj->get_inflated_columns;
236 Arguments: none
238 Returns: A hash of column, object|value pairs
239 Returns a hash of all column keys and associated values. Values for any
241 columns set to use inflation will be inflated and returns as objects.
242 See "get_columns" to get the uninflated values.
244 See DBIx::Class::InflateColumn for how to setup inflation.
246 set_column
248 $row->set_column($col => $val);
249 Arguments: $columnname, $value
251 Returns: $value
252 Sets a raw column value. If the new value is different from the old
254 one, the column is marked as dirty for when you next call "update".
255 If passed an object or reference as a value, this method will happily
257 attempt to store it, and a later "insert" or "update" will try and
258 stringify/numify as appropriate. To set an object to be deflated
259 instead, see "set_inflated_columns".
260 set_columns
262 $row->set_columns({ $col => $val, ... });
263 Arguments: \%columndata
265 Returns: The Row object
266 Sets multiple column, raw value pairs at once.
268 Works as "set_column".
270 set_inflated_columns
272 $row->set_inflated_columns({ $col => $val, $relname => $obj, ... });
273 Arguments: \%columndata
275 Returns: The Row object
276 Sets more than one column value at once. Any inflated values are
278 deflated and the raw values stored.
279 Any related values passed as Row objects, using the relation name as a
281 key, are reduced to the appropriate foreign key values and stored. If
282 instead of related row objects, a hashref of column, value data is
283 passed, will create the related object first then store.
284 Will even accept arrayrefs of data as a value to a "has_many" in
286 DBIx::Class::Relationship key, and create the related objects if
287 necessary.
288 Be aware that the input hashref might be edited in place, so don't rely
290 on it being the same after a call to "set_inflated_columns". If you
291 need to preserve the hashref, it is sufficient to pass a shallow copy
292 to "set_inflated_columns", e.g. ( { %{ $href } } )
293 See also "set_from_related" in DBIx::Class::Relationship::Base.
295 copy
297 my $copy = $orig->copy({ change => $to, ... });
298 Arguments: \%replacementdata
300 Returns: The Row object copy
301 Inserts a new row into the database, as a copy of the original object.
303 If a hashref of replacement data is supplied, these will take
304 precedence over data in the original. Also any columns which have the
305 column info attribute "is_auto_increment => 1" are explicitly removed
306 before the copy, so that the database can insert its own
307 autoincremented values into the new object.
308 Relationships will be followed by the copy procedure only if the
310 relationship specifies a true value for its cascade_copy attribute.
311 "cascade_copy" is set by default on "has_many" relationships and unset
312 on all others.
313 store_column
315 $row->store_column($col => $val);
316 Arguments: $columnname, $value
318 Returns: The value sent to storage
319 Set a raw value for a column without marking it as changed. This method
321 is used internally by "set_column" which you should probably be using.
322 This is the lowest level at which data is set on a row object, extend
324 this method to catch all data setting methods.
325 inflate_result
327 Class->inflate_result($result_source, \%me, \%prefetch?)
328 Arguments: $result_source, \%columndata, \%prefetcheddata
330 Returns: A Row object
331 All DBIx::Class::ResultSet methods that retrieve data from the database
333 and turn it into row objects call this method.
334 Extend this method in your Result classes to hook into this process,
336 for example to rebless the result into a different class.
337 Reblessing can also be done more easily by setting "result_class" in
339 your Result class. See "result_class" in DBIx::Class::ResultSource.
340 Different types of results can also be created from a particular
342 DBIx::Class::ResultSet, see "result_class" in DBIx::Class::ResultSet.
343 update_or_insert
345 $row->update_or_insert
346 Arguments: none
348 Returns: Result of update or insert operation
349 "Update"s the object if it's already in the database, according to
351 "in_storage", else "insert"s it.
352 insert_or_update
354 $obj->insert_or_update
355 Alias for "update_or_insert"
357 is_changed
359 my @changed_col_names = $row->is_changed();
360 if ($row->is_changed()) { ... }
361 Arguments: none
363 Returns: 0|1 or @columnnames
364 In list context returns a list of columns with uncommited changes, or
366 in scalar context returns a true value if there are uncommitted
367 changes.
368 is_column_changed
370 if ($row->is_column_changed('col')) { ... }
371 Arguments: $columname
373 Returns: 0|1
374 Returns a true value if the column has uncommitted changes.
376 result_source
378 my $resultsource = $row->result_source;
379 Arguments: none
381 Returns: a ResultSource instance
382 Accessor to the DBIx::Class::ResultSource this object was created from.
384 register_column
386 $column_info = { .... };
387 $class->register_column($column_name, $column_info);
388 Arguments: $columnname, \%columninfo
390 Returns: undefined
391 Registers a column on the class. If the column_info has an 'accessor'
393 key, creates an accessor named after the value if defined; if there is
394 no such key, creates an accessor with the same name as the column
395 The column_info attributes are described in "add_columns" in
397 DBIx::Class::ResultSource
398 get_from_storage
400 my $copy = $row->get_from_storage($attrs)
401 Arguments: \%attrs
403 Returns: A Row object
404 Fetches a fresh copy of the Row object from the database and returns
406 it.
407 If passed the \%attrs argument, will first apply these attributes to
409 the resultset used to find the row.
410 This copy can then be used to compare to an existing row object, to
412 determine if any changes have been made in the database since it was
413 created.
414 To just update your Row object with any latest changes from the
416 database, use "discard_changes" instead.
417 The \%attrs argument should be compatible with "ATTRIBUTES" in
419 DBIx::Class::ResultSet.
420 discard_changes ($attrs)
422 Re-selects the row from the database, losing any changes that had been
423 made.
424 This method can also be used to refresh from storage, retrieving any
426 changes made since the row was last read from storage.
427 $attrs is expected to be a hashref of attributes suitable for passing
429 as the second argument to $resultset->search($cond, $attrs);
430 throw_exception
432 See "throw_exception" in DBIx::Class::Schema.
433 id
435 my @pk = $row->id;
436 Arguments: none
438 Returns: A list of primary key values
439 Returns the primary key(s) for a row. Can't be called as a class
441 method. Actually implemented in DBIx::Class::PK
442 discard_changes
444 $row->discard_changes
445 Arguments: none
447 Returns: nothing (updates object in-place)
448 Retrieves and sets the row object data from the database, losing any
450 local changes made.
451 This method can also be used to refresh from storage, retrieving any
453 changes made since the row was last read from storage. Actually
454 implemented in DBIx::Class::PK
455 Note: If you are using DBIx::Class::Storage::DBI::Replicated as your
457 storage, please kept in mind that if you "discard_changes" on a row
458 that you just updated or created, you should wrap the entire bit inside
459 a transaction. Otherwise you run the risk that you insert or update to
460 the master database but read from a replicant database that has not yet
461 been updated from the master. This will result in unexpected results.
462
464 Matt S. Trout <mst@shadowcatsystems.co.uk>
465
467 You may distribute this code under the same terms as Perl itself.
468perl v5.12.0 2010-05-12 DBIx::Class::Row(3)