[Bast-commits] r9615 - in SQL-Abstract/1.x/trunk: . lib/SQL

[nigel at dev.catalyst.perl.org]

Author: nigel
Date: 2010-06-29 15:09:36 +0100 (Tue, 29 Jun 2010)
New Revision: 9615

Modified:
   SQL-Abstract/1.x/trunk/Changes
   SQL-Abstract/1.x/trunk/lib/SQL/Abstract.pm
Log:
Improvements to where clause docs for undef/NULL - tackling RT Bug #58490

Modified: SQL-Abstract/1.x/trunk/Changes
===================================================================
--- SQL-Abstract/1.x/trunk/Changes	2010-06-29 13:32:34 UTC (rev 9614)
+++ SQL-Abstract/1.x/trunk/Changes	2010-06-29 14:09:36 UTC (rev 9615)
@@ -1,5 +1,9 @@
 Revision history for SQL::Abstract
 
+revision 1.68  work in progress
+----------------------------
+    - Better documentation of undef/NULL in where clause
+
 revision 1.67  2010-05-31 14:21 (UTC)
 ----------------------------
     - Fix SQL::Test failure when first chunk is an unrecognized

Modified: SQL-Abstract/1.x/trunk/lib/SQL/Abstract.pm
===================================================================
--- SQL-Abstract/1.x/trunk/lib/SQL/Abstract.pm	2010-06-29 13:32:34 UTC (rev 9614)
+++ SQL-Abstract/1.x/trunk/lib/SQL/Abstract.pm	2010-06-29 14:09:36 UTC (rev 9615)
@@ -1900,6 +1900,20 @@
 A field associated to an empty arrayref will be considered a
 logical false and will generate 0=1.
 
+=head2 Tests for NULL values
+
+If the value part is C<undef> then this is converted to SQL <IS NULL>
+
+    my %where  = (
+        user   => 'nwiger',
+        status => undef,
+    );
+
+becomes:
+
+    $stmt = "WHERE user = ? AND status IS NULL";
+    @bind = ('nwiger');
+
 =head2 Specific comparison operators
 
 If you want to specify a different type of operator for your comparison,
@@ -2261,7 +2275,18 @@
     $stmt = "WHERE priority < ? AND is_ready";
     @bind = ('2');
 
+Literal SQL is also the only way to compare 2 columns to one another:
 
+    my %where = (
+        priority => { '<', 2 },
+        requestor => \'= submittor'
+    );
+
+which creates:
+
+    $stmt = "WHERE priority < ? AND requestor = submitter";
+    @bind = ('2');
+
 =head2 Literal SQL with placeholders and bind values (subqueries)
 
 If the literal SQL to be inserted has placeholders and bind values,
@@ -2584,6 +2609,12 @@
 around. On subsequent queries, simply use the C<values> function provided
 by this module to return your values in the correct order.
 
+However this depends on the values having the same type - if, for
+example, the values of a where clause may either have values
+(resulting in sql of the form C<column = ?> with a single bind
+value), or alternatively the values might be C<undef> (resulting in
+sql of the form C<column IS NULL> with no bind value) then the
+caching technique suggested will not work.
 
 =head1 FORMBUILDER