Merge pull request rails#49423 from paulreece/update_has_one_doc

Added available methods for has_one association to guide.

Author: rafaelfranca

guides/source/association_basics.md

@@ -1118,14 +1118,19 @@ The [`belongs_to`][] association supports these options:
 * `:autosave`
 * `:class_name`
 * `:counter_cache`
+* `:default`
 * `:dependent`
+* `:ensuring_owner_was`
 * `:foreign_key`
+* `:foreign_type`
 * `:primary_key`
 * `:inverse_of`
+* `:optional`
 * `:polymorphic`
+* `:required`
+* `:strict_loading`
 * `:touch`
 * `:validate`
-* `:optional`
 
 ##### `:autosave`
 
@@ -1201,6 +1206,10 @@ towards the counter. To fix a stale counter cache, use [`reset_counters`][].
 
 [`reset_counters`]: https://api.rubyonrails.org/classes/ActiveRecord/CounterCache/ClassMethods.html#method-i-reset_counters
 
+##### `:default`
+
+When set to `true`, the association will not have its presence validated.
+
 ##### `:dependent`
 
 If you set the `:dependent` option to:
@@ -1217,6 +1226,10 @@ If you set the `:dependent` option to:
 
 WARNING: You should not specify this option on a `belongs_to` association that is connected with a `has_many` association on the other class. Doing so can lead to orphaned records in your database.
 
+##### `:ensuring_owner_was`
+
+Specifies an instance method to be called on the owner. The method must return true in order for the associated records to be deleted in a background job.
+
 ##### `:foreign_key`
 
 By convention, Rails assumes that the column used to hold the foreign key on this model is the name of the association with the suffix `_id` added. The `:foreign_key` option lets you set the name of the foreign key directly:
@@ -1230,6 +1243,10 @@ end
 
 TIP: In any case, Rails will not create foreign key columns for you. You need to explicitly define them as part of your migrations.
 
+##### `:foreign_type`
+
+Specify the column used to store the associated object’s type, if this is a polymorphic association. By default this is guessed to be the name of the association with a “`_type`” suffix. So a class that defines a `belongs_to :taggable, polymorphic: true` association will use “`taggable_type`” as the default `:foreign_type`.
+
 ##### `:primary_key`
 
 By convention, Rails assumes that the `id` column is used to hold the primary key
@@ -1265,10 +1282,26 @@ class Book < ApplicationRecord
 end
 ```
 
+##### `:optional`
+
+If you set the `:optional` option to `true`, then the presence of the associated
+object won't be validated. By default, this option is set to `false`.
+
 ##### `:polymorphic`
 
 Passing `true` to the `:polymorphic` option indicates that this is a polymorphic association. Polymorphic associations were discussed in detail <a href="#polymorphic-associations">earlier in this guide</a>.
 
+
+##### `:required`
+
+When set to `true`, the association will also have its presence validated. This will validate the association itself, not the id. You can use `:inverse_of` to avoid an extra query during validation.
+
+NOTE: required is set to `true` by default and is deprecated. If you don’t want to have association presence validated, use `optional: true`.
+
+##### `:strict_loading`
+
+Enforces strict loading every time the associated record is loaded through this association.
+
 ##### `:touch`
 
 If you set the `:touch` option to `true`, then the `updated_at` or `updated_on` timestamp on the associated object will be set to the current time whenever this object is saved or destroyed:
@@ -1295,11 +1328,6 @@ end
 
 If you set the `:validate` option to `true`, then new associated objects will be validated whenever you save this object. By default, this is `false`: new associated objects will not be validated when this object is saved.
 
-##### `:optional`
-
-If you set the `:optional` option to `true`, then the presence of the associated
-object won't be validated. By default, this option is set to `false`.
-
 #### Scopes for `belongs_to`
 
 There may be times when you wish to customize the query used by `belongs_to`. Such customizations can be achieved via a scope block. For example:
@@ -1489,11 +1517,16 @@ The [`has_one`][] association supports these options:
 * `:autosave`
 * `:class_name`
 * `:dependent`
+* `:disable_joins`
+* `:ensuring_owner_was`
 * `:foreign_key`
 * `:inverse_of`
 * `:primary_key`
+* `:query_constraints`
+* `:required`
 * `:source`
 * `:source_type`
+* `:strict_loading`
 * `:through`
 * `:touch`
 * `:validate`
@@ -1533,6 +1566,10 @@ destroy such associations you won't be able to change the associated object
 because the initial associated object's foreign key will be set to the
 unallowed `NULL` value.
 
+##### `:disable_joins`
+
+Specifies whether joins should be skipped for an association. If set to `true`, two or more queries will be generated. Note that in some cases, if order or limit is applied, it will be done in-memory due to database limitations. This option is only applicable on `has_one :through` associations as `has_one` alone does not perform a join.
+
 ##### `:foreign_key`
 
 By convention, Rails assumes that the column used to hold the foreign key on the other model is the name of this model with the suffix `_id` added. The `:foreign_key` option lets you set the name of the foreign key directly:
@@ -1564,6 +1601,14 @@ end
 
 By convention, Rails assumes that the column used to hold the primary key of this model is `id`. You can override this and explicitly specify the primary key with the `:primary_key` option.
 
+##### `:query_constraints`
+
+Serves as a composite foreign key. Defines the list of columns to be used to query the associated object. This is an optional option. By default Rails will attempt to derive the value automatically. When the value is set the Array size must match associated model’s primary key or query_constraints size.
+
+##### `:required`
+
+When set to `true`, the association will also have its presence validated. This will validate the association itself, not the id. You can use `:inverse_of` to avoid an extra query during validation.
+
 ##### `:source`
 
 The `:source` option specifies the source association name for a `has_one :through` association.
@@ -1592,6 +1637,10 @@ end
 class DustJacket < ApplicationRecord; end
 ```
 
