activerecord 7.0.8.7 → 7.1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (237) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +1795 -1424
  3. data/MIT-LICENSE +1 -1
  4. data/README.rdoc +16 -16
  5. data/lib/active_record/aggregations.rb +16 -13
  6. data/lib/active_record/association_relation.rb +1 -1
  7. data/lib/active_record/associations/association.rb +20 -4
  8. data/lib/active_record/associations/association_scope.rb +16 -9
  9. data/lib/active_record/associations/belongs_to_association.rb +14 -6
  10. data/lib/active_record/associations/builder/association.rb +3 -3
  11. data/lib/active_record/associations/builder/belongs_to.rb +21 -8
  12. data/lib/active_record/associations/builder/has_and_belongs_to_many.rb +1 -5
  13. data/lib/active_record/associations/builder/singular_association.rb +4 -0
  14. data/lib/active_record/associations/collection_association.rb +19 -13
  15. data/lib/active_record/associations/collection_proxy.rb +15 -10
  16. data/lib/active_record/associations/foreign_association.rb +10 -3
  17. data/lib/active_record/associations/has_many_association.rb +20 -13
  18. data/lib/active_record/associations/has_many_through_association.rb +10 -6
  19. data/lib/active_record/associations/has_one_association.rb +10 -3
  20. data/lib/active_record/associations/join_dependency/join_association.rb +3 -2
  21. data/lib/active_record/associations/join_dependency.rb +10 -10
  22. data/lib/active_record/associations/preloader/association.rb +31 -7
  23. data/lib/active_record/associations/preloader.rb +13 -10
  24. data/lib/active_record/associations/singular_association.rb +1 -1
  25. data/lib/active_record/associations/through_association.rb +22 -11
  26. data/lib/active_record/associations.rb +319 -217
  27. data/lib/active_record/attribute_assignment.rb +0 -2
  28. data/lib/active_record/attribute_methods/before_type_cast.rb +17 -0
  29. data/lib/active_record/attribute_methods/dirty.rb +53 -35
  30. data/lib/active_record/attribute_methods/primary_key.rb +76 -24
  31. data/lib/active_record/attribute_methods/query.rb +28 -16
  32. data/lib/active_record/attribute_methods/read.rb +21 -8
  33. data/lib/active_record/attribute_methods/serialization.rb +150 -31
  34. data/lib/active_record/attribute_methods/time_zone_conversion.rb +4 -0
  35. data/lib/active_record/attribute_methods/write.rb +6 -6
  36. data/lib/active_record/attribute_methods.rb +145 -21
  37. data/lib/active_record/attributes.rb +3 -3
  38. data/lib/active_record/autosave_association.rb +59 -10
  39. data/lib/active_record/base.rb +7 -2
  40. data/lib/active_record/callbacks.rb +10 -24
  41. data/lib/active_record/coders/column_serializer.rb +61 -0
  42. data/lib/active_record/coders/json.rb +1 -1
  43. data/lib/active_record/coders/yaml_column.rb +70 -42
  44. data/lib/active_record/connection_adapters/abstract/connection_handler.rb +163 -88
  45. data/lib/active_record/connection_adapters/abstract/connection_pool/queue.rb +2 -0
  46. data/lib/active_record/connection_adapters/abstract/connection_pool/reaper.rb +3 -1
  47. data/lib/active_record/connection_adapters/abstract/connection_pool.rb +80 -50
  48. data/lib/active_record/connection_adapters/abstract/database_limits.rb +5 -0
  49. data/lib/active_record/connection_adapters/abstract/database_statements.rb +129 -31
  50. data/lib/active_record/connection_adapters/abstract/query_cache.rb +62 -23
  51. data/lib/active_record/connection_adapters/abstract/quoting.rb +41 -6
  52. data/lib/active_record/connection_adapters/abstract/savepoints.rb +4 -3
  53. data/lib/active_record/connection_adapters/abstract/schema_creation.rb +18 -4
  54. data/lib/active_record/connection_adapters/abstract/schema_definitions.rb +137 -11
  55. data/lib/active_record/connection_adapters/abstract/schema_statements.rb +296 -127
  56. data/lib/active_record/connection_adapters/abstract/transaction.rb +287 -58
  57. data/lib/active_record/connection_adapters/abstract_adapter.rb +511 -92
  58. data/lib/active_record/connection_adapters/abstract_mysql_adapter.rb +244 -121
  59. data/lib/active_record/connection_adapters/column.rb +9 -0
  60. data/lib/active_record/connection_adapters/mysql/column.rb +1 -0
  61. data/lib/active_record/connection_adapters/mysql/database_statements.rb +22 -143
  62. data/lib/active_record/connection_adapters/mysql/quoting.rb +16 -12
  63. data/lib/active_record/connection_adapters/mysql/schema_creation.rb +9 -0
  64. data/lib/active_record/connection_adapters/mysql/schema_definitions.rb +6 -0
  65. data/lib/active_record/connection_adapters/mysql/schema_dumper.rb +1 -1
  66. data/lib/active_record/connection_adapters/mysql/schema_statements.rb +19 -13
  67. data/lib/active_record/connection_adapters/mysql2/database_statements.rb +151 -0
  68. data/lib/active_record/connection_adapters/mysql2_adapter.rb +106 -55
  69. data/lib/active_record/connection_adapters/pool_config.rb +14 -5
  70. data/lib/active_record/connection_adapters/pool_manager.rb +19 -9
  71. data/lib/active_record/connection_adapters/postgresql/column.rb +14 -3
  72. data/lib/active_record/connection_adapters/postgresql/database_statements.rb +74 -40
  73. data/lib/active_record/connection_adapters/postgresql/oid/cidr.rb +6 -0
  74. data/lib/active_record/connection_adapters/postgresql/oid/money.rb +3 -2
  75. data/lib/active_record/connection_adapters/postgresql/oid/range.rb +11 -2
  76. data/lib/active_record/connection_adapters/postgresql/oid/timestamp_with_time_zone.rb +1 -1
  77. data/lib/active_record/connection_adapters/postgresql/quoting.rb +10 -6
  78. data/lib/active_record/connection_adapters/postgresql/referential_integrity.rb +3 -9
  79. data/lib/active_record/connection_adapters/postgresql/schema_creation.rb +76 -6
  80. data/lib/active_record/connection_adapters/postgresql/schema_definitions.rb +131 -2
  81. data/lib/active_record/connection_adapters/postgresql/schema_dumper.rb +53 -0
  82. data/lib/active_record/connection_adapters/postgresql/schema_statements.rb +364 -61
  83. data/lib/active_record/connection_adapters/postgresql_adapter.rb +353 -192
  84. data/lib/active_record/connection_adapters/schema_cache.rb +287 -59
  85. data/lib/active_record/connection_adapters/sqlite3/column.rb +49 -0
  86. data/lib/active_record/connection_adapters/sqlite3/database_statements.rb +52 -39
  87. data/lib/active_record/connection_adapters/sqlite3/quoting.rb +4 -3
  88. data/lib/active_record/connection_adapters/sqlite3/schema_definitions.rb +1 -0
  89. data/lib/active_record/connection_adapters/sqlite3/schema_statements.rb +26 -7
  90. data/lib/active_record/connection_adapters/sqlite3_adapter.rb +211 -81
  91. data/lib/active_record/connection_adapters/statement_pool.rb +7 -0
  92. data/lib/active_record/connection_adapters/trilogy/database_statements.rb +99 -0
  93. data/lib/active_record/connection_adapters/trilogy_adapter.rb +258 -0
  94. data/lib/active_record/connection_adapters.rb +3 -1
  95. data/lib/active_record/connection_handling.rb +72 -95
  96. data/lib/active_record/core.rb +181 -154
  97. data/lib/active_record/counter_cache.rb +52 -27
  98. data/lib/active_record/database_configurations/connection_url_resolver.rb +1 -1
  99. data/lib/active_record/database_configurations/database_config.rb +9 -3
  100. data/lib/active_record/database_configurations/hash_config.rb +28 -14
  101. data/lib/active_record/database_configurations/url_config.rb +17 -11
  102. data/lib/active_record/database_configurations.rb +86 -33
  103. data/lib/active_record/delegated_type.rb +15 -10
  104. data/lib/active_record/deprecator.rb +7 -0
  105. data/lib/active_record/destroy_association_async_job.rb +3 -1
  106. data/lib/active_record/encryption/auto_filtered_parameters.rb +66 -0
  107. data/lib/active_record/encryption/cipher/aes256_gcm.rb +4 -1
  108. data/lib/active_record/encryption/config.rb +25 -1
  109. data/lib/active_record/encryption/configurable.rb +12 -19
  110. data/lib/active_record/encryption/context.rb +10 -3
  111. data/lib/active_record/encryption/contexts.rb +5 -1
  112. data/lib/active_record/encryption/derived_secret_key_provider.rb +8 -2
  113. data/lib/active_record/encryption/encryptable_record.rb +42 -18
  114. data/lib/active_record/encryption/encrypted_attribute_type.rb +23 -8
  115. data/lib/active_record/encryption/extended_deterministic_queries.rb +66 -69
  116. data/lib/active_record/encryption/extended_deterministic_uniqueness_validator.rb +3 -3
  117. data/lib/active_record/encryption/key_generator.rb +12 -1
  118. data/lib/active_record/encryption/message_serializer.rb +2 -0
  119. data/lib/active_record/encryption/properties.rb +3 -3
  120. data/lib/active_record/encryption/scheme.rb +22 -21
  121. data/lib/active_record/encryption.rb +3 -0
  122. data/lib/active_record/enum.rb +112 -28
  123. data/lib/active_record/errors.rb +112 -18
  124. data/lib/active_record/explain.rb +23 -3
  125. data/lib/active_record/fixture_set/model_metadata.rb +14 -4
  126. data/lib/active_record/fixture_set/render_context.rb +2 -0
  127. data/lib/active_record/fixture_set/table_row.rb +29 -8
  128. data/lib/active_record/fixtures.rb +135 -71
  129. data/lib/active_record/future_result.rb +40 -5
  130. data/lib/active_record/gem_version.rb +4 -4
  131. data/lib/active_record/inheritance.rb +30 -16
  132. data/lib/active_record/insert_all.rb +57 -10
  133. data/lib/active_record/integration.rb +8 -8
  134. data/lib/active_record/internal_metadata.rb +120 -30
  135. data/lib/active_record/locking/optimistic.rb +1 -1
  136. data/lib/active_record/locking/pessimistic.rb +5 -2
  137. data/lib/active_record/log_subscriber.rb +29 -12
  138. data/lib/active_record/marshalling.rb +59 -0
  139. data/lib/active_record/message_pack.rb +124 -0
  140. data/lib/active_record/middleware/database_selector/resolver.rb +4 -0
  141. data/lib/active_record/middleware/database_selector.rb +6 -8
  142. data/lib/active_record/middleware/shard_selector.rb +3 -1
  143. data/lib/active_record/migration/command_recorder.rb +104 -5
  144. data/lib/active_record/migration/compatibility.rb +145 -5
  145. data/lib/active_record/migration/default_strategy.rb +23 -0
  146. data/lib/active_record/migration/execution_strategy.rb +19 -0
  147. data/lib/active_record/migration/pending_migration_connection.rb +21 -0
  148. data/lib/active_record/migration.rb +219 -111
  149. data/lib/active_record/model_schema.rb +69 -44
  150. data/lib/active_record/nested_attributes.rb +37 -8
  151. data/lib/active_record/normalization.rb +167 -0
  152. data/lib/active_record/persistence.rb +188 -37
  153. data/lib/active_record/promise.rb +84 -0
  154. data/lib/active_record/query_cache.rb +4 -22
  155. data/lib/active_record/query_logs.rb +77 -52
  156. data/lib/active_record/query_logs_formatter.rb +41 -0
  157. data/lib/active_record/querying.rb +15 -2
  158. data/lib/active_record/railtie.rb +107 -45
  159. data/lib/active_record/railties/controller_runtime.rb +12 -6
  160. data/lib/active_record/railties/databases.rake +144 -150
  161. data/lib/active_record/railties/job_runtime.rb +23 -0
  162. data/lib/active_record/readonly_attributes.rb +32 -5
  163. data/lib/active_record/reflection.rb +181 -45
  164. data/lib/active_record/relation/batches/batch_enumerator.rb +5 -3
  165. data/lib/active_record/relation/batches.rb +190 -61
  166. data/lib/active_record/relation/calculations.rb +187 -63
  167. data/lib/active_record/relation/delegation.rb +23 -9
  168. data/lib/active_record/relation/finder_methods.rb +77 -16
  169. data/lib/active_record/relation/merger.rb +2 -0
  170. data/lib/active_record/relation/predicate_builder/association_query_value.rb +11 -2
  171. data/lib/active_record/relation/predicate_builder/polymorphic_array_value.rb +10 -7
  172. data/lib/active_record/relation/predicate_builder/relation_handler.rb +5 -1
  173. data/lib/active_record/relation/predicate_builder.rb +26 -14
  174. data/lib/active_record/relation/query_attribute.rb +2 -1
  175. data/lib/active_record/relation/query_methods.rb +371 -68
  176. data/lib/active_record/relation/spawn_methods.rb +18 -1
  177. data/lib/active_record/relation.rb +103 -37
  178. data/lib/active_record/result.rb +19 -5
  179. data/lib/active_record/runtime_registry.rb +24 -1
  180. data/lib/active_record/sanitization.rb +51 -11
  181. data/lib/active_record/schema.rb +2 -3
  182. data/lib/active_record/schema_dumper.rb +46 -7
  183. data/lib/active_record/schema_migration.rb +68 -33
  184. data/lib/active_record/scoping/default.rb +15 -5
  185. data/lib/active_record/scoping/named.rb +2 -2
  186. data/lib/active_record/scoping.rb +2 -1
  187. data/lib/active_record/secure_password.rb +60 -0
  188. data/lib/active_record/secure_token.rb +21 -3
  189. data/lib/active_record/signed_id.rb +7 -5
  190. data/lib/active_record/store.rb +8 -8
  191. data/lib/active_record/suppressor.rb +3 -1
  192. data/lib/active_record/table_metadata.rb +10 -1
  193. data/lib/active_record/tasks/database_tasks.rb +152 -108
  194. data/lib/active_record/tasks/mysql_database_tasks.rb +15 -6
  195. data/lib/active_record/tasks/postgresql_database_tasks.rb +16 -13
  196. data/lib/active_record/tasks/sqlite_database_tasks.rb +15 -7
  197. data/lib/active_record/test_fixtures.rb +114 -96
  198. data/lib/active_record/timestamp.rb +30 -16
  199. data/lib/active_record/token_for.rb +113 -0
  200. data/lib/active_record/touch_later.rb +11 -6
  201. data/lib/active_record/transactions.rb +36 -10
  202. data/lib/active_record/type/adapter_specific_registry.rb +1 -8
  203. data/lib/active_record/type/internal/timezone.rb +7 -2
  204. data/lib/active_record/type/time.rb +4 -0
  205. data/lib/active_record/validations/absence.rb +1 -1
  206. data/lib/active_record/validations/numericality.rb +5 -4
  207. data/lib/active_record/validations/presence.rb +5 -28
  208. data/lib/active_record/validations/uniqueness.rb +47 -2
  209. data/lib/active_record/validations.rb +8 -4
  210. data/lib/active_record/version.rb +1 -1
  211. data/lib/active_record.rb +122 -17
  212. data/lib/arel/errors.rb +10 -0
  213. data/lib/arel/factory_methods.rb +4 -0
  214. data/lib/arel/nodes/binary.rb +6 -1
  215. data/lib/arel/nodes/bound_sql_literal.rb +61 -0
  216. data/lib/arel/nodes/cte.rb +36 -0
  217. data/lib/arel/nodes/fragments.rb +35 -0
  218. data/lib/arel/nodes/homogeneous_in.rb +1 -9
  219. data/lib/arel/nodes/leading_join.rb +8 -0
  220. data/lib/arel/nodes/node.rb +111 -2
  221. data/lib/arel/nodes/sql_literal.rb +6 -0
  222. data/lib/arel/nodes/table_alias.rb +4 -0
  223. data/lib/arel/nodes.rb +4 -0
  224. data/lib/arel/predications.rb +2 -0
  225. data/lib/arel/table.rb +9 -5
  226. data/lib/arel/tree_manager.rb +5 -1
  227. data/lib/arel/visitors/mysql.rb +8 -1
  228. data/lib/arel/visitors/to_sql.rb +83 -18
  229. data/lib/arel/visitors/visitor.rb +2 -2
  230. data/lib/arel.rb +16 -2
  231. data/lib/rails/generators/active_record/application_record/USAGE +8 -0
  232. data/lib/rails/generators/active_record/migration.rb +3 -1
  233. data/lib/rails/generators/active_record/model/USAGE +113 -0
  234. data/lib/rails/generators/active_record/model/model_generator.rb +15 -6
  235. metadata +46 -10
  236. data/lib/active_record/connection_adapters/legacy_pool_manager.rb +0 -35
  237. data/lib/active_record/null_relation.rb +0 -63
