pick better names and add a little documentation

2 files changed, 24 insertions, 16 deletions

diff --git a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
index 5e166defea..c39e8c8577 100644
--- a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
@@ -406,7 +406,7 @@ module ActiveRecord
 
         initialize_type_map
         @local_tz = execute('SHOW TIME ZONE', 'SCHEMA').first["TimeZone"]
-        self.use_returning = true
+        self.enable_insert_returning!
       end
 
       # Clears the prepared statements cache.
@@ -668,7 +668,7 @@ module ActiveRecord
           pk = primary_key(table_ref) if table_ref
         end
 
-        if pk && use_returning?
+        if pk && use_insert_returning?
           select_value("#{sql} RETURNING #{quote_column_name(pk)}")
         elsif pk
           super
@@ -787,7 +787,7 @@ module ActiveRecord
           pk = primary_key(table_ref) if table_ref
         end
 
-        if pk && use_returning?
+        if pk && use_insert_returning?
           sql = "#{sql} RETURNING #{quote_column_name(pk)}"
         end
 
@@ -796,7 +796,7 @@ module ActiveRecord
 
       def exec_insert(sql, name, binds, pk = nil, sequence_name = nil)
         val = exec_query(sql, name, binds)
-        if !use_returning? && pk
+        if !use_insert_returning? && pk
           unless sequence_name
             table_ref = extract_table_ref_from_insert_sql(sql)
             sequence_name = default_sequence_name(table_ref, pk)
@@ -1258,12 +1258,20 @@ module ActiveRecord
         end
       end
 
-      def use_returning=(val)
-        @use_returning = val
+      # Enable insert statements to use INSERT ... RETURNING ... statements. On by default.
+      def enable_insert_returning!
+        @use_insert_returning = true
       end
 
-      def use_returning?
-        @use_returning
+      # Disable INSERT ... RETURNING ... statements, using currval() instead.
+      # Useful for trigger based insertions where INSERT RETURNING does the wrong thing.
+      def disable_insert_returning!
+        @use_insert_returning = false
+      end
+
+
+      def use_insert_returning?
+        @use_insert_returning
       end
 
       protected
diff --git a/activerecord/test/cases/adapters/postgresql/postgresql_adapter_test.rb b/activerecord/test/cases/adapters/postgresql/postgresql_adapter_test.rb
index 1452911974..3073b9f011 100644
--- a/activerecord/test/cases/adapters/postgresql/postgresql_adapter_test.rb
+++ b/activerecord/test/cases/adapters/postgresql/postgresql_adapter_test.rb
@@ -50,38 +50,38 @@ module ActiveRecord
       end
 
       def test_insert_sql_with_returning_disabled
-        @connection.use_returning = false
+        @connection.disable_insert_returning!
         id = @connection.insert_sql("insert into postgresql_partitioned_table_parent (number) VALUES (1)")
         expect = @connection.query('select max(id) from postgresql_partitioned_table_parent').first.first
         assert_equal expect, id
       ensure
-        @connection.use_returning = true
+        @connection.enable_insert_returning!
       end
 
       def test_exec_insert_with_returning_disabled
-        @connection.use_returning = false
+        @connection.disable_insert_returning!
         result = @connection.exec_insert("insert into postgresql_partitioned_table_parent (number) VALUES (1)", nil, [], 'id', 'postgresql_partitioned_table_parent_id_seq')
         expect = @connection.query('select max(id) from postgresql_partitioned_table_parent').first.first
         assert_equal expect, result.rows.first.first
       ensure
-        @connection.use_returning = true
+        @connection.enable_insert_returning!
       end
 
       def test_exec_insert_with_returning_disabled_and_no_sequence_name_given
-        @connection.use_returning = false
+        @connection.disable_insert_returning!
         result = @connection.exec_insert("insert into postgresql_partitioned_table_parent (number) VALUES (1)", nil, [], 'id')
         expect = @connection.query('select max(id) from postgresql_partitioned_table_parent').first.first
         assert_equal expect, result.rows.first.first
       ensure
-        @connection.use_returning = true
+        @connection.enable_insert_returning!
       end
 
       def test_sql_for_insert_with_returning_disabled
-        @connection.use_returning = false
+        @connection.disable_insert_returning!
         result = @connection.sql_for_insert('sql', nil, nil, nil, 'binds')
         assert_equal ['sql', 'binds'], result
       ensure
-        @connection.use_returning = true
+        @connection.enable_insert_returning!
       end
 
       def test_serial_sequence