Rename subquery to subselect and rewrite POD (per castaway)

diff --git a/lib/DBIx/Class/Storage/DBI/MSSQL.pm b/lib/DBIx/Class/Storage/DBI/MSSQL.pm
index 0331180..1893c66 100644 (file)
--- a/lib/DBIx/Class/Storage/DBI/MSSQL.pm
+++ b/lib/DBIx/Class/Storage/DBI/MSSQL.pm
@@ -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};
     my $max = 2 ** 32;
     $sql =~ s/^ \s* SELECT \s/SELECT TOP $max /xi;
   }
@@ -308,43 +308,52 @@ $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 searches like "Give me things number 4 to 6 (ordered by name), and
-prefetch all their relations, 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>.
 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 => 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
+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

diff --git a/t/746mssql.t b/t/746mssql.t
index a4720c8..e70a3b8 100644 (file)
--- a/t/746mssql.t
+++ b/t/746mssql.t
@@ -258,11 +258,11 @@ lives_ok ( sub {
 # plain ordered subqueries throw
 throws_ok (sub {
   $schema->resultset('Owners')->search ({}, { order_by => 'name' })->as_query
-}, qr/ordered subquery encountered/, 'Ordered Subquery detection throws ok');
+}, qr/ordered subselect encountered/, 'Ordered Subselect detection throws ok');
 
 # make sure ordered subselects *somewhat* work
 {
-  my $owners = $schema->resultset ('Owners')->search ({}, { order_by => 'name', offset => 2, rows => 3, unsafe_subquery => 1 });
+  my $owners = $schema->resultset ('Owners')->search ({}, { order_by => 'name', offset => 2, rows => 3, unsafe_subselect => 1 });
 
   my $al = $owners->current_source_alias;
   my $sealed_owners = $owners->result_source->resultset->search (
@@ -288,7 +288,7 @@ TODO: {
   local $TODO = "This porbably will never work, but it isn't critical either afaik";
 
   my $book_owner_ids = $schema->resultset ('BooksInLibrary')
-                               ->search ({}, { join => 'owner', distinct => 1, order_by => 'owner.name', unsafe_subquery => 1 })
+                               ->search ({}, { join => 'owner', distinct => 1, order_by => 'owner.name', unsafe_subselect => 1 })
                                 ->get_column ('owner');
 
   my $book_owners = $schema->resultset ('Owners')->search ({
@@ -304,7 +304,7 @@ TODO: {
 
 # This is known not to work - thus the negative test
 {
-  my $owners = $schema->resultset ('Owners')->search ({}, { order_by => 'name', offset => 2, rows => 3, unsafe_subquery => 1 });
+  my $owners = $schema->resultset ('Owners')->search ({}, { order_by => 'name', offset => 2, rows => 3, unsafe_subselect => 1 });
   my $corelated_owners = $owners->result_source->resultset->search (
     {
       id => { -in => $owners->get_column('id')->as_query },
@@ -351,7 +351,7 @@ TODO: {
     'Rows were properly ordered'
   );
 
-  my $limited_rs = $rs->search ({}, {rows => 7, offset => 2, unsafe_subquery => 1});
+  my $limited_rs = $rs->search ({}, {rows => 7, offset => 2, unsafe_subselect => 1});
   is ($limited_rs->count, 6, 'Correct count of limited right-sorted joined resultset');
   is ($limited_rs->count_rs->next, 6, 'Correct count_rs of limited right-sorted joined resultset');
 
@@ -397,7 +397,7 @@ $schema->storage->_sql_maker->{name_sep} = '.';
       prefetch => 'books',
       order_by => { -asc => \['name + ?', [ test => 'xxx' ]] }, # test bindvar propagation
       rows     => 3,  # 8 results total
-      unsafe_subquery => 1,
+      unsafe_subselect => 1,
     },
   );
 
@@ -426,7 +426,7 @@ $schema->storage->_sql_maker->{name_sep} = '.';
       prefetch => 'owner',
       rows     => 2,  # 3 results total
       order_by => { -desc => 'owner' },
-      unsafe_subquery => 1,
+      unsafe_subselect => 1,
     },
   );