@@ -184,6 +184,22 @@ module ActiveRecord
184
184
  end
185
185
  end
186
186
 
187
+ class CompositePrimaryKeyMismatchError < ActiveRecordError # :nodoc:
188
+ attr_reader :reflection
189
+
190
+ def initialize(reflection = nil)
191
+ if reflection
192
+ if reflection.has_one? || reflection.collection?
193
+ super("Association #{reflection.active_record}##{reflection.name} primary key #{reflection.active_record_primary_key} doesn't match with foreign key #{reflection.foreign_key}. Please specify query_constraints, or primary_key and foreign_key values.")
194
+ else
195
+ super("Association #{reflection.active_record}##{reflection.name} primary key #{reflection.association_primary_key} doesn't match with foreign key #{reflection.foreign_key}. Please specify query_constraints, or primary_key and foreign_key values.")
196
+ end
197
+ else
198
+ super("Association primary key doesn't match with foreign key.")
199
+ end
200
+ end
201
+ end
202
+
187
203
  class AmbiguousSourceReflectionForThroughAssociation < ActiveRecordError # :nodoc:
188
204
  def initialize(klass, macro, association_name, options, possible_sources)
189
205
  example_options = options.dup
@@ -319,8 +335,8 @@ module ActiveRecord
319
335
 
320
336
  private
321
337
  def init_internals
322
- @association_cache = {}
323
338
  super
339
+ @association_cache = {}
324
340
  end
325
341
 
326
342
  # Returns the specified association instance if it exists, +nil+ otherwise.
@@ -333,6 +349,8 @@ module ActiveRecord
333
349
  @association_cache[name] = association
334
350
  end
335
351
 
352
+ # = Active Record \Associations
353
+ #
336
354
  # \Associations are a set of macro-like class methods for tying objects together through
337
355
  # foreign keys. They express relationships like "Project has one Project Manager"
338
356
  # or "Project belongs to a Portfolio". Each macro adds a number of methods to the
@@ -349,23 +367,42 @@ module ActiveRecord
349
367
  #
350
368
  # The project class now has the following methods (and more) to ease the traversal and
351
369
  # manipulation of its relationships:
352
- # * <tt>Project#portfolio</tt>, <tt>Project#portfolio=(portfolio)</tt>, <tt>Project#reload_portfolio</tt>
353
- # * <tt>Project#project_manager</tt>, <tt>Project#project_manager=(project_manager)</tt>, <tt>Project#reload_project_manager</tt>
354
- # * <tt>Project#milestones.empty?</tt>, <tt>Project#milestones.size</tt>, <tt>Project#milestones</tt>, <tt>Project#milestones<<(milestone)</tt>,
355
- # <tt>Project#milestones.delete(milestone)</tt>, <tt>Project#milestones.destroy(milestone)</tt>, <tt>Project#milestones.find(milestone_id)</tt>,
356
- # <tt>Project#milestones.build</tt>, <tt>Project#milestones.create</tt>
357
- # * <tt>Project#categories.empty?</tt>, <tt>Project#categories.size</tt>, <tt>Project#categories</tt>, <tt>Project#categories<<(category1)</tt>,
358
- # <tt>Project#categories.delete(category1)</tt>, <tt>Project#categories.destroy(category1)</tt>
370
+ #
371
+ # project = Project.first
372
+ # project.portfolio
373
+ # project.portfolio = Portfolio.first
374
+ # project.reload_portfolio
375
+ #
376
+ # project.project_manager
377
+ # project.project_manager = ProjectManager.first
378
+ # project.reload_project_manager
379
+ #
380
+ # project.milestones.empty?
381
+ # project.milestones.size
382
+ # project.milestones
383
+ # project.milestones << Milestone.first
384
+ # project.milestones.delete(Milestone.first)
385
+ # project.milestones.destroy(Milestone.first)
386
+ # project.milestones.find(Milestone.first.id)
387
+ # project.milestones.build
388
+ # project.milestones.create
389
+ #
390
+ # project.categories.empty?
391
+ # project.categories.size
392
+ # project.categories
393
+ # project.categories << Category.first
394
+ # project.categories.delete(category1)
395
+ # project.categories.destroy(category1)
359
396
  #
