Merge pull request rails#49774 from stevepolitodesign/sp-disable-inheritance

Improve STI documentation

Author: rafaelfranca

activerecord/lib/active_record/inheritance.rb

@@ -202,7 +202,9 @@ def sti_class_for(type_name)
           "The single-table inheritance mechanism failed to locate the subclass: '#{type_name}'. " \
           "This error is raised because the column '#{inheritance_column}' is reserved for storing the class in case of inheritance. " \
           "Please rename this column if you didn't intend it to be used for storing the inheritance class " \
-          "or overwrite #{name}.inheritance_column to use another column for that information."
+          "or overwrite #{name}.inheritance_column to use another column for that information. " \
+          "If you wish to disable single-table inheritance for #{name} set " \
+          "#{name}.inheritance_column to nil"
       end
 
       # Returns the value to be stored in the polymorphic type column for Polymorphic Associations.

activerecord/lib/active_record/model_schema.rb

@@ -146,6 +146,11 @@ module ModelSchema
     # your own model for something else, you can set +inheritance_column+:
     #
     #     self.inheritance_column = 'zoink'
+    #
+    # If you wish to disable single-table inheritance altogether you can set
+    # +inheritance_column+ to +nil+
+    #
+    #     self.inheritance_column = nil
 
     ##
     # :singleton-method: inheritance_column=

guides/source/association_basics.md

@@ -2904,6 +2904,46 @@ will run a query like:
 SELECT "vehicles".* FROM "vehicles" WHERE "vehicles"."type" IN ('Car')
 ```
 
+### Overriding the inheritance column
+
+There may be cases (like when working with a legacy database) where you need to
+override the name of the inheritance column. This can be achieved with the
+[inheritance_column][] method.
+
+```ruby
+# Schema: vehicles[ id, kind, created_at, updated_at ]
+class Vehicle < ApplicationRecord
+  self.inheritance_column = "kind"
+end
+
+class Car < Vehicle
+end
+
+Car.create
+# => #<Car kind: "Car">
+```
+
+### Disabling the inheritance column
+
+There may be cases (like when working with a legacy database) where you need to
+disable Single Table Inheritance altogether. Otherwise, you'll raise
+[`ActiveRecord::SubclassNotFound`][].
+
+This can be achieved by setting the [inheritance_column][] to `nil`.
+
+```ruby
+# Schema: vehicles[ id, type, created_at, updated_at ]
+class Vehicle < ApplicationRecord
+  self.inheritance_column = nil
+end
+
+Vehicle.create!(type: "Car")
+# => #<Vehicle type: "Car">
+```
+
+[inheritance_column]: https://api.rubyonrails.org/classes/ActiveRecord/ModelSchema.html#method-c-inheritance_column
+[`ActiveRecord::SubclassNotFound`]: https://api.rubyonrails.org/classes/ActiveRecord/SubclassNotFound.html
+
 Delegated Types
 ----------------