This is not really used for anything (same code in DBI)

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Storage / DBI / MSSQL.pm

diff --git a/lib/DBIx/Class/Storage/DBI/MSSQL.pm b/lib/DBIx/Class/Storage/DBI/MSSQL.pm
index ea1269a..7896a86 100644 (file)
--- a/lib/DBIx/Class/Storage/DBI/MSSQL.pm
+++ b/lib/DBIx/Class/Storage/DBI/MSSQL.pm
@@ -3,7 +3,7 @@ package DBIx::Class::Storage::DBI::MSSQL;
 use strict;
 use warnings;
 
-use base qw/DBIx::Class::Storage::DBI::AmbiguousGlob DBIx::Class::Storage::DBI/;
+use base qw/DBIx::Class::Storage::DBI/;
 use mro 'c3';
 
 use List::Util();
@@ -192,8 +192,8 @@ sub _select_args_to_query {
   my $attrs = $_[3];
   if ( scalar $self->sql_maker->_order_by_chunks ($attrs->{order_by}) ) {
     $self->throw_exception(
-      'An ordered subquery encountered. Please see "Ordered Subqueries" in DBIx::Class::Storage::DBI::MSSQL
-    ') unless $attrs->{unsafe_subquery};
+      'An ordered subselect encountered - this is not safe! Please see "Ordered Subselects" in DBIx::Class::Storage::DBI::MSSQL
+    ') unless $attrs->{unsafe_subselect_ok};
     my $max = 2 ** 32;
     $sql =~ s/^ \s* SELECT \s/SELECT TOP $max /xi;
   }
@@ -308,44 +308,53 @@ $table_name ON>. Unfortunately this operation in MSSQL requires the
 C<db_ddladmin> privilege, which is normally not included in the standard
 write-permissions.
 
-=head2 Ordered Subqueries
+=head2 Ordered Subselects
 
- # this is deemed unsafe and throws under MSSQL
- $rs->search ({}, {
-  prefetch => 'relation',
-  rows => 2,
-  offset => 3,
- });
+If you attempted the following query (among many others) in Microsoft SQL
+Server
 
- # however this should work (but please check what comes back from the db)
  $rs->search ({}, {
-  unsafe_subquery => 1,
   prefetch => 'relation',
   rows => 2,
   offset => 3,
  });
 
-DBIC can do truly wonderful things with the aid of subqueries, and does so
-automatically when necessary. Especially useful are ordered subqueries,
-which allow things like "Give me things number 4 to 6 (ordered by name), and
-prefetch all their relationss, no matter how many". In its pursuit of standards
-Microsft SQL Server goes to great lengths to forbid the use of ordered
-subqueries. While there is a hack which fools the syntax checker, the optimizer
-may B<still elect to break the subquery>. Testing has determined that while
-such breakage does occur (the test suite contains an explicit test which
-demonstrates the problem), it is relative rare. The benefits of ordered
-subqueries are on the other hand too great to be outright disabled for MSSQL.
+You may be surprised to receive an exception. The reason for this is a quirk
+in the MSSQL engine itself, and sadly doesn't have a sensible workaround due
+to the way DBIC is built. DBIC can do truly wonderful things with the aid of
+subselects, and does so automatically when necessary. The list of situations
+when a subselect is necessary is long and still changes often, so it can not
+be exhaustively enumerated here. The general rule of thumb is a joined
+L<has_many|DBIx::Class::Relationship/has_many> relationship with limit/group
+applied to the left part of the join.
+
+In its "pursuit of standards" Microsft SQL Server goes to great lengths to
+forbid the use of ordered subselects. This breaks a very useful group of
+searches like "Give me things number 4 to 6 (ordered by name), and prefetch
+all their relations, no matter how many". While there is a hack which fools
+the syntax checker, the optimizer may B<still elect to break the subselect>.
+Testing has determined that while such breakage does occur (the test suite
+contains an explicit test which demonstrates the problem), it is relative
+rare. The benefits of ordered subselects are on the other hand too great to be
+outright disabled for MSSQL.
 
 Thus compromise between usability and perfection is the MSSQL-specific
-L<resultset attribute|DBIx::Class::ResultSet/ATTRIBUTES> C<unsafe_subquery>.
+L<resultset attribute|DBIx::Class::ResultSet/ATTRIBUTES> C<unsafe_subselect_ok>.
 It is deliberately not possible to set this on the Storage level, as the user
 should inspect (and preferrably regression-test) the return of every such
-ResultSet individually.
+ResultSet individually. The example above would work if written like:
+
+ $rs->search ({}, {
+  unsafe_subselect_ok => 1,
+  prefetch => 'relation',
+  rows => 2,
+  offset => 3,
+ });
 
 If it is possible to rewrite the search() in a way that will avoid the need
 for this flag - you are urged to do so. If DBIC internals insist that an
-ordered subquery is necessary for an operation, and you believe there is a
-differnt way to express the query - please file a bugreport.
+ordered subselect is necessary for an operation, and you believe there is a
+differnt/better way to get the same result - please file a bugreport.
 
 =head1 AUTHOR