360
397
  # === A word of warning
361
398
  #
362
399
  # Don't create associations that have the same name as {instance methods}[rdoc-ref:ActiveRecord::Core] of
363
- # <tt>ActiveRecord::Base</tt>. Since the association adds a method with that name to
364
- # its model, using an association with the same name as one provided by <tt>ActiveRecord::Base</tt> will override the method inherited through <tt>ActiveRecord::Base</tt> and will break things.
365
- # For instance, +attributes+ and +connection+ would be bad choices for association names, because those names already exist in the list of <tt>ActiveRecord::Base</tt> instance methods.
400
+ # +ActiveRecord::Base+. Since the association adds a method with that name to
401
+ # its model, using an association with the same name as one provided by +ActiveRecord::Base+ will override the method inherited through +ActiveRecord::Base+ and will break things.
402
+ # For instance, +attributes+ and +connection+ would be bad choices for association names, because those names already exist in the list of +ActiveRecord::Base+ instance methods.
366
403
  #
367
404
  # == Auto-generated methods
368
- # See also Instance Public methods below for more details.
405
+ # See also "Instance Public methods" below ( from #belongs_to ) for more details.
369
406
  #
370
407
  # === Singular associations (one-to-one)
371
408
  # | | belongs_to |
@@ -611,6 +648,7 @@ module ActiveRecord
611
648
  # def log_after_remove(record)
612
649
  # # ...
613
650
  # end
651
+ # end
614
652
  #
615
653
  # It's possible to stack callbacks by passing them as an array. Example:
616
654
  #
@@ -1012,7 +1050,7 @@ module ActiveRecord
1012
1050
  # query per addressable type.
1013
1051
  # For example, if all the addressables are either of class Person or Company, then a total
1014
1052
  # of 3 queries will be executed. The list of addressable types to load is determined on
1015
- # the back of the addresses loaded. This is not supported if Active Record has to fallback
1053
+ # the back of the addresses loaded. This is not supported if Active Record has to fall back
1016
1054
  # to the previous implementation of eager loading and will raise ActiveRecord::EagerLoadPolymorphicError.
1017
1055
  # The reason is that the parent model's type is a column value so its corresponding table
1018
1056
  # name cannot be put in the +FROM+/+JOIN+ clauses of that query.
@@ -1025,45 +1063,45 @@ module ActiveRecord
1025
1063
  # Indexes are appended for any more successive uses of the table name.
1026
1064
  #
1027
1065
  # Post.joins(:comments)
1028
- # # => SELECT ... FROM posts INNER JOIN comments ON ...
1066
+ # # SELECT ... FROM posts INNER JOIN comments ON ...
1029
1067
  # Post.joins(:special_comments) # STI
1030
- # # => SELECT ... FROM posts INNER JOIN comments ON ... AND comments.type = 'SpecialComment'
1068
+ # # SELECT ... FROM posts INNER JOIN comments ON ... AND comments.type = 'SpecialComment'
1031
1069
  # Post.joins(:comments, :special_comments) # special_comments is the reflection name, posts is the parent table name
1032
- # # => SELECT ... FROM posts INNER JOIN comments ON ... INNER JOIN comments special_comments_posts
1070
+ # # SELECT ... FROM posts INNER JOIN comments ON ... INNER JOIN comments special_comments_posts
1033
1071
  #
1034
1072
  # Acts as tree example:
1035
1073
  #
1036
1074
  # TreeMixin.joins(:children)
1037
- # # => SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ...
1075
+ # # SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ...
1038
1076
  # TreeMixin.joins(children: :parent)
1039
- # # => SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ...
1040
- # INNER JOIN parents_mixins ...
1077
+ # # SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ...
1078
+ # # INNER JOIN parents_mixins ...
1041
1079
  # TreeMixin.joins(children: {parent: :children})
1042
- # # => SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ...
1043
- # INNER JOIN parents_mixins ...
1044
- # INNER JOIN mixins childrens_mixins_2
1080
+ # # SELECT ... FROM mixins INNER JOIN mixins childrens_mixins ...
1081
+ # # INNER JOIN parents_mixins ...
1082
+ # # INNER JOIN mixins childrens_mixins_2
1045
1083
  #
1046
1084
  # Has and Belongs to Many join tables use the same idea, but add a <tt>_join</tt> suffix:
1047
1085
  #
1048
1086
  # Post.joins(:categories)
1049
- # # => SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ...
1087
+ # # SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ...
1050
1088
  # Post.joins(categories: :posts)
1051
- # # => SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ...
1052
- # INNER JOIN categories_posts posts_categories_join INNER JOIN posts posts_categories
1089
+ # # SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ...
1090
+ # # INNER JOIN categories_posts posts_categories_join INNER JOIN posts posts_categories
1053
1091
  # Post.joins(categories: {posts: :categories})
1054
- # # => SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ...
1055
- # INNER JOIN categories_posts posts_categories_join INNER JOIN posts posts_categories
1056
- # INNER JOIN categories_posts categories_posts_join INNER JOIN categories categories_posts_2
1092
+ # # SELECT ... FROM posts INNER JOIN categories_posts ... INNER JOIN categories ...
1093
+ # # INNER JOIN categories_posts posts_categories_join INNER JOIN posts posts_categories
1094
+ # # INNER JOIN categories_posts categories_posts_join INNER JOIN categories categories_posts_2
1057
1095
  #
1058
1096
  # If you wish to specify your own custom joins using ActiveRecord::QueryMethods#joins method, those table
1059
1097
  # names will take precedence over the eager associations:
1060
1098
  #
1061
1099
  # Post.joins(:comments).joins("inner join comments ...")
1062
- # # => SELECT ... FROM posts INNER JOIN comments_posts ON ... INNER JOIN comments ...
1100
+ # # SELECT ... FROM posts INNER JOIN comments_posts ON ... INNER JOIN comments ...
1063
1101
  # Post.joins(:comments, :special_comments).joins("inner join comments ...")
1064
- # # => SELECT ... FROM posts INNER JOIN comments comments_posts ON ...
1065
- # INNER JOIN comments special_comments_posts ...
1066
- # INNER JOIN comments ...
1102
+ # # SELECT ... FROM posts INNER JOIN comments comments_posts ON ...
1103
+ # # INNER JOIN comments special_comments_posts ...
1104
+ # # INNER JOIN comments ...
1067
1105
  #
1068
1106
  # Table aliases are automatically truncated according to the maximum length of table identifiers
1069
1107
  # according to the specific database.
@@ -1144,7 +1182,8 @@ module ActiveRecord
1144
1182
  # belongs_to :dungeon, inverse_of: :evil_wizard
1145
1183
  # end
1146
1184
  #
1147
- # For more information, see the documentation for the +:inverse_of+ option.
1185
+ # For more information, see the documentation for the +:inverse_of+ option and the
1186
+ # {Active Record Associations guide}[https://guides.rubyonrails.org/association_basics.html#bi-directional-associations].
1148
1187
  #
1149
1188
  # == Deleting from associations
1150
1189
  #
@@ -1166,7 +1205,7 @@ module ActiveRecord
1166
1205
  # specific association types. When no option is given, the behavior is to do nothing
1167
1206
  # with the associated records when destroying a record.
1168
1207
  #
1169
- # Note that <tt>:dependent</tt> is implemented using Rails' callback
1208
+ # Note that <tt>:dependent</tt> is implemented using \Rails' callback
1170
1209
  # system, which works by processing callbacks in order. Therefore, other
1171
1210
  # callbacks declared either before or after the <tt>:dependent</tt> option
1172
1211
  # can affect what it does.
@@ -1237,15 +1276,15 @@ module ActiveRecord
1237
1276
  # +collection+ is a placeholder for the symbol passed as the +name+ argument, so
1238
1277
  # <tt>has_many :clients</tt> would add among others <tt>clients.empty?</tt>.
1239
1278
  #
1240
- # [collection]
1279
+ # [<tt>collection</tt>]
1241
1280
  # Returns a Relation of all the associated objects.
1242
1281
  # An empty Relation is returned if none are found.
1243
- # [collection<<(object, ...)]
1282
+ # [<tt>collection<<(object, ...)</tt>]
1244
1283
  # Adds one or more objects to the collection by setting their foreign keys to the collection's primary key.
1245
1284
  # Note that this operation instantly fires update SQL without waiting for the save or update call on the
1246
1285
  # parent object, unless the parent object is a new record.
1247
1286
  # This will also run validations and callbacks of associated object(s).
1248
- # [collection.delete(object, ...)]
1287
+ # [<tt>collection.delete(object, ...)</tt>]
1249
1288
  # Removes one or more objects from the collection by setting their foreign keys to +NULL+.
1250
1289
  # Objects will be in addition destroyed if they're associated with <tt>dependent: :destroy</tt>,
1251
1290
  # and deleted if they're associated with <tt>dependent: :delete_all</tt>.
@@ -1253,75 +1292,84 @@ module ActiveRecord
1253
1292
  # If the <tt>:through</tt> option is used, then the join records are deleted (rather than
1254
1293
  # nullified) by default, but you can specify <tt>dependent: :destroy</tt> or
1255
1294
  # <tt>dependent: :nullify</tt> to override this.
1256
- # [collection.destroy(object, ...)]
1295
+ # [<tt>collection.destroy(object, ...)</tt>]
1257
1296
  # Removes one or more objects from the collection by running <tt>destroy</tt> on
1258
1297
  # each record, regardless of any dependent option, ensuring callbacks are run.
