Merge 'trunk' into 'replication_dedux'

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Manual / FAQ.pod

diff --git a/lib/DBIx/Class/Manual/FAQ.pod b/lib/DBIx/Class/Manual/FAQ.pod
index 2ff72ee..8fcc313 100644 (file)
--- a/lib/DBIx/Class/Manual/FAQ.pod
+++ b/lib/DBIx/Class/Manual/FAQ.pod
@@ -232,6 +232,25 @@ and not:
  my $interval = "now() - interval '12 hours'";
  ->search({last_attempt => { '<' => \$interval } })
 
+=item .. search with an SQL function on the left hand side?
+
+To use an SQL function on the left hand side of a comparison:
+
+ ->search({}, { where => \'YEAR(date_of_birth)=1979' });
+
+=begin hidden
+
+(When the bind arg ordering bug is fixed, the previous example can be
+replaced with the following.)
+
+ ->search({}, { where => \'YEAR(date_of_birth)=?', bind => [ 1979 ] });
+
+=end hidden
+
+Or, if you have quoting off:
+
+ ->search({ 'YEAR(date_of_birth' => 1979 });
+
 =item .. find more help on constructing searches?
 
 Behind the scenes, DBIx::Class uses L<SQL::Abstract> to help construct
@@ -259,7 +278,7 @@ L<Cookbook|DBIx::Class::Manual::Cookbook> for details.
 
 In your table schema class, create a "private" column accessor with:
 
-  __PACKAGE__->add_columns(my_common => { accessor => '_hidden_my_column' });
+  __PACKAGE__->add_columns(my_column => { accessor => '_hidden_my_column' });
 
 Then, in the same class, implement a subroutine called "my_column" that
 fetches the real value and does the formatting you want.
@@ -285,6 +304,18 @@ Why slice instead of L<DBIx::Class::ResultSet/first> or L<DBIx::Class::ResultSet
 If supported by the database, slice will use LIMIT/OFFSET to hint to the database that we
 really only need one row. This can result in a significant speed improvement.
 
+=item .. refresh a row from storage?
+
+Use L<DBIx::Class::PK/discard_changes>.
+
+  $row->discard_changes
+
+Discarding changes and refreshing from storage are two sides fo the same coin.  When you
+want to discard your local changes, just re-fetch the row from storage.  When you want
+to get a new, fresh copy of the row, just re-fetch the row from storage.
+L<DBIx::Class::PK/discard_changes> does just that by re-fetching the row from storage
+using the row's primary key.
+
 =back
 
 =head2 Inserting and updating data
@@ -307,7 +338,7 @@ primary key field from the sequence. To help PK::Auto find your
 inserted key, you can tell it the name of the sequence in the
 C<column_info> supplied with C<add_columns>.
 
- ->add_columns({ id => { sequence => 'mysequence' } });
+ ->add_columns({ id => { sequence => 'mysequence', auto_nextval => 1 } });
 
 =item .. insert many rows of data efficiently?
 
@@ -326,6 +357,19 @@ scalar reference:
 
  ->update({ somecolumn => \'othercolumn' })
 
+But note that when using a scalar reference the column in the database
+will be updated but when you read the value from the object with e.g.
+ 
+ ->somecolumn()
+ 
+you still get back the scalar reference to the string, B<not> the new
+value in the database. To get that you must refresh the row from storage
+using C<discard_changes()>. Or chain your function calls like this:
+
+  ->update->discard_changes
+ 
+ to update the database and refresh the object in one step.
+ 
 =item .. store JSON/YAML in a column and have it deflate/inflate automatically?
 
 You can use L<DBIx::Class::InflateColumn> to accomplish YAML/JSON storage transparently.
@@ -376,7 +420,7 @@ to work around this issue.
 
 =item See the SQL statements my code is producing?
 
-Turn on debugging! See L<DBIx::Class::Storage::DBI> for details of how
+Turn on debugging! See L<DBIx::Class::Storage> for details of how
 to turn on debugging in the environment, pass your own filehandle to
 save debug to, or create your own callback.
 
@@ -388,6 +432,17 @@ is executed. You can create further resultset refinements by calling
 search again or relationship accessors. The SQL query is only run when
 you ask the resultset for an actual row object.
 
+=item How do I deal with tables that lack a primary key?
+
+If your table lacks a primary key, DBIx::Class can't work out which row
+it should operate on, for example to delete or update.  However, a
+UNIQUE constraint on one or more columns allows DBIx::Class to uniquely
+identify the row, so you can tell L<DBIx::Class::ResultSource> these
+columns act as a primary key, even if they don't from the database's
+point of view:
+
+ $resultset->set_primary_key(@column);
+
 =back
 
 =head2 Notes for CDBI users
@@ -398,6 +453,6 @@ you ask the resultset for an actual row object.
 particular column or group of columns (a-la cdbi Stringfy column
 group, or stringify_self method) ?
 
-See L<Cookbook/Stringification>
+See L<DBIx::Class::Manual::Cookbook/Stringification>
 
 =back