Merge pull request #20364 from ernie/update-serialize-docs

Update docs for ActiveRecord `serialize`

[ci skip]

1 files changed, 9 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/attribute_methods/serialization.rb b/activerecord/lib/active_record/attribute_methods/serialization.rb
index d0d8a968c5..fd7099e0de 100644
--- a/activerecord/lib/active_record/attribute_methods/serialization.rb
+++ b/activerecord/lib/active_record/attribute_methods/serialization.rb
@@ -11,6 +11,15 @@ module ActiveRecord
         # serialized object must be of that class on assignment and retrieval.
         # Otherwise <tt>SerializationTypeMismatch</tt> will be raised.
         #
+        # Keep in mind that database adapters handle certain serialization tasks
+        # for you. For instance: +json+ and +jsonb+ types in PostgreSQL will be
+        # converted between JSON object/array syntax and Ruby +Hash+ or +Array+
+        # objects transparently. There is no need to use +serialize+ in this
+        # case.
+        #
+        # For more complex cases, such as conversion to or from your application
+        # domain objects, consider using the ActiveRecord::Attributes API.
+        #
         # ==== Parameters
         #
         # * +attr_name+ - The field name that should be serialized.