1259
1298
  #
1260
1299
  # If the <tt>:through</tt> option is used, then the join records are destroyed
1261
1300
  # instead, not the objects themselves.
1262
- # [collection=objects]
1301
+ # [<tt>collection=objects</tt>]
1263
1302
  # Replaces the collections content by deleting and adding objects as appropriate. If the <tt>:through</tt>
1264
1303
  # option is true callbacks in the join models are triggered except destroy callbacks, since deletion is
1265
1304
  # direct by default. You can specify <tt>dependent: :destroy</tt> or
1266
1305
  # <tt>dependent: :nullify</tt> to override this.
1267
- # [collection_singular_ids]
1306
+ # [<tt>collection_singular_ids</tt>]
1268
1307
  # Returns an array of the associated objects' ids
1269
- # [collection_singular_ids=ids]
1308
+ # [<tt>collection_singular_ids=ids</tt>]
1270
1309
  # Replace the collection with the objects identified by the primary keys in +ids+. This
1271
1310
  # method loads the models and calls <tt>collection=</tt>. See above.
1272
- # [collection.clear]
1311
+ # [<tt>collection.clear</tt>]
1273
1312
  # Removes every object from the collection. This destroys the associated objects if they
1274
1313
  # are associated with <tt>dependent: :destroy</tt>, deletes them directly from the
1275
1314
  # database if <tt>dependent: :delete_all</tt>, otherwise sets their foreign keys to +NULL+.
1276
1315
  # If the <tt>:through</tt> option is true no destroy callbacks are invoked on the join models.
1277
1316
  # Join models are directly deleted.
1278
- # [collection.empty?]
1317
+ # [<tt>collection.empty?</tt>]
1279
1318
  # Returns +true+ if there are no associated objects.
1280
- # [collection.size]
1319
+ # [<tt>collection.size</tt>]
1281
1320
  # Returns the number of associated objects.
1282
- # [collection.find(...)]
1321
+ # [<tt>collection.find(...)</tt>]
1283
1322
  # Finds an associated object according to the same rules as ActiveRecord::FinderMethods#find.
1284
- # [collection.exists?(...)]
1323
+ # [<tt>collection.exists?(...)</tt>]
1285
1324
  # Checks whether an associated object with the given conditions exists.
1286
1325
  # Uses the same rules as ActiveRecord::FinderMethods#exists?.
1287
- # [collection.build(attributes = {}, ...)]
1326
+ # [<tt>collection.build(attributes = {}, ...)</tt>]
1288
1327
  # Returns one or more new objects of the collection type that have been instantiated
1289
1328
  # with +attributes+ and linked to this object through a foreign key, but have not yet
1290
1329
  # been saved.
1291
- # [collection.create(attributes = {})]
1330
+ # [<tt>collection.create(attributes = {})</tt>]
1292
1331
  # Returns a new object of the collection type that has been instantiated
1293
1332
  # with +attributes+, linked to this object through a foreign key, and that has already
1294
1333
  # been saved (if it passed the validation). *Note*: This only works if the base model
1295
1334
  # already exists in the DB, not if it is a new (unsaved) record!
1296
- # [collection.create!(attributes = {})]
1335
+ # [<tt>collection.create!(attributes = {})</tt>]
1297
1336
  # Does the same as <tt>collection.create</tt>, but raises ActiveRecord::RecordInvalid
1298
1337
  # if the record is invalid.
1299
- # [collection.reload]
1338
+ # [<tt>collection.reload</tt>]
1300
1339
  # Returns a Relation of all of the associated objects, forcing a database read.
1301
1340
  # An empty Relation is returned if none are found.
1302
1341
  #
1303
- # === Example
1304
- #
1305
- # A <tt>Firm</tt> class declares <tt>has_many :clients</tt>, which will add:
1306
- # * <tt>Firm#clients</tt> (similar to <tt>Client.where(firm_id: id)</tt>)
1307
- # * <tt>Firm#clients<<</tt>
1308
- # * <tt>Firm#clients.delete</tt>
1309
- # * <tt>Firm#clients.destroy</tt>
1310
- # * <tt>Firm#clients=</tt>
1311
- # * <tt>Firm#client_ids</tt>
1312
- # * <tt>Firm#client_ids=</tt>
1313
- # * <tt>Firm#clients.clear</tt>
1314
- # * <tt>Firm#clients.empty?</tt> (similar to <tt>firm.clients.size == 0</tt>)
1315
- # * <tt>Firm#clients.size</tt> (similar to <tt>Client.count "firm_id = #{id}"</tt>)
1316
- # * <tt>Firm#clients.find</tt> (similar to <tt>Client.where(firm_id: id).find(id)</tt>)
1317
- # * <tt>Firm#clients.exists?(name: 'ACME')</tt> (similar to <tt>Client.exists?(name: 'ACME', firm_id: firm.id)</tt>)
1318
- # * <tt>Firm#clients.build</tt> (similar to <tt>Client.new(firm_id: id)</tt>)
1319
- # * <tt>Firm#clients.create</tt> (similar to <tt>c = Client.new(firm_id: id); c.save; c</tt>)
1320
- # * <tt>Firm#clients.create!</tt> (similar to <tt>c = Client.new(firm_id: id); c.save!</tt>)
1321
- # * <tt>Firm#clients.reload</tt>
1342
+ # ==== Example
1343
+ #
1344
+ # class Firm < ActiveRecord::Base
1345
+ # has_many :clients
1346
+ # end
1347
+ #
1348
+ # Declaring <tt>has_many :clients</tt> adds the following methods (and more):
1349
+ #
1350
+ # firm = Firm.find(2)
1351
+ # client = Client.find(6)
1352
+ #
1353
+ # firm.clients # similar to Client.where(firm_id: 2)
1354
+ # firm.clients << client
1355
+ # firm.clients.delete(client)
1356
+ # firm.clients.destroy(client)
1357
+ # firm.clients = [client]
1358
+ # firm.client_ids
1359
+ # firm.client_ids = [6]
1360
+ # firm.clients.clear
1361
+ # firm.clients.empty? # similar to firm.clients.size == 0
1362
+ # firm.clients.size # similar to Client.count "firm_id = 2"
1363
+ # firm.clients.find # similar to Client.where(firm_id: 2).find(6)
1364
+ # firm.clients.exists?(name: 'ACME') # similar to Client.exists?(name: 'ACME', firm_id: 2)
1365
+ # firm.clients.build # similar to Client.new(firm_id: 2)
1366
+ # firm.clients.create # similar to Client.create(firm_id: 2)
1367
+ # firm.clients.create! # similar to Client.create!(firm_id: 2)
1368
+ # firm.clients.reload
1369
+ #
1322
1370
  # The declaration can also include an +options+ hash to specialize the behavior of the association.
1323
1371
  #
1324
- # === Scopes
1372
+ # ==== Scopes
1325
1373
  #
1326
1374
  # You can pass a second argument +scope+ as a callable (i.e. proc or
1327
1375
  # lambda) to retrieve a specific set of records or customize the generated
@@ -1332,7 +1380,7 @@ module ActiveRecord
1332
1380
  # has_many :employees, -> { joins(:address) }
1333
1381
  # has_many :posts, ->(blog) { where("max_post_length > ?", blog.max_post_length) }
1334
1382
  #
1335
- # === Extensions
1383
+ # ==== Extensions
1336
1384
  #
1337
1385
  # The +extension+ argument allows you to pass a block into a has_many
1338
1386
  # association. This is useful for adding new finders, creators, and other
@@ -1346,31 +1394,31 @@ module ActiveRecord
1346
1394
  # end
1347
1395
  # end
1348
1396
  #
1349
- # === Options
1350
- # [:class_name]
1397
+ # ==== Options
1398
+ # [+:class_name+]
1351
1399
  # Specify the class name of the association. Use it only if that name can't be inferred
1352
1400
  # from the association name. So <tt>has_many :products</tt> will by default be linked
1353
1401
  # to the +Product+ class, but if the real class name is +SpecialProduct+, you'll have to
1354
1402
  # specify it with this option.
1355
- # [:foreign_key]
1403
+ # [+:foreign_key+]
1356
1404
  # Specify the foreign key used for the association. By default this is guessed to be the name
1357
1405
  # of this class in lower-case and "_id" suffixed. So a Person class that makes a #has_many
1358
1406
  # association will use "person_id" as the default <tt>:foreign_key</tt>.
1359
1407
  #
1360
- # If you are going to modify the association (rather than just read from it), then it is
1361
- # a good idea to set the <tt>:inverse_of</tt> option.
1362
- # [:foreign_type]
1408
+ # Setting the <tt>:foreign_key</tt> option prevents automatic detection of the association's
1409
+ # inverse, so it is generally a good idea to set the <tt>:inverse_of</tt> option as well.
1410
+ # [+:foreign_type+]
1363
1411
  # Specify the column used to store the associated object's type, if this is a polymorphic
1364
1412
  # association. By default this is guessed to be the name of the polymorphic association
1365
1413
  # specified on "as" option with a "_type" suffix. So a class that defines a
1366
1414
  # <tt>has_many :tags, as: :taggable</tt> association will use "taggable_type" as the
1367
1415
  # default <tt>:foreign_type</tt>.
1368
- # [:primary_key]
1416
+ # [+:primary_key+]
1369
1417
  # Specify the name of the column to use as the primary key for the association. By default this is +id+.
1370
- # [:dependent]
1418
+ # [+:dependent+]
1371
1419
  # Controls what happens to the associated objects when
1372
1420
  # their owner is destroyed. Note that these are implemented as
1373
- # callbacks, and Rails executes callbacks in order. Therefore, other
1421
+ # callbacks, and \Rails executes callbacks in order. Therefore, other
1374
1422
  # similar callbacks may affect the <tt>:dependent</tt> behavior, and the
1375
1423
  # <tt>:dependent</tt> behavior may affect other callbacks.
1376
1424
  #
@@ -1382,7 +1430,7 @@ module ActiveRecord
1382
1430
  # * <tt>:delete_all</tt> causes all the associated objects to be deleted directly from the database (so callbacks will not be executed).
1383
1431
  # * <tt>:nullify</tt> causes the foreign keys to be set to +NULL+. Polymorphic type will also be nullified