+##### `:strict_loading`
+
+Enforces strict loading every time the associated record is loaded through this association.
+
 ##### `:through`
 
 The `:through` option specifies a join model through which to perform the query. `has_one :through` associations were discussed in detail [earlier in this guide](#the-has-one-through-association).
@@ -1944,11 +1993,17 @@ The [`has_many`][] association supports these options:
 * `:class_name`
 * `:counter_cache`
 * `:dependent`
+* `:disable_joins`
+* `:ensuring_owner_was`
+* `:extend`
 * `:foreign_key`
+* `:foreign_type`
 * `:inverse_of`
 * `:primary_key`
+* `:query_constraints`
 * `:source`
 * `:source_type`
+* `:strict_loading`
 * `:through`
 * `:validate`
 
@@ -1987,6 +2042,18 @@ Controls what happens to the associated objects when their owner is destroyed:
 
 The `:destroy` and `:delete_all` options also affect the semantics of the `collection.delete` and `collection=` methods by causing them to destroy associated objects when they are removed from the collection.
 
+##### `:disable_joins`
+
+Specifies whether joins should be skipped for an association. If set to true, two or more queries will be generated. Note that in some cases, if order or limit is applied, it will be done in-memory due to database limitations. This option is only applicable on `has_many :through associations` as has_many alone do not perform a join.
+
+##### `:ensuring_owner_was`
+
+Specifies an instance method to be called on the owner. The method must return true in order for the associated records to be deleted in a background job.
+
+##### `:extend`
+
+Specifies a module or array of modules that will be extended into the association object returned. Useful for defining methods on associations, especially when they should be shared between multiple association objects.
+
 ##### `:foreign_key`
 
 By convention, Rails assumes that the column used to hold the foreign key on the other model is the name of this model with the suffix `_id` added. The `:foreign_key` option lets you set the name of the foreign key directly:
@@ -1999,6 +2066,10 @@ end
 
 TIP: In any case, Rails will not create foreign key columns for you. You need to explicitly define them as part of your migrations.
 
+##### `:foreign_type`
+
+Specify the column used to store the associated object’s type, if this is a polymorphic association. By default this is guessed to be the name of the polymorphic association specified on “`as`” option with a “`_type`” suffix. So a class that defines a `has_many :tags, as: :taggable` association will use “`taggable_type`” as the default `:foreign_type`.
+
 ##### `:inverse_of`
 
 The `:inverse_of` option specifies the name of the `belongs_to` association that is the inverse of this association.
@@ -2032,6 +2103,10 @@ end
 Now if we execute `@todo = @user.todos.create` then the `@todo`
 record's `user_id` value will be the `guid` value of `@user`.
 
+##### `:query_constraints`
+
+Serves as a composite foreign key. Defines the list of columns to be used to query the associated object. This is an optional option. By default Rails will attempt to derive the value automatically. When the value is set the Array size must match associated model’s primary key or `query_constraints` size.
+
 ##### `:source`
 
 The `:source` option specifies the source association name for a `has_many :through` association. You only need to use this option if the name of the source association cannot be automatically inferred from the association name.
@@ -2054,6 +2129,10 @@ class Hardback < ApplicationRecord; end
 class Paperback < ApplicationRecord; end
 ```
 
+##### `:strict_loading`
+
+When set to true, enforces strict loading every time the associated record is loaded through this association.
+
 ##### `:through`
 
 The `:through` option specifies a join model through which to perform the query. `has_many :through` associations provide a way to implement many-to-many relationships, as discussed [earlier in this guide](#the-has-many-through-association).
@@ -2486,6 +2565,7 @@ The [`has_and_belongs_to_many`][] association supports these options:
 * `:class_name`
 * `:foreign_key`
 * `:join_table`
+* `:strict_loading`
 * `:validate`
 
 ##### `:association_foreign_key`
@@ -2534,6 +2614,10 @@ end
 
 If the default name of the join table, based on lexical ordering, is not what you want, you can use the `:join_table` option to override the default.
 
+##### `:strict_loading`
+
+Enforces strict loading every time an associated record is loaded through this association.
+
 ##### `:validate`
 
 If you set the `:validate` option to `false`, then new associated objects will not be validated whenever you save this object. By default, this is `true`: new associated objects will be validated when this object is saved.