Declare an enum attribute where the values map to integers in the database, but can be queried by name. Example:
classConversation<ActiveRecord::Baseenum:status, [:active,:archived ]end# conversation.update! status: 0conversation.active!conversation.active?# => trueconversation.status# => "active"# conversation.update! status: 1conversation.archived!conversation.archived?# => trueconversation.status# => "archived"# conversation.status = 1conversation.status ="archived"conversation.status =nilconversation.status.nil?# => trueconversation.status# => nil
Scopes based on the allowed values of the enum field will be provided as well. With the above example:
Conversation.activeConversation.not_activeConversation.archivedConversation.not_archived
Of course, you can also query them directly if the scopes don’t fit your needs:
Conversation.where(status: [:active,:archived])Conversation.where.not(status::active)
Defining scopes can be disabled by setting:scopes tofalse.
classConversation<ActiveRecord::Baseenum:status, [:active,:archived ],scopes:falseend
You can set the default enum value by setting:default, like:
classConversation<ActiveRecord::Baseenum:status, [:active,:archived ],default::activeendconversation =Conversation.newconversation.status# => "active"
It’s possible to explicitly map the relation between attribute and database integer with a hash:
classConversation<ActiveRecord::Baseenum:status,active:0,archived:1end
Finally it’s also possible to use a string column to persist the enumerated value. Note that this will likely lead to slower database queries:
classConversation<ActiveRecord::Baseenum:status,active:"active",archived:"archived"end
Note that when an array is used, the implicit mapping from the values to database integers is derived from the order the values appear in the array. In the example,:active is mapped to0 as it’s the first element, and:archived is mapped to1. In general, thei-th element is mapped toi-1 in the database.
Therefore, once a value is added to the enum array, its position in the array must be maintained, and new values should only be added to the end of the array. To remove unused values, the explicit hash syntax should be used.
In rare circumstances you might need to access the mapping directly. The mappings are exposed through a class method with the pluralized attribute name, which return the mapping in aActiveSupport::HashWithIndifferentAccess :
Conversation.statuses[:active]# => 0Conversation.statuses["archived"]# => 1
Use that class method when you need to know the ordinal value of an enum. For example, you can use that when manually building SQL strings:
Conversation.where("status <> ?",Conversation.statuses[:archived])
You can use the:prefix or:suffix options when you need to define multiple enums with same values. If the passed value istrue, the methods are prefixed/suffixed with the name of the enum. It is also possible to supply a custom value:
classConversation<ActiveRecord::Baseenum:status, [:active,:archived ],suffix:trueenum:comments_status, [:active,:inactive ],prefix::commentsend
With the above example, the bang and predicate methods along with the associated scopes are now prefixed and/or suffixed accordingly:
conversation.active_status!conversation.archived_status?# => falseconversation.comments_inactive!conversation.comments_active?# => false
If you want to disable the auto-generated methods on the model, you can do so by setting the:instance_methods option to false:
classConversation<ActiveRecord::Baseenum:status, [:active,:archived ],instance_methods:falseend
By default, anArgumentError will be raised when assigning an invalid value:
classConversation<ActiveRecord::Baseenum:status, [:active,:archived ]endconversation =Conversation.newconversation.status =:unknown# 'unknown' is not a valid status (ArgumentError)
If, instead, you want the enum value to be validated before saving, use the:validate option:
classConversation<ActiveRecord::Baseenum:status, [:active,:archived ],validate:trueendconversation =Conversation.newconversation.status =:unknownconversation.valid?# => falseconversation.status =nilconversation.valid?# => falseconversation.status =:activeconversation.valid?# => true
You may also pass additional validation options:
classConversation<ActiveRecord::Baseenum:status, [:active,:archived ],validate: {allow_nil:true }endconversation =Conversation.newconversation.status =:unknownconversation.valid?# => falseconversation.status =nilconversation.valid?# => trueconversation.status =:activeconversation.valid?# => true
- E