1384
1432
  # on polymorphic associations. Callbacks are not executed.
1385
- # * <tt>:restrict_with_exception</tt> causes an <tt>ActiveRecord::DeleteRestrictionError</tt> exception to be raised if there are any associated records.
1433
+ # * <tt>:restrict_with_exception</tt> causes an ActiveRecord::DeleteRestrictionError exception to be raised if there are any associated records.
1386
1434
  # * <tt>:restrict_with_error</tt> causes an error to be added to the owner if there are any associated objects.
1387
1435
  #
1388
1436
  # If using with the <tt>:through</tt> option, the association on the join model must be
@@ -1394,12 +1442,12 @@ module ActiveRecord
1394
1442
  # <tt>has_many :comments, -> { where published: true }, dependent: :destroy</tt> and <tt>destroy</tt> is
1395
1443
  # called on a post, only published comments are destroyed. This means that any unpublished comments in the
1396
1444
  # database would still contain a foreign key pointing to the now deleted post.
1397
- # [:counter_cache]
1445
+ # [+:counter_cache+]
1398
1446
  # This option can be used to configure a custom named <tt>:counter_cache.</tt> You only need this option,
1399
1447
  # when you customized the name of your <tt>:counter_cache</tt> on the #belongs_to association.
1400
- # [:as]
1448
+ # [+:as+]
1401
1449
  # Specifies a polymorphic interface (See #belongs_to).
1402
- # [:through]
1450
+ # [+:through+]
1403
1451
  # Specifies an association through which to perform the query. This can be any other type
1404
1452
  # of association, including other <tt>:through</tt> associations. Options for <tt>:class_name</tt>,
1405
1453
  # <tt>:primary_key</tt> and <tt>:foreign_key</tt> are ignored, as the association uses the
@@ -1414,24 +1462,24 @@ module ActiveRecord
1414
1462
  # a good idea to set the <tt>:inverse_of</tt> option on the source association on the
1415
1463
  # join model. This allows associated records to be built which will automatically create
1416
1464
  # the appropriate join model records when they are saved. (See the 'Association Join Models'
1417
- # section above.)
1418
- # [:disable_joins]
1465
+ # and 'Setting Inverses' sections above.)
1466
+ # [+:disable_joins+]
1419
1467
  # Specifies whether joins should be skipped for an association. If set to true, two or more queries
1420
1468
  # will be generated. Note that in some cases, if order or limit is applied, it will be done in-memory
1421
1469
  # due to database limitations. This option is only applicable on <tt>has_many :through</tt> associations as
1422
1470
  # +has_many+ alone do not perform a join.
1423
- # [:source]
1471
+ # [+:source+]
1424
1472
  # Specifies the source association name used by #has_many <tt>:through</tt> queries.
1425
1473
  # Only use it if the name cannot be inferred from the association.
1426
1474
  # <tt>has_many :subscribers, through: :subscriptions</tt> will look for either <tt>:subscribers</tt> or
1427
1475
  # <tt>:subscriber</tt> on Subscription, unless a <tt>:source</tt> is given.
1428
- # [:source_type]
1476
+ # [+:source_type+]
1429
1477
  # Specifies type of the source association used by #has_many <tt>:through</tt> queries where the source
1430
1478
  # association is a polymorphic #belongs_to.
1431
- # [:validate]
1479
+ # [+:validate+]
1432
1480
  # When set to +true+, validates new objects added to association when saving the parent object. +true+ by default.
1433
1481
  # If you want to ensure associated objects are revalidated on every update, use +validates_associated+.
1434
- # [:autosave]
1482
+ # [+:autosave+]
1435
1483
  # If true, always save the associated objects or destroy them if marked for destruction,
1436
1484
  # when saving the parent object. If false, never save or destroy the associated objects.
1437
1485
  # By default, only save associated objects that are new records. This option is implemented as a
@@ -1440,20 +1488,29 @@ module ActiveRecord
1440
1488
  #
1441
1489
  # Note that NestedAttributes::ClassMethods#accepts_nested_attributes_for sets
1442
1490
  # <tt>:autosave</tt> to <tt>true</tt>.
1443
- # [:inverse_of]
1491
+ # [+:inverse_of+]
1444
1492
  # Specifies the name of the #belongs_to association on the associated object
1445
1493
  # that is the inverse of this #has_many association.
1446
1494
  # See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail.
1447
- # [:extend]
1495
+ # [+:extend+]
1448
1496
  # Specifies a module or array of modules that will be extended into the association object returned.
1449
1497
  # Useful for defining methods on associations, especially when they should be shared between multiple
1450
1498
  # association objects.
1451
- # [:strict_loading]
1499
+ # [+:strict_loading+]
1452
1500
  # When set to +true+, enforces strict loading every time the associated record is loaded through this
1453
1501
  # association.
1454
- # [:ensuring_owner_was]
1502
+ # [+:ensuring_owner_was+]
1455
1503
  # Specifies an instance method to be called on the owner. The method must return true in order for the
1456
1504
  # associated records to be deleted in a background job.
1505
+ # [+:query_constraints+]
1506
+ # Serves as a composite foreign key. Defines the list of columns to be used to query the associated object.
1507
+ # This is an optional option. By default Rails will attempt to derive the value automatically.
1508
+ # When the value is set the Array size must match associated model's primary key or +query_constraints+ size.
1509
+ # [+:index_errors+]
1510
+ # Enables differentiation of multiple validation errors from the association records, by including
1511
+ # an index in the error attribute name, e.g. +roles[2].level+.
1512
+ # The index is based on association order, i.e. database order, with yet to be
1513
+ # persisted new records placed at the end.
1457
1514
  #
1458
1515
  # Option examples:
1459
1516
  # has_many :comments, -> { order("posted_on") }
@@ -1466,6 +1523,8 @@ module ActiveRecord
1466
1523
  # has_many :subscribers, through: :subscriptions, source: :user
1467
1524
  # has_many :subscribers, through: :subscriptions, disable_joins: true
1468
1525
  # has_many :comments, strict_loading: true
1526
+ # has_many :comments, query_constraints: [:blog_id, :post_id]
1527
+ # has_many :comments, index_errors: true
1469
1528
  def has_many(name, scope = nil, **options, &extension)
1470
1529
  reflection = Builder::HasMany.build(self, name, scope, options, &extension)
1471
1530
  Reflection.add_reflection self, name, reflection
@@ -1481,37 +1540,48 @@ module ActiveRecord
1481
1540
  # +association+ is a placeholder for the symbol passed as the +name+ argument, so
1482
1541
  # <tt>has_one :manager</tt> would add among others <tt>manager.nil?</tt>.
1483
1542
  #
1484
- # [association]
1543
+ # [<tt>association</tt>]
1485
1544
  # Returns the associated object. +nil+ is returned if none is found.
1486
- # [association=(associate)]
1545
+ # [<tt>association=(associate)</tt>]
1487
1546
  # Assigns the associate object, extracts the primary key, sets it as the foreign key,
1488
1547
  # and saves the associate object. To avoid database inconsistencies, permanently deletes an existing
1489
1548
  # associated object when assigning a new one, even if the new one isn't saved to database.
1490
- # [build_association(attributes = {})]
1549
+ # [<tt>build_association(attributes = {})</tt>]
1491
1550
  # Returns a new object of the associated type that has been instantiated
1492
1551
  # with +attributes+ and linked to this object through a foreign key, but has not
1493
1552
  # yet been saved.
1494
- # [create_association(attributes = {})]
1553
+ # [<tt>create_association(attributes = {})</tt>]
1495
1554
  # Returns a new object of the associated type that has been instantiated
1496
1555
  # with +attributes+, linked to this object through a foreign key, and that
1497
1556
  # has already been saved (if it passed the validation).
1498
- # [create_association!(attributes = {})]
1557
+ # [<tt>create_association!(attributes = {})</tt>]
1499
1558
  # Does the same as <tt>create_association</tt>, but raises ActiveRecord::RecordInvalid
1500
1559
  # if the record is invalid.
1501
- # [reload_association]
1560
+ # [<tt>reload_association</tt>]
1502
1561
  # Returns the associated object, forcing a database read.
1562
+ # [<tt>reset_association</tt>]
1563
+ # Unloads the associated object. The next access will query it from the database.
1564
+ #
1565
+ # ==== Example
1566
+ #
1567
+ # class Account < ActiveRecord::Base
1568
+ # has_one :beneficiary
1569
+ # end
1570
+ #
1571
+ # Declaring <tt>has_one :beneficiary</tt> adds the following methods (and more):
1503
1572
  #
1504
- # === Example
1573
+ # account = Account.find(5)
1574
+ # beneficiary = Beneficiary.find(8)
1505
1575
  #
1506
- # An Account class declares <tt>has_one :beneficiary</tt>, which will add:
1507
- # * <tt>Account#beneficiary</tt> (similar to <tt>Beneficiary.where(account_id: id).first</tt>)
1508
- # * <tt>Account#beneficiary=(beneficiary)</tt> (similar to <tt>beneficiary.account_id = account.id; beneficiary.save</tt>)
1509
- # * <tt>Account#build_beneficiary</tt> (similar to <tt>Beneficiary.new(account_id: id)</tt>)
1510
- # * <tt>Account#create_beneficiary</tt> (similar to <tt>b = Beneficiary.new(account_id: id); b.save; b</tt>)
1511
- # * <tt>Account#create_beneficiary!</tt> (similar to <tt>b = Beneficiary.new(account_id: id); b.save!; b</tt>)
1512
- # * <tt>Account#reload_beneficiary</tt>
1576
+ # account.beneficiary # similar to Beneficiary.find_by(account_id: 5)
1577
+ # account.beneficiary = beneficiary # similar to beneficiary.update(account_id: 5)
1578
+ # account.build_beneficiary # similar to Beneficiary.new(account_id: 5)
1579
+ # account.create_beneficiary # similar to Beneficiary.create(account_id: 5)
1580
+ # account.create_beneficiary! # similar to Beneficiary.create!(account_id: 5)
1581
+ # account.reload_beneficiary
1582
+ # account.reset_beneficiary
1513
1583
  #
1514
- # === Scopes
1584
+ # ==== Scopes
1515
1585
  #
1516
1586
  # You can pass a second argument +scope+ as a callable (i.e. proc or
