- V
Instance Public methods
validates_absence_of(*attr_names) Link
Validates that the specified attributes are not present (as defined by Object#present?
). If the attribute is an association, the associated object is also considered not present if it is marked for destruction.
See ActiveModel::Validations::HelperMethods.validates_absence_of
for more information.
validates_associated(*attr_names) Link
Validates whether the associated object or objects are all valid. Works with any kind of association.
class Book < ActiveRecord::Base
has_many :pages
belongs_to :library
validates_associated :pages, :library
end
WARNING: This validation must not be used on both ends of an association. Doing so will lead to a circular dependency and cause infinite recursion.
NOTE: This validation will not fail if the association hasn’t been assigned. If you want to ensure that the association is both present and guaranteed to be valid, you also need to use validates_presence_of.
Configuration options:
-
:message
- A custom error message (default is: “is invalid”). -
:on
- Specifies the contexts where this validation is active. Runs in all validation contexts by defaultnil
. You can pass a symbol or an array of symbols. (e.g.on: :create
oron: :custom_validation_context
oron: [:create, :custom_validation_context]
) -
:if
- Specifies a method, proc, or string to call to determine if the validation should occur (e.g.if: :allow_validation
, orif: Proc.new { |user| user.signup_step > 2 }
). The method, proc or string should return or evaluate to atrue
orfalse
value. -
:unless
- Specifies a method, proc, or string to call to determine if the validation should not occur (e.g.unless: :skip_validation
, orunless: Proc.new { |user| user.signup_step <= 2 }
). The method, proc, or string should return or evaluate to atrue
orfalse
value.
validates_length_of(*attr_names) Link
Validates that the specified attributes match the length restrictions supplied. If the attribute is an association, records that are marked for destruction are not counted.
See ActiveModel::Validations::HelperMethods.validates_length_of
for more information.
validates_numericality_of(*attr_names) Link
Validates whether the value of the specified attribute is numeric by trying to convert it to a float with Kernel.Float
(if only_integer
is false
) or applying it to the regular expression /\A[+\-]?\d+\z/
(if only_integer
is set to true
). Kernel.Float
precision defaults to the column’s precision value or 15.
See ActiveModel::Validations::HelperMethods.validates_numericality_of
for more information.
validates_presence_of(*attr_names) Link
Validates that the specified attributes are not blank (as defined by Object#blank?
). If the attribute is an association, the associated object is also considered blank if it is marked for destruction.
class Person < ActiveRecord::Base
has_one :face
validates_presence_of :face
end
The face attribute must be in the object and it cannot be blank or marked for destruction.
This validator defers to the Active Model validation for presence, adding the check to see that an associated object is not marked for destruction. This prevents the parent object from validating successfully and saving, which then deletes the associated object, thus putting the parent object into an invalid state.
See ActiveModel::Validations::HelperMethods.validates_presence_of
for more information.
NOTE: This validation will not fail while using it with an association if the latter was assigned but not valid. If you want to ensure that it is both present and valid, you also need to use validates_associated.
validates_uniqueness_of(*attr_names) Link
Validates whether the value of the specified attributes are unique across the system. Useful for making sure that only one user can be named “davidhh”.
class Person < ActiveRecord::Base
validates_uniqueness_of :user_name
end
It can also validate whether the value of the specified attributes are unique based on a :scope
parameter:
class Person < ActiveRecord::Base
validates_uniqueness_of :user_name, scope: :account_id
end
Or even multiple scope parameters. For example, making sure that a teacher can only be on the schedule once per semester for a particular class.
class TeacherSchedule < ActiveRecord::Base
validates_uniqueness_of :teacher_id, scope: [:semester_id, :class_id]
end
It is also possible to limit the uniqueness constraint to a set of records matching certain conditions. In this example archived articles are not being taken into consideration when validating uniqueness of the title attribute:
class Article < ActiveRecord::Base
validates_uniqueness_of :title, conditions: -> { where.not(status: 'archived') }
end
To build conditions based on the record’s state, define the conditions callable with a parameter, which will be the record itself. This example validates the title is unique for the year of publication:
class Article < ActiveRecord::Base
validates_uniqueness_of :title, conditions: ->(article) {
published_at = article.published_at
where(published_at: published_at.beginning_of_year..published_at.end_of_year)
}
end
When the record is created, a check is performed to make sure that no record exists in the database with the given value for the specified attribute (that maps to a column). When the record is updated, the same check is made but disregarding the record itself.
Configuration options:
-
:message
- Specifies a custom error message (default is: “has already been taken”). -
:scope
- One or more columns by which to limit the scope of the uniqueness constraint. -
:conditions
- Specify the conditions to be included as aWHERE
SQL fragment to limit the uniqueness constraint lookup (e.g.conditions: -> { where(status: 'active') }
). -
:case_sensitive
- Looks for an exact match. Ignored by non-text columns. The default behavior respects the default database collation. -
:allow_nil
- If set totrue
, skips this validation if the attribute isnil
(default isfalse
). -
:allow_blank
- If set totrue
, skips this validation if the attribute is blank (default isfalse
). -
:if
- Specifies a method, proc, or string to call to determine if the validation should occur (e.g.if: :allow_validation
, orif: Proc.new { |user| user.signup_step > 2 }
). The method, proc or string should return or evaluate to atrue
orfalse
value. -
:unless
- Specifies a method, proc, or string to call to determine if the validation should not occur (e.g.unless: :skip_validation
, orunless: Proc.new { |user| user.signup_step <= 2 }
). The method, proc, or string should return or evaluate to atrue
orfalse
value.
Concurrency and integrity
Using this validation method in conjunction with ActiveRecord::Base#save does not guarantee the absence of duplicate record insertions, because uniqueness checks on the application level are inherently prone to race conditions. For example, suppose that two users try to post a Comment at the same time, and a Comment’s title must be unique. At the database-level, the actions performed by these users could be interleaved in the following manner:
User 1 | User 2
------------------------------------+--------------------------------------
# User 1 checks whether there's |
# already a comment with the title |
# 'My Post'. This is not the case. |
SELECT * FROM comments |
WHERE title = 'My Post' |
|
| # User 2 does the same thing and also
| # infers that their title is unique.
| SELECT * FROM comments
| WHERE title = 'My Post'
|
# User 1 inserts their comment. |
INSERT INTO comments |
(title, content) VALUES |
('My Post', 'hi!') |
|
| # User 2 does the same thing.
| INSERT INTO comments
| (title, content) VALUES
| ('My Post', 'hello!')
|
| # ^^^^^^
| # Boom! We now have a duplicate
| # title!
The best way to work around this problem is to add a unique index to the database table using connection.add_index. In the rare case that a race condition occurs, the database will guarantee the field’s uniqueness.
When the database catches such a duplicate insertion, ActiveRecord::Base#save will raise an ActiveRecord::StatementInvalid
exception. You can either choose to let this error propagate (which will result in the default Rails exception page being shown), or you can catch it and restart the transaction (e.g. by telling the user that the title already exists, and asking them to re-enter the title). This technique is also known as optimistic concurrency control.
The bundled ActiveRecord::ConnectionAdapters distinguish unique index constraint errors from other types of database errors by throwing an ActiveRecord::RecordNotUnique
exception. For other adapters you will have to parse the (database-specific) exception message to detect such a case.
The following bundled adapters throw the ActiveRecord::RecordNotUnique
exception: