From: Jess Robinson <castaway@desert-island.me.uk>
Date: Mon, 12 Mar 2012 13:21:53 +0000 (+0000)
Subject: More tidy up of links and comments.
X-Git-Tag: v1.0^0
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=1ffc68a9c468afd446af2cd5cfe49467f586fe72;p=dbsrgits%2FDBIx-Class-Manual-SQLHackers.git

More tidy up of links and comments.
Moved TOC to SQLHackers.pod top layer
Added NOTES (of things that don't work yet ;)
---

diff --git a/NOTES.txt b/NOTES.txt
new file mode 100644
index 0000000..8bf578f
--- /dev/null
+++ b/NOTES.txt
@@ -0,0 +1,70 @@
+## Removed from UPDATE.pod:
+
+=head2 Update a row or rows using a column calculation
+
+    -- Yet another pointless example
+    UPDATE users
+    SET username = username || '.uk'
+    WHERE id = 1;
+
+=over
+
+=item 1. Create a Schema object representing the database you are working with:
+
+        my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db');
+
+=item 2. Call the B<find> method on the resultset for the L<ResultSource|DBIx::Class::ResultSource> you wish to fetch data from:
+
+        my $fred_user = $schema->resultset('User')->find({ id => 1 });
+
+The Row object has an B<update> method that will change the values on
+the object, and send an UPDATE query to the database.
+
+=item 3. Call the B<update> method, passing it a hashref of new data:
+
+# this won't yet work, DBIC for now mandates the [ {} => $value ] format, the simple \[ $sql, $value1, $value2 ] will start being recognized later on 
+# the only documentation we currently have is this, if you can turn it into a DBIC pod-patch it will be freaking awesome
+# https://github.com/dbsrgits/dbix-class/commit/0e773352
+        $fred_user->update({ username => \['username || ?', '.uk'] }); 
+
+^^ you never got around to this
+
+# the DBIC syntax is a tad different from te thing above (i.e. we no longer encourage 'dummy' crap)
+The \[ .. ] syntax here is described in L<SQL::Abstract>
+documentation, used for passing bind parameters.
+
+
+=back
+
+=head2 Update a row based on data in other tables
+
+    -- Slightly less pointless example
+    UPDATE posts 
+    SET title = user.username || title
+    JOIN users user ON user.id = posts.user_id;
+
+Joining two tables for an update is a similar sort of exercise to
+joining them for a select query and using data from both.
+
+=over
+
+=item 1. Create a Schema object representing the database you are working with:
+
+        my $schema = MyDatabase::Schema->connect('dbi:SQLite:my.db');
+
+=item 2. Call the B<search> method on the resultset for the L<ResultSource|DBIx::Class::ResultSource> you wish to update data in, joining to the second table:
+
+        my $posts = $schema->resultset('Post')->search(
+          {},
+          { join => 'user' }
+        );
+
+    The B<join> key takes as an argument a nested structure of one or more relation names (see L<DBIx::Class::Manual::SQLHackers::CREATE>).
+
+=item 3. Call the B<update> method on the resultset to run the UPDATE statement:
+
+        $posts->update({ 'me.title' => \[ 'user.username || me.title' ] });
+
+^^ I am 95% sure this won't actually work, please try it (ideally as a passing or failing test)
+
+=back
diff --git a/lib/DBIx/Class/Manual/SQLHackers/TOC.pod b/lib/DBIx/Class/Manual/SQLHackers.pod
similarity index 84%
rename from lib/DBIx/Class/Manual/SQLHackers/TOC.pod
rename to lib/DBIx/Class/Manual/SQLHackers.pod
index d54c492..2274b3b 100644
--- a/lib/DBIx/Class/Manual/SQLHackers/TOC.pod
+++ b/lib/DBIx/Class/Manual/SQLHackers.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-DBIx::Class::Manual::SQLHackers::TOC - DBIx::Class for SQL Hackers - TOC
+DBIx::Class::Manual::SQLHackers - DBIx::Class for SQL Hackers - Table of Contents
 
 =over
 
@@ -26,7 +26,7 @@ Jess Robinson <castaway@desert-island.me.uk>, L<http://metacpan.org/author/JROBI
 
 =head1 COPYRIGHT
 
-Copyright (c) 2010 - 2011 the L</AUTHOR>
+Copyright (c) 2010 - 2012 the L</AUTHOR>
 
 =head1 LICENSE
 
diff --git a/lib/DBIx/Class/Manual/SQLHackers/DELETE.pod b/lib/DBIx/Class/Manual/SQLHackers/DELETE.pod
index 151b5fa..9d5761a 100644
--- a/lib/DBIx/Class/Manual/SQLHackers/DELETE.pod
+++ b/lib/DBIx/Class/Manual/SQLHackers/DELETE.pod
@@ -53,7 +53,7 @@ variable, if it is not needed later:
     $schema->resultset('User')->find({ id => 1 })->delete;
 
 In the first variant, the $fred_user row object will still contain the
-last known contents of Fred's data. A call to L<$fred_user->in_storage|DBIx::Class::Row/in_storage> will return
+last known contents of Fred's data. A call to $fred_user->L<in_storage|DBIx::Class::Row/in_storage> will return
 false (0), showing that the row object is no longer connected to a actual
 database row.
 
diff --git a/lib/DBIx/Class/Manual/SQLHackers/SELECT.pod b/lib/DBIx/Class/Manual/SQLHackers/SELECT.pod
index 6aa311f..44a0513 100644
--- a/lib/DBIx/Class/Manual/SQLHackers/SELECT.pod
+++ b/lib/DBIx/Class/Manual/SQLHackers/SELECT.pod
@@ -440,7 +440,6 @@ Here "posts" refers to the name of the L<Relationship|DBIx::Class::Relationship>
 The results will be filtered by the HAVING clause.
 
 =head2 SELECT with DISTINCT
-^^ you may or may not want to mention the distinct => 1 flag, which is an automatic "group by the selection" thing. 
 
     SELECT DISTINCT(posts.title)
     FROM posts