1517
1587
  # lambda) to retrieve a specific record or customize the generated query
@@ -1522,16 +1592,16 @@ module ActiveRecord
1522
1592
  # has_one :employer, -> { joins(:company) }
1523
1593
  # has_one :latest_post, ->(blog) { where("created_at > ?", blog.enabled_at) }
1524
1594
  #
1525
- # === Options
1595
+ # ==== Options
1526
1596
  #
1527
1597
  # The declaration can also include an +options+ hash to specialize the behavior of the association.
1528
1598
  #
1529
1599
  # Options are:
1530
- # [:class_name]
1600
+ # [+:class_name+]
1531
1601
  # Specify the class name of the association. Use it only if that name can't be inferred
1532
1602
  # from the association name. So <tt>has_one :manager</tt> will by default be linked to the Manager class, but
1533
1603
  # if the real class name is Person, you'll have to specify it with this option.
1534
- # [:dependent]
1604
+ # [+:dependent+]
1535
1605
  # Controls what happens to the associated object when
1536
1606
  # its owner is destroyed:
1537
1607
  #
@@ -1543,28 +1613,28 @@ module ActiveRecord
1543
1613
  # * <tt>:delete</tt> causes the associated object to be deleted directly from the database (so callbacks will not execute)
1544
1614
  # * <tt>:nullify</tt> causes the foreign key to be set to +NULL+. Polymorphic type column is also nullified
1545
1615
  # on polymorphic associations. Callbacks are not executed.
1546
- # * <tt>:restrict_with_exception</tt> causes an <tt>ActiveRecord::DeleteRestrictionError</tt> exception to be raised if there is an associated record
1616
+ # * <tt>:restrict_with_exception</tt> causes an ActiveRecord::DeleteRestrictionError exception to be raised if there is an associated record
1547
1617
  # * <tt>:restrict_with_error</tt> causes an error to be added to the owner if there is an associated object
1548
1618
  #
1549
1619
  # Note that <tt>:dependent</tt> option is ignored when using <tt>:through</tt> option.
1550
- # [:foreign_key]
1620
+ # [+:foreign_key+]
1551
1621
  # Specify the foreign key used for the association. By default this is guessed to be the name
1552
1622
  # of this class in lower-case and "_id" suffixed. So a Person class that makes a #has_one association
1553
1623
  # will use "person_id" as the default <tt>:foreign_key</tt>.
1554
1624
  #
1555
- # If you are going to modify the association (rather than just read from it), then it is
1556
- # a good idea to set the <tt>:inverse_of</tt> option.
1557
- # [:foreign_type]
1625
+ # Setting the <tt>:foreign_key</tt> option prevents automatic detection of the association's
1626
+ # inverse, so it is generally a good idea to set the <tt>:inverse_of</tt> option as well.
1627
+ # [+:foreign_type+]
1558
1628
  # Specify the column used to store the associated object's type, if this is a polymorphic
1559
1629
  # association. By default this is guessed to be the name of the polymorphic association
1560
1630
  # specified on "as" option with a "_type" suffix. So a class that defines a
1561
1631
  # <tt>has_one :tag, as: :taggable</tt> association will use "taggable_type" as the
1562
1632
  # default <tt>:foreign_type</tt>.
1563
- # [:primary_key]
1633
+ # [+:primary_key+]
1564
1634
  # Specify the method that returns the primary key used for the association. By default this is +id+.
1565
- # [:as]
1635
+ # [+:as+]
1566
1636
  # Specifies a polymorphic interface (See #belongs_to).
1567
- # [:through]
1637
+ # [+:through+]
1568
1638
  # Specifies a Join Model through which to perform the query. Options for <tt>:class_name</tt>,
1569
1639
  # <tt>:primary_key</tt>, and <tt>:foreign_key</tt> are ignored, as the association uses the
1570
1640
  # source reflection. You can only use a <tt>:through</tt> query through a #has_one
@@ -1579,49 +1649,53 @@ module ActiveRecord
1579
1649
  # a good idea to set the <tt>:inverse_of</tt> option on the source association on the
1580
1650
  # join model. This allows associated records to be built which will automatically create
1581
1651
  # the appropriate join model records when they are saved. (See the 'Association Join Models'
1582
- # section above.)
1583
- # [:disable_joins]
1652
+ # and 'Setting Inverses' sections above.)
1653
+ # [+:disable_joins+]
1584
1654
  # Specifies whether joins should be skipped for an association. If set to true, two or more queries
1585
1655
  # will be generated. Note that in some cases, if order or limit is applied, it will be done in-memory
1586
1656
  # due to database limitations. This option is only applicable on <tt>has_one :through</tt> associations as
1587
1657
  # +has_one+ alone does not perform a join.
1588
- # [:source]
1658
+ # [+:source+]
1589
1659
  # Specifies the source association name used by #has_one <tt>:through</tt> queries.
1590
1660
  # Only use it if the name cannot be inferred from the association.
1591
1661
  # <tt>has_one :favorite, through: :favorites</tt> will look for a
1592
1662
  # <tt>:favorite</tt> on Favorite, unless a <tt>:source</tt> is given.
1593
- # [:source_type]
1663
+ # [+:source_type+]
1594
1664
  # Specifies type of the source association used by #has_one <tt>:through</tt> queries where the source
1595
1665
  # association is a polymorphic #belongs_to.
1596
- # [:validate]
1666
+ # [+:validate+]
1597
1667
  # When set to +true+, validates new objects added to association when saving the parent object. +false+ by default.
1598
1668
  # If you want to ensure associated objects are revalidated on every update, use +validates_associated+.
1599
- # [:autosave]
1669
+ # [+:autosave+]
1600
1670
  # If true, always save the associated object or destroy it if marked for destruction,
1601
1671
  # when saving the parent object. If false, never save or destroy the associated object.
1602
1672
  # By default, only save the associated object if it's a new record.
1603
1673
  #
1604
1674
  # Note that NestedAttributes::ClassMethods#accepts_nested_attributes_for sets
1605
1675
  # <tt>:autosave</tt> to <tt>true</tt>.
1606
- # [:touch]
1676
+ # [+:touch+]
1607
1677
  # If true, the associated object will be touched (the +updated_at+ / +updated_on+ attributes set to current time)
1608
1678
  # when this record is either saved or destroyed. If you specify a symbol, that attribute
1609
1679
  # will be updated with the current time in addition to the +updated_at+ / +updated_on+ attribute.
1610
1680
  # Please note that no validation will be performed when touching, and only the +after_touch+,
1611
1681
  # +after_commit+, and +after_rollback+ callbacks will be executed.
1612
- # [:inverse_of]
1682
+ # [+:inverse_of+]
1613
1683
  # Specifies the name of the #belongs_to association on the associated object
1614
1684
  # that is the inverse of this #has_one association.
1615
1685
  # See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail.
1616
- # [:required]
1686
+ # [+:required+]
1617
1687
  # When set to +true+, the association will also have its presence validated.
1618
1688
  # This will validate the association itself, not the id. You can use
1619
1689
  # +:inverse_of+ to avoid an extra query during validation.
1620
- # [:strict_loading]
1690
+ # [+:strict_loading+]
1621
1691
  # Enforces strict loading every time the associated record is loaded through this association.
1622
- # [:ensuring_owner_was]
1692
+ # [+:ensuring_owner_was+]
1623
1693
  # Specifies an instance method to be called on the owner. The method must return true in order for the
1624
1694
  # associated records to be deleted in a background job.
1695
+ # [+:query_constraints+]
1696
+ # Serves as a composite foreign key. Defines the list of columns to be used to query the associated object.
1697
+ # This is an optional option. By default Rails will attempt to derive the value automatically.
1698
+ # When the value is set the Array size must match associated model's primary key or +query_constraints+ size.
1625
1699
  #
1626
1700
  # Option examples:
1627
1701
  # has_one :credit_card, dependent: :destroy # destroys the associated credit card
@@ -1636,6 +1710,7 @@ module ActiveRecord
1636
1710
  # has_one :primary_address, -> { where(primary: true) }, through: :addressables, source: :addressable
1637
1711
  # has_one :credit_card, required: true
1638
1712
  # has_one :credit_card, strict_loading: true
1713
+ # has_one :employment_record_book, query_constraints: [:organization_id, :employee_id]
1639
1714
  def has_one(name, scope = nil, **options)
1640
1715
  reflection = Builder::HasOne.build(self, name, scope, options)
1641
1716
  Reflection.add_reflection self, name, reflection
@@ -1652,42 +1727,52 @@ module ActiveRecord
1652
1727
  # +association+ is a placeholder for the symbol passed as the +name+ argument, so
1653
1728
  # <tt>belongs_to :author</tt> would add among others <tt>author.nil?</tt>.
1654
1729
  #
1655
- # [association]
1730
+ # [<tt>association</tt>]
1656
1731
  # Returns the associated object. +nil+ is returned if none is found.
1657
- # [association=(associate)]
1732
+ # [<tt>association=(associate)</tt>]
1658
1733
  # Assigns the associate object, extracts the primary key, and sets it as the foreign key.
1659
1734
  # No modification or deletion of existing records takes place.
1660
- # [build_association(attributes = {})]
1735
+ # [<tt>build_association(attributes = {})</tt>]
1661
1736
  # Returns a new object of the associated type that has been instantiated
1662
1737
  # with +attributes+ and linked to this object through a foreign key, but has not yet been saved.
1663
- # [create_association(attributes = {})]
1738
+ # [<tt>create_association(attributes = {})</tt>]
1664
1739
  # Returns a new object of the associated type that has been instantiated
1665
1740
  # with +attributes+, linked to this object through a foreign key, and that
1666
1741
  # has already been saved (if it passed the validation).
1667
- # [create_association!(attributes = {})]
1742
+ # [<tt>create_association!(attributes = {})</tt>]
1668
1743
  # Does the same as <tt>create_association</tt>, but raises ActiveRecord::RecordInvalid
1669
1744
  # if the record is invalid.
1670
- # [reload_association]
1745
+ # [<tt>reload_association</tt>]
1671
1746
  # Returns the associated object, forcing a database read.
