1DBIx::Class::Row(3)   User Contributed Perl Documentation  DBIx::Class::Row(3)
2
3
4

NAME

6       DBIx::Class::Row - Basic row methods
7

SYNOPSIS

DESCRIPTION

10       This class is responsible for defining and doing basic operations on
11       rows derived from DBIx::Class::ResultSource objects.
12
13       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

NOTE

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
23       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

METHODS

34   new
35         my $result = My::Class->new(\%attrs);
36
37         my $result = $schema->resultset('MySource')->new(\%colsandvalues);
38
39       Arguments: \%attrs or \%colsandvalues
40       Return Value: $result
41
42       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
46       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
51       $attrs is a hashref of column name, value data. It can also contain
52       some other attributes such as the "result_source".
53
54       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
60       For a more involved explanation, see "create" in
61       DBIx::Class::ResultSet.
62
63       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
72        CAVEAT:
73
74        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
80   $column_accessor
81         # Each pair does the same thing
82
83         # (un-inflated, regular column)
84         my $val = $result->get_column('first_name');
85         my $val = $result->first_name;
86
87         $result->set_column('first_name' => $val);
88         $result->first_name($val);
89
90         # (inflated column via DBIx::Class::InflateColumn::DateTime)
91         my $val = $result->get_inflated_column('last_modified');
92         my $val = $result->last_modified;
93
94         $result->set_inflated_column('last_modified' => $val);
95         $result->last_modified($val);
96
97       Arguments: $value?
98       Return Value: $value
99
100       A column accessor method is created for each column, which is used for
101       getting/setting the value for that column.
102
103       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
108   insert
109         $result->insert;
110
111       Arguments: none
112       Return Value: $result
113
114       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
119       To fetch an uninserted result object, call new_result on a resultset.
120
121       This will also insert any uninserted, related objects held inside this
122       one, see "create" in DBIx::Class::ResultSet for more details.
123
124   in_storage
125         $result->in_storage; # Get value
126         $result->in_storage(1); # Set value
127
128       Arguments: none or 1|0
129       Return Value: 1|0
130
131       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
135       Creating a result object using "new_result" in DBIx::Class::ResultSet,
136       or calling "delete" on one, sets it to false.
137
138   update
139         $result->update(\%columns?)
140
141       Arguments: none or a hashref
142       Return Value: $result
143
144       Throws an exception if the result object is not yet in the database,
145       according to "in_storage". Returns the object itself.
146
147       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
153       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
160       If the values passed or any of the column values set on the object
161       contain scalar references, e.g.:
162
163         $result->last_modified(\'NOW()')->update();
164         # OR
165         $result->update({ last_modified => \'NOW()' });
166
167       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
172         $result->update()->discard_changes();
173
174       To determine before calling this method, which column values have
175       changed and will be updated, call "get_dirty_columns".
176
177       To check if any columns will be updated, call "is_changed".
178
179       To force a column to be updated, call "make_column_dirty" before this
180       method.
181
182   delete
183         $result->delete
184
185       Arguments: none
186       Return Value: $result
187
188       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
193       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
197       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
205       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
213       See also "delete" in DBIx::Class::ResultSet.
214
215   get_column
216         my $val = $result->get_column($col);
217
218       Arguments: $columnname
219       Return Value: The value of the column
220
221       Throws an exception if the column name given doesn't exist according to
222       has_column.
223
224       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
227       If an inflated value has been set, it will be deflated and returned.
228
229       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
234       To retrieve all loaded column values as a hash, use "get_columns".
235
236   has_column_loaded
237         if ( $result->has_column_loaded($col) ) {
238            print "$col has been loaded from db";
239         }
240
241       Arguments: $columnname
242       Return Value: 0|1
243
244       Returns a true value if the column value has been loaded from the
245       database (or set locally).
246
247   get_columns
248         my %data = $result->get_columns;
249
250       Arguments: none
251       Return Value: A hash of columnname, value pairs.
252
253       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
256       See "get_inflated_columns" to get the inflated values.
257
258   get_dirty_columns
259         my %data = $result->get_dirty_columns;
260
261       Arguments: none
262       Return Value: A hash of column, value pairs
263
264       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
267       See "get_columns" to fetch all column/value pairs.
268
269   make_column_dirty
270         $result->make_column_dirty($col)
271
272       Arguments: $columnname
273       Return Value: not defined
274
275       Throws an exception if the column does not exist.
276
277       Marks a column as having been changed regardless of whether it has
278       really changed.
279
280   get_inflated_columns
281         my %inflated_data = $obj->get_inflated_columns;
282
283       Arguments: none
284       Return Value: A hash of column, object|value pairs
285
286       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
289       See "get_columns" to get the uninflated values.
290
291       See DBIx::Class::InflateColumn for how to setup inflation.
292
293   set_column
294         $result->set_column($col => $val);
295
296       Arguments: $columnname, $value
297       Return Value: $value
298
299       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
302       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
308   set_columns
309         $result->set_columns({ $col => $val, ... });
310
311       Arguments: \%columndata
312       Return Value: $result
313
314       Sets multiple column, raw value pairs at once.
315
316       Works as "set_column".
317
318   set_inflated_columns
319         $result->set_inflated_columns({ $col => $val, $rel_name => $obj, ... });
320
321       Arguments: \%columndata
322       Return Value: $result
323
324       Sets more than one column value at once. Any inflated values are
325       deflated and the raw values stored.
326
327       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
332       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
336       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
341       See also "set_from_related" in DBIx::Class::Relationship::Base.
342
343   copy
344         my $copy = $orig->copy({ change => $to, ... });
345
346       Arguments: \%replacementdata
347       Return Value: $result copy
348
349       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
356       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
361   store_column
362         $result->store_column($col => $val);
363
364       Arguments: $columnname, $value
365       Return Value: The value sent to storage
366
367       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
370       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
373   inflate_result
374         Class->inflate_result($result_source, \%me, \%prefetch?)
375
376       Arguments: $result_source, \%columndata, \%prefetcheddata
377       Return Value: $result
378
379       All DBIx::Class::ResultSet methods that retrieve data from the database
380       and turn it into result objects call this method.
381
382       Extend this method in your Result classes to hook into this process,
383       for example to rebless the result into a different class.
384
385       Reblessing can also be done more easily by setting "result_class" in
386       your Result class. See "result_class" in DBIx::Class::ResultSource.
387
388       Different types of results can also be created from a particular
389       DBIx::Class::ResultSet, see "result_class" in DBIx::Class::ResultSet.
390
391   update_or_insert
392         $result->update_or_insert
393
394       Arguments: none
395       Return Value: Result of update or insert operation
396
397       "update"s the object if it's already in the database, according to
398       "in_storage", else "insert"s it.
399
400   insert_or_update
401         $obj->insert_or_update
402
403       Alias for "update_or_insert"
404
405   is_changed
406         my @changed_col_names = $result->is_changed();
407         if ($result->is_changed()) { ... }
408
409       Arguments: none
410       Return Value: 0|1 or @columnnames
411
412       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
416   is_column_changed
417         if ($result->is_column_changed('col')) { ... }
418
419       Arguments: $columname
420       Return Value: 0|1
421
422       Returns a true value if the column has uncommitted changes.
423
424   result_source
425         my $resultsource = $result->result_source;
426
427       Arguments: $result_source?
428       Return Value: $result_source
429
430       Accessor to the DBIx::Class::ResultSource this object was created from.
431
432   register_column
433         $column_info = { .... };
434         $class->register_column($column_name, $column_info);
435
436       Arguments: $columnname, \%columninfo
437       Return Value: not defined
438
439       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
443       The column_info attributes are described in "add_columns" in
444       DBIx::Class::ResultSource
445
446   get_from_storage
447         my $copy = $result->get_from_storage($attrs)
448
449       Arguments: \%attrs
450       Return Value: A Result object
451
452       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
459       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
463       To just update your Result object with any latest changes from the
464       database, use "discard_changes" instead.
465
466       The \%attrs argument should be compatible with "ATTRIBUTES" in
467       DBIx::Class::ResultSet.
468
469   discard_changes
470         $result->discard_changes
471
472       Arguments: none or $attrs
473       Return Value: self (updates object in-place)
474
475       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
480       This method can also be used to refresh from storage, retrieving any
481       changes made since the row was last read from storage.
482
483       $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
487       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
494   throw_exception
495       See "throw_exception" in DBIx::Class::Schema.
496
497   id
498         my @pk = $result->id;
499
500       Arguments: none
501       Returns: A list of primary key values
502
503       Returns the primary key(s) for a row. Can't be called as a class
504       method.  Actually implemented in DBIx::Class::PK
505

FURTHER QUESTIONS?

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.
513
514
515
516perl v5.30.0                      2019-07-26               DBIx::Class::Row(3)
Impressum