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
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
173         $result->update()->discard_changes();
174
175       To determine before calling this method, which column values have
176       changed and will be updated, call "get_dirty_columns".
177
178       To check if any columns will be updated, call "is_changed".
179
180       To force a column to be updated, call "make_column_dirty" before this
181       method.
182
183   delete
184         $result->delete
185
186       Arguments: none
187       Return Value: $result
188
189       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
194       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
198       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
206       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
214       See also "delete" in DBIx::Class::ResultSet.
215
216   get_column
217         my $val = $result->get_column($col);
218
219       Arguments: $columnname
220       Return Value: The value of the column
221
222       Throws an exception if the column name given doesn't exist according to
223       has_column.
224
225       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
228       If an inflated value has been set, it will be deflated and returned.
229
230       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
235       To retrieve all loaded column values as a hash, use "get_columns".
236
237   has_column_loaded
238         if ( $result->has_column_loaded($col) ) {
239            print "$col has been loaded from db";
240         }
241
242       Arguments: $columnname
243       Return Value: 0|1
244
245       Returns a true value if the column value has been loaded from the
246       database (or set locally).
247
248   get_columns
249         my %data = $result->get_columns;
250
251       Arguments: none
252       Return Value: A hash of columnname, value pairs.
253
254       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
257       See "get_inflated_columns" to get the inflated values.
258
259   get_dirty_columns
260         my %data = $result->get_dirty_columns;
261
262       Arguments: none
263       Return Value: A hash of column, value pairs
264
265       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
268       See "get_columns" to fetch all column/value pairs.
269
270   make_column_dirty
271         $result->make_column_dirty($col)
272
273       Arguments: $columnname
274       Return Value: not defined
275
276       Throws an exception if the column does not exist.
277
278       Marks a column as having been changed regardless of whether it has
279       really changed.
280
281   get_inflated_columns
282         my %inflated_data = $obj->get_inflated_columns;
283
284       Arguments: none
285       Return Value: A hash of column, object|value pairs
286
287       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
290       See "get_columns" to get the uninflated values.
291
292       See DBIx::Class::InflateColumn for how to setup inflation.
293
294   set_column
295         $result->set_column($col => $val);
296
297       Arguments: $columnname, $value
298       Return Value: $value
299
300       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
303       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
309   set_columns
310         $result->set_columns({ $col => $val, ... });
311
312       Arguments: \%columndata
313       Return Value: $result
314
315       Sets multiple column, raw value pairs at once.
316
317       Works as "set_column".
318
319   set_inflated_columns
320         $result->set_inflated_columns({ $col => $val, $rel_name => $obj, ... });
321
322       Arguments: \%columndata
323       Return Value: $result
324
325       Sets more than one column value at once. Any inflated values are
326       deflated and the raw values stored.
327
328       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
333       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
337       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
342       See also "set_from_related" in DBIx::Class::Relationship::Base.
343
344   copy
345         my $copy = $orig->copy({ change => $to, ... });
346
347       Arguments: \%replacementdata
348       Return Value: $result copy
349
350       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
357       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
362   store_column
363         $result->store_column($col => $val);
364
365       Arguments: $columnname, $value
366       Return Value: The value sent to storage
367
368       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
371       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
374   inflate_result
375         Class->inflate_result($result_source, \%me, \%prefetch?)
376
377       Arguments: $result_source, \%columndata, \%prefetcheddata
378       Return Value: $result
379
380       All DBIx::Class::ResultSet methods that retrieve data from the database
381       and turn it into result objects call this method.
382
383       Extend this method in your Result classes to hook into this process,
384       for example to rebless the result into a different class.
385
386       Reblessing can also be done more easily by setting "result_class" in
387       your Result class. See "result_class" in DBIx::Class::ResultSource.
388
389       Different types of results can also be created from a particular
390       DBIx::Class::ResultSet, see "result_class" in DBIx::Class::ResultSet.
391
392   update_or_insert
393         $result->update_or_insert
394
395       Arguments: none
396       Return Value: Result of update or insert operation
397
398       "update"s the object if it's already in the database, according to
399       "in_storage", else "insert"s it.
400
401   insert_or_update
402         $obj->insert_or_update
403
404       Alias for "update_or_insert"
405
406   is_changed
407         my @changed_col_names = $result->is_changed();
408         if ($result->is_changed()) { ... }
409
410       Arguments: none
411       Return Value: 0|1 or @columnnames
412
413       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
417   is_column_changed
418         if ($result->is_column_changed('col')) { ... }
419
420       Arguments: $columname
421       Return Value: 0|1
422
423       Returns a true value if the column has uncommitted changes.
424
425   result_source
426         my $resultsource = $result->result_source;
427
428       Arguments: $result_source?
429       Return Value: $result_source
430
431       Accessor to the DBIx::Class::ResultSource this object was created from.
432
433   register_column
434         $column_info = { .... };
435         $class->register_column($column_name, $column_info);
436
437       Arguments: $columnname, \%columninfo
438       Return Value: not defined
439
440       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
444       The column_info attributes are described in "add_columns" in
445       DBIx::Class::ResultSource
446
447   get_from_storage
448         my $copy = $result->get_from_storage($attrs)
449
450       Arguments: \%attrs
451       Return Value: A Result object
452
453       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
460       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
464       To just update your Result object with any latest changes from the
465       database, use "discard_changes" instead.
466
467       The \%attrs argument should be compatible with "ATTRIBUTES" in
468       DBIx::Class::ResultSet.
469
470   discard_changes
471         $result->discard_changes
472
473       Arguments: none or $attrs
474       Return Value: self (updates object in-place)
475
476       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
481       This method can also be used to refresh from storage, retrieving any
482       changes made since the row was last read from storage.
483
484       $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
488       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
495   throw_exception
496       See "throw_exception" in DBIx::Class::Schema.
497
498   id
499         my @pk = $result->id;
500
501       Arguments: none
502       Returns: A list of primary key values
503
504       Returns the primary key(s) for a row. Can't be called as a class
505       method.  Actually implemented in DBIx::Class::PK
506

FURTHER QUESTIONS?

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.
514
515
516
517perl v5.34.0                      2021-07-22               DBIx::Class::Row(3)
Impressum