1672
- # [association_changed?]
1747
+ # [<tt>reset_association</tt>]
1748
+ # Unloads the associated object. The next access will query it from the database.
1749
+ # [<tt>association_changed?</tt>]
1673
1750
  # Returns true if a new associate object has been assigned and the next save will update the foreign key.
1674
- # [association_previously_changed?]
1751
+ # [<tt>association_previously_changed?</tt>]
1675
1752
  # Returns true if the previous save updated the association to reference a new associate object.
1676
1753
  #
1677
- # === Example
1678
- #
1679
- # A Post class declares <tt>belongs_to :author</tt>, which will add:
1680
- # * <tt>Post#author</tt> (similar to <tt>Author.find(author_id)</tt>)
1681
- # * <tt>Post#author=(author)</tt> (similar to <tt>post.author_id = author.id</tt>)
1682
- # * <tt>Post#build_author</tt> (similar to <tt>post.author = Author.new</tt>)
1683
- # * <tt>Post#create_author</tt> (similar to <tt>post.author = Author.new; post.author.save; post.author</tt>)
1684
- # * <tt>Post#create_author!</tt> (similar to <tt>post.author = Author.new; post.author.save!; post.author</tt>)
1685
- # * <tt>Post#reload_author</tt>
1686
- # * <tt>Post#author_changed?</tt>
1687
- # * <tt>Post#author_previously_changed?</tt>
1688
- # The declaration can also include an +options+ hash to specialize the behavior of the association.
1754
+ # ==== Example
1755
+ #
1756
+ # class Post < ActiveRecord::Base
1757
+ # belongs_to :author
1758
+ # end
1759
+ #
1760
+ # Declaring <tt>belongs_to :author</tt> adds the following methods (and more):
1689
1761
  #
1690
- # === Scopes
1762
+ # post = Post.find(7)
1763
+ # author = Author.find(19)
1764
+ #
1765
+ # post.author # similar to Author.find(post.author_id)
1766
+ # post.author = author # similar to post.author_id = author.id
1767
+ # post.build_author # similar to post.author = Author.new
1768
+ # post.create_author # similar to post.author = Author.new; post.author.save; post.author
1769
+ # post.create_author! # similar to post.author = Author.new; post.author.save!; post.author
1770
+ # post.reload_author
1771
+ # post.reset_author
1772
+ # post.author_changed?
1773
+ # post.author_previously_changed?
1774
+ #
1775
+ # ==== Scopes
1691
1776
  #
1692
1777
  # You can pass a second argument +scope+ as a callable (i.e. proc or
1693
1778
  # lambda) to retrieve a specific record or customize the generated query
@@ -1698,37 +1783,39 @@ module ActiveRecord
1698
1783
  # belongs_to :user, -> { joins(:friends) }
1699
1784
  # belongs_to :level, ->(game) { where("game_level > ?", game.current_level) }
1700
1785
  #
1701
- # === Options
1786
+ # ==== Options
1702
1787
  #
1703
- # [:class_name]
1788
+ # The declaration can also include an +options+ hash to specialize the behavior of the association.
1789
+ #
1790
+ # [+:class_name+]
1704
1791
  # Specify the class name of the association. Use it only if that name can't be inferred
1705
1792
  # from the association name. So <tt>belongs_to :author</tt> will by default be linked to the Author class, but
1706
1793
  # if the real class name is Person, you'll have to specify it with this option.
1707
- # [:foreign_key]
1794
+ # [+:foreign_key+]
1708
1795
  # Specify the foreign key used for the association. By default this is guessed to be the name
1709
1796
  # of the association with an "_id" suffix. So a class that defines a <tt>belongs_to :person</tt>
1710
1797
  # association will use "person_id" as the default <tt>:foreign_key</tt>. Similarly,
1711
1798
  # <tt>belongs_to :favorite_person, class_name: "Person"</tt> will use a foreign key
1712
1799
  # of "favorite_person_id".
1713
1800
  #
1714
- # If you are going to modify the association (rather than just read from it), then it is
1715
- # a good idea to set the <tt>:inverse_of</tt> option.
1716
- # [:foreign_type]
1801
+ # Setting the <tt>:foreign_key</tt> option prevents automatic detection of the association's
1802
+ # inverse, so it is generally a good idea to set the <tt>:inverse_of</tt> option as well.
1803
+ # [+:foreign_type+]
1717
1804
  # Specify the column used to store the associated object's type, if this is a polymorphic
1718
1805
  # association. By default this is guessed to be the name of the association with a "_type"
1719
1806
  # suffix. So a class that defines a <tt>belongs_to :taggable, polymorphic: true</tt>
1720
1807
  # association will use "taggable_type" as the default <tt>:foreign_type</tt>.
1721
- # [:primary_key]
1808
+ # [+:primary_key+]
1722
1809
  # Specify the method that returns the primary key of associated object used for the association.
1723
1810
  # By default this is +id+.
1724
- # [:dependent]
1811
+ # [+:dependent+]
1725
1812
  # If set to <tt>:destroy</tt>, the associated object is destroyed when this object is. If set to
1726
1813
  # <tt>:delete</tt>, the associated object is deleted *without* calling its destroy method. If set to
1727
1814
  # <tt>:destroy_async</tt>, the associated object is scheduled to be destroyed in a background job.
1728
1815
  # This option should not be specified when #belongs_to is used in conjunction with
1729
1816
  # a #has_many relationship on another class because of the potential to leave
1730
1817
  # orphaned records behind.
1731
- # [:counter_cache]
1818
+ # [+:counter_cache+]
1732
1819
  # Caches the number of belonging objects on the associate class through the use of CounterCache::ClassMethods#increment_counter
1733
1820
  # and CounterCache::ClassMethods#decrement_counter. The counter cache is incremented when an object of this
1734
1821
  # class is created and decremented when it's destroyed. This requires that a column
@@ -1740,14 +1827,14 @@ module ActiveRecord
1740
1827
  # option (e.g., <tt>counter_cache: :my_custom_counter</tt>.)
1741
1828
  # Note: Specifying a counter cache will add it to that model's list of readonly attributes
1742
1829
  # using +attr_readonly+.
1743
- # [:polymorphic]
1830
+ # [+:polymorphic+]
1744
1831
  # Specify this association is a polymorphic association by passing +true+.
1745
1832
  # Note: If you've enabled the counter cache, then you may want to add the counter cache attribute
1746
1833
  # to the +attr_readonly+ list in the associated classes (e.g. <tt>class Post; attr_readonly :comments_count; end</tt>).
1747
- # [:validate]
1834
+ # [+:validate+]
1748
1835
  # When set to +true+, validates new objects added to association when saving the parent object. +false+ by default.
1749
1836
  # If you want to ensure associated objects are revalidated on every update, use +validates_associated+.
1750
- # [:autosave]
1837
+ # [+:autosave+]
1751
1838
  # If true, always save the associated object or destroy it if marked for destruction, when
1752
1839
  # saving the parent object.
1753
1840
  # If false, never save or destroy the associated object.
@@ -1755,32 +1842,37 @@ module ActiveRecord
1755
1842
  #
1756
1843
  # Note that NestedAttributes::ClassMethods#accepts_nested_attributes_for
1757
1844
  # sets <tt>:autosave</tt> to <tt>true</tt>.
1758
- # [:touch]
1845
+ # [+:touch+]
1759
1846
  # If true, the associated object will be touched (the +updated_at+ / +updated_on+ attributes set to current time)
1760
1847
  # when this record is either saved or destroyed. If you specify a symbol, that attribute
1761
1848
  # will be updated with the current time in addition to the +updated_at+ / +updated_on+ attribute.
1762
1849
  # Please note that no validation will be performed when touching, and only the +after_touch+,
1763
1850
  # +after_commit+, and +after_rollback+ callbacks will be executed.
1764
- # [:inverse_of]
1851
+ # [+:inverse_of+]
1765
1852
  # Specifies the name of the #has_one or #has_many association on the associated
1766
1853
  # object that is the inverse of this #belongs_to association.
1767
1854
  # See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail.
1768
- # [:optional]
1855
+ # [+:optional+]
1769
1856
  # When set to +true+, the association will not have its presence validated.
1770
- # [:required]
1857
+ # [+:required+]
1771
1858
  # When set to +true+, the association will also have its presence validated.
1772
1859
  # This will validate the association itself, not the id. You can use
1773
1860
  # +:inverse_of+ to avoid an extra query during validation.
1774
1861
  # NOTE: <tt>required</tt> is set to <tt>true</tt> by default and is deprecated. If
1775
1862
  # you don't want to have association presence validated, use <tt>optional: true</tt>.
1776
- # [:default]
1863
+ # [+:default+]
1777
1864
  # Provide a callable (i.e. proc or lambda) to specify that the association should
1778
1865
  # be initialized with a particular record before validation.
1779
- # [:strict_loading]
1866
+ # Please note that callable won't be executed if the record exists.
1867
+ # [+:strict_loading+]
1780
1868
  # Enforces strict loading every time the associated record is loaded through this association.
1781
- # [:ensuring_owner_was]
1869
+ # [+:ensuring_owner_was+]
1782
1870
  # Specifies an instance method to be called on the owner. The method must return true in order for the
1783
1871
  # associated records to be deleted in a background job.
1872
+ # [+:query_constraints+]
1873
+ # Serves as a composite foreign key. Defines the list of columns to be used to query the associated object.
1874
+ # This is an optional option. By default Rails will attempt to derive the value automatically.
1875
+ # When the value is set the Array size must match associated model's primary key or +query_constraints+ size.
1784
1876
  #
1785
1877
  # Option examples:
1786
1878
  # belongs_to :firm, foreign_key: "client_of"
@@ -1796,6 +1888,7 @@ module ActiveRecord
1796
1888
  # belongs_to :user, optional: true
1797
1889
  # belongs_to :account, default: -> { company.account }
1798
1890
  # belongs_to :account, strict_loading: true
1891
+ # belong_to :note, query_constraints: [:organization_id, :note_id]
1799
1892
  def belongs_to(name, scope = nil, **options)
1800
1893
  reflection = Builder::BelongsTo.build(self, name, scope, options)
1801
1894
  Reflection.add_reflection self, name, reflection
@@ -1818,7 +1911,7 @@ module ActiveRecord
1818
1911
  # The join table should not have a primary key or a model associated with it. You must manually generate the
1819
1912
  # join table with a migration such as this:
