convenience method for outer_join

4 files changed, 44 insertions, 0 deletions

diff --git a/lib/arel/select_manager.rb b/lib/arel/select_manager.rb
index 804316209c..0bcffba680 100644
--- a/lib/arel/select_manager.rb
+++ b/lib/arel/select_manager.rb
@@ -114,6 +114,10 @@ module Arel
       self
     end
 
+    def outer_join relation
+      join(relation, Nodes::OuterJoin)
+    end
+
     def having *exprs
       @ctx.having = Nodes::Having.new(collapse(exprs, @ctx.having))
       self
diff --git a/lib/arel/table.rb b/lib/arel/table.rb
index 16ae83c284..3866637bd2 100644
--- a/lib/arel/table.rb
+++ b/lib/arel/table.rb
@@ -64,6 +64,10 @@ primary_key (#{caller.first}) is deprecated and will be removed in Arel 4.0.0
       from(self).join(relation, klass)
     end
 
+    def outer_join relation
+      join(relation, Nodes::OuterJoin)
+    end
+
     def group *columns
       from(self).group(*columns)
     end
diff --git a/test/test_select_manager.rb b/test/test_select_manager.rb
index 837486fb46..5662bc8990 100644
--- a/test/test_select_manager.rb
+++ b/test/test_select_manager.rb
@@ -579,6 +579,28 @@ module Arel
       end
     end
 
+    describe 'outer join' do
+      it 'responds to join' do
+        left      = Table.new :users
+        right     = left.alias
+        predicate = left[:id].eq(right[:id])
+        manager   = Arel::SelectManager.new Table.engine
+
+        manager.from left
+        manager.outer_join(right).on(predicate)
+        manager.to_sql.must_be_like %{
+           SELECT FROM "users"
+             LEFT OUTER JOIN "users" "users_2"
+               ON "users"."id" = "users_2"."id"
+        }
+      end
+
+      it 'noops on nil' do
+        manager   = Arel::SelectManager.new Table.engine
+        manager.outer_join(nil).must_equal manager
+      end
+    end
+
     describe 'joins' do
       it 'returns join sql' do
         table   = Table.new :users
diff --git a/test/test_table.rb b/test/test_table.rb
index b4c2a65fcd..286ad10167 100644
--- a/test/test_table.rb
+++ b/test/test_table.rb
@@ -96,6 +96,20 @@ module Arel
           }
         end
       end
+
+      describe 'join' do
+        it 'creates an outer join' do
+          right     = @relation.alias
+          predicate = @relation[:id].eq(right[:id])
+          mgr = @relation.outer_join(right).on(predicate)
+
+          mgr.to_sql.must_be_like %{
+            SELECT FROM "users"
+              LEFT OUTER JOIN "users" "users_2"
+                ON "users"."id" = "users_2"."id"
+          }
+        end
+      end
     end
 
     describe 'group' do