1820
1913
  #
1821
- # class CreateDevelopersProjectsJoinTable < ActiveRecord::Migration[7.0]
1914
+ # class CreateDevelopersProjectsJoinTable < ActiveRecord::Migration[7.1]
1822
1915
  # def change
1823
1916
  # create_join_table :developers, :projects
1824
1917
  # end
@@ -1833,71 +1926,80 @@ module ActiveRecord
1833
1926
  # +collection+ is a placeholder for the symbol passed as the +name+ argument, so
1834
1927
  # <tt>has_and_belongs_to_many :categories</tt> would add among others <tt>categories.empty?</tt>.
1835
1928
  #
1836
- # [collection]
1929
+ # [<tt>collection</tt>]
1837
1930
  # Returns a Relation of all the associated objects.
1838
1931
  # An empty Relation is returned if none are found.
1839
- # [collection<<(object, ...)]
1932
+ # [<tt>collection<<(object, ...)</tt>]
1840
1933
  # Adds one or more objects to the collection by creating associations in the join table
1841
1934
  # (<tt>collection.push</tt> and <tt>collection.concat</tt> are aliases to this method).
1842
1935
  # Note that this operation instantly fires update SQL without waiting for the save or update call on the
1843
1936
  # parent object, unless the parent object is a new record.
1844
- # [collection.delete(object, ...)]
1937
+ # [<tt>collection.delete(object, ...)</tt>]
1845
1938
  # Removes one or more objects from the collection by removing their associations from the join table.
1846
1939
  # This does not destroy the objects.
1847
- # [collection.destroy(object, ...)]
1940
+ # [<tt>collection.destroy(object, ...)</tt>]
1848
1941
  # Removes one or more objects from the collection by running destroy on each association in the join table, overriding any dependent option.
1849
1942
  # This does not destroy the objects.
1850
- # [collection=objects]
1943
+ # [<tt>collection=objects</tt>]
1851
1944
  # Replaces the collection's content by deleting and adding objects as appropriate.
1852
- # [collection_singular_ids]
1945
+ # [<tt>collection_singular_ids</tt>]
1853
1946
  # Returns an array of the associated objects' ids.
1854
- # [collection_singular_ids=ids]
1947
+ # [<tt>collection_singular_ids=ids</tt>]
1855
1948
  # Replace the collection by the objects identified by the primary keys in +ids+.
1856
- # [collection.clear]
1949
+ # [<tt>collection.clear</tt>]
1857
1950
  # Removes every object from the collection. This does not destroy the objects.
1858
- # [collection.empty?]
1951
+ # [<tt>collection.empty?</tt>]
1859
1952
  # Returns +true+ if there are no associated objects.
1860
- # [collection.size]
1953
+ # [<tt>collection.size</tt>]
1861
1954
  # Returns the number of associated objects.
1862
- # [collection.find(id)]
1955
+ # [<tt>collection.find(id)</tt>]
1863
1956
  # Finds an associated object responding to the +id+ and that
1864
1957
  # meets the condition that it has to be associated with this object.
1865
1958
  # Uses the same rules as ActiveRecord::FinderMethods#find.
1866
- # [collection.exists?(...)]
1959
+ # [<tt>collection.exists?(...)</tt>]
1867
1960
  # Checks whether an associated object with the given conditions exists.
1868
1961
  # Uses the same rules as ActiveRecord::FinderMethods#exists?.
1869
- # [collection.build(attributes = {})]
1962
+ # [<tt>collection.build(attributes = {})</tt>]
1870
1963
  # Returns a new object of the collection type that has been instantiated
1871
1964
  # with +attributes+ and linked to this object through the join table, but has not yet been saved.
1872
- # [collection.create(attributes = {})]
1965
+ # [<tt>collection.create(attributes = {})</tt>]
1873
1966
  # Returns a new object of the collection type that has been instantiated
1874
1967
  # with +attributes+, linked to this object through the join table, and that has already been
1875
1968
  # saved (if it passed the validation).
1876
- # [collection.reload]
1969
+ # [<tt>collection.reload</tt>]
1877
1970
  # Returns a Relation of all of the associated objects, forcing a database read.
1878
1971
  # An empty Relation is returned if none are found.
1879
1972
  #
1880
- # === Example
1881
- #
1882
- # A Developer class declares <tt>has_and_belongs_to_many :projects</tt>, which will add:
1883
- # * <tt>Developer#projects</tt>
1884
- # * <tt>Developer#projects<<</tt>
1885
- # * <tt>Developer#projects.delete</tt>
1886
- # * <tt>Developer#projects.destroy</tt>
1887
- # * <tt>Developer#projects=</tt>
1888
- # * <tt>Developer#project_ids</tt>
1889
- # * <tt>Developer#project_ids=</tt>
1890
- # * <tt>Developer#projects.clear</tt>
1891
- # * <tt>Developer#projects.empty?</tt>
1892
- # * <tt>Developer#projects.size</tt>
1893
- # * <tt>Developer#projects.find(id)</tt>
1894
- # * <tt>Developer#projects.exists?(...)</tt>
1895
- # * <tt>Developer#projects.build</tt> (similar to <tt>Project.new(developer_id: id)</tt>)
1896
- # * <tt>Developer#projects.create</tt> (similar to <tt>c = Project.new(developer_id: id); c.save; c</tt>)
1897
- # * <tt>Developer#projects.reload</tt>
1973
+ # ==== Example
1974
+ #
1975
+ # class Developer < ActiveRecord::Base
1976
+ # has_and_belongs_to_many :projects
1977
+ # end
1978
+ #
1979
+ # Declaring <tt>has_and_belongs_to_many :projects</tt> adds the following methods (and more):
1980
+ #
1981
+ # developer = Developer.find(11)
1982
+ # project = Project.find(9)
1983
+ #
1984
+ # developer.projects
1985
+ # developer.projects << project
1986
+ # developer.projects.delete(project)
1987
+ # developer.projects.destroy(project)
1988
+ # developer.projects = [project]
1989
+ # developer.project_ids
1990
+ # developer.project_ids = [9]
1991
+ # developer.projects.clear
1992
+ # developer.projects.empty?
1993
+ # developer.projects.size
1994
+ # developer.projects.find(9)
1995
+ # developer.projects.exists?(9)
1996
+ # developer.projects.build # similar to Project.new(developer_id: 11)
1997
+ # developer.projects.create # similar to Project.create(developer_id: 11)
1998
+ # developer.projects.reload
1999
+ #
1898
2000
  # The declaration may include an +options+ hash to specialize the behavior of the association.
1899
2001
  #
1900
- # === Scopes
2002
+ # ==== Scopes
1901
2003
  #
1902
2004
  # You can pass a second argument +scope+ as a callable (i.e. proc or
1903
2005
  # lambda) to retrieve a specific set of records or customize the generated
@@ -1909,7 +2011,7 @@ module ActiveRecord
1909
2011
  # where("default_category = ?", post.default_category)
1910
2012
  # }
1911
2013
  #
1912
- # === Extensions
2014
+ # ==== Extensions
1913
2015
  #
1914
2016
  # The +extension+ argument allows you to pass a block into a
1915
2017
  # has_and_belongs_to_many association. This is useful for adding new
@@ -1924,33 +2026,33 @@ module ActiveRecord
1924
2026
  # end
1925
2027
  # end
1926
2028
  #
1927
- # === Options
2029
+ # ==== Options
1928
2030
  #
1929
- # [:class_name]
2031
+ # [+:class_name+]
1930
2032
  # Specify the class name of the association. Use it only if that name can't be inferred
1931
2033
  # from the association name. So <tt>has_and_belongs_to_many :projects</tt> will by default be linked to the
1932
2034
  # Project class, but if the real class name is SuperProject, you'll have to specify it with this option.
1933
- # [:join_table]
2035
+ # [+:join_table+]
1934
2036
  # Specify the name of the join table if the default based on lexical order isn't what you want.
1935
2037
  # <b>WARNING:</b> If you're overwriting the table name of either class, the +table_name+ method
1936
2038
  # MUST be declared underneath any #has_and_belongs_to_many declaration in order to work.
1937
- # [:foreign_key]
2039
+ # [+:foreign_key+]
1938
2040
  # Specify the foreign key used for the association. By default this is guessed to be the name
1939
2041
  # of this class in lower-case and "_id" suffixed. So a Person class that makes
1940
2042
  # a #has_and_belongs_to_many association to Project will use "person_id" as the
1941
2043
  # default <tt>:foreign_key</tt>.
1942
2044
  #
1943
- # If you are going to modify the association (rather than just read from it), then it is
1944
- # a good idea to set the <tt>:inverse_of</tt> option.
1945
- # [:association_foreign_key]
2045
+ # Setting the <tt>:foreign_key</tt> option prevents automatic detection of the association's
2046
+ # inverse, so it is generally a good idea to set the <tt>:inverse_of</tt> option as well.
2047
+ # [+:association_foreign_key+]
1946
2048
  # Specify the foreign key used for the association on the receiving side of the association.
1947
2049
  # By default this is guessed to be the name of the associated class in lower-case and "_id" suffixed.
1948
2050
  # So if a Person class makes a #has_and_belongs_to_many association to Project,
1949
2051
  # the association will use "project_id" as the default <tt>:association_foreign_key</tt>.
1950
- # [:validate]
2052
+ # [+:validate+]
1951
2053
  # When set to +true+, validates new objects added to association when saving the parent object. +true+ by default.
1952
2054
  # If you want to ensure associated objects are revalidated on every update, use +validates_associated+.
1953
- # [:autosave]
2055
+ # [+:autosave+]
1954
2056
  # If true, always save the associated objects or destroy them if marked for destruction, when
1955
2057
  # saving the parent object.
1956
2058
  # If false, never save or destroy the associated objects.
@@ -1958,7 +2060,7 @@ module ActiveRecord
1958
2060
  #
1959
2061
  # Note that NestedAttributes::ClassMethods#accepts_nested_attributes_for sets
1960
2062
  # <tt>:autosave</tt> to <tt>true</tt>.
1961
- # [:strict_loading]
2063
+ # [+:strict_loading+]
1962
2064
  # Enforces strict loading every time an associated record is loaded through this association.
1963
2065
  #
1964
2066
  # Option examples: