The 3 kinds of Enum in Rails

Enums are a very useful concept. It's like a locked list of choices where only a few specific values are allowed, and nothing else. Enums work well for any place where you need a limited, known list of values for something, like:

• status (with values like "pending," "active," and "archived")
• role (with values like "admin," "user," and "guest")
• difficulty_level (with values like "easy," "medium," and "hard")

See docs on Rails' enum macro.

Enums allow more choices of values than booleans, and are more constrained than strings.

Using string columns for enum values is known to be too permissive. Eventually letter case and random whitespace problems creep into the dataset. Sidestep issues by using appropriate data type - enum!

Let me present three approaches to defining enums in Rails.

Integer-based Enums (easy)

Integer-based enums are easy to define, use and extend:

# in migration
create_table :jobs do |t|
  t.integer :status, null: false, default: 0
end

# in model
enum status: { pending: 0, completed: 1, errored: 2 }

Adding a new possible status is easy - add new key-value pairs, but be sure not to change the existing mappings.

enum status: { pending: 0, completed: 1, errored: 2, processing: 3 }

You can even skip some integers to have subgroups. Here we're placing errors in the 90s, and leaving integers 3-8 for possible additions.

enum status: {
  pending: 0, processing: 1, completed: 2,
  errored_hard: 91,
  errored_with_retry: 92  
}

DB-level Enums (hard-er)

Postgres supports database-level enum definition. This approach is more easy to read (queries have human-readable values, not cryptic integers), but harder to maintain - changing values requires a database migration, not just code change.

# in migration
create_enum :job_status, ["pending", "completed", "errored"]

create_table :jobs do |t|
  t.enum :status, null: false, default: "pending", enum_type: "job_status"
end

# in model
enum status: { pending: "pending", completed: "completed", errored: "errored" }

String Enums (discouraged)

If you need the flexibility of permitting new values without changes to code, such as user-defined types, and are OK with taking on the dataset pollution risk, and then string enums can be an option.
It's basically using just a string column, so very few native constraints on the database level for the values users can write. I recommend adding CHECK constraints, for example, allow only lowercase latin letters and underscores, to have some semblance of data integrity on the database level, and a dynamic validation in app code, so forms can show validation errors etc.

# in migration
create_table :jobs do |t|
  t.string :status, null: false, default: "pending"
end

# in model, just define a validation
validate :validate_status_in_supported_list

def validate_status_in_supported_list
  return unless status_changed?

  # here the dynamic source of allowed values can be anything - database, remote requests, file read etc.
  allowed_statuses = SomeSource.allowed_statuses

  return if allowed_statuses.include?(status)

  errors.add(:status, :inclusion)
end

Comments

[Paweł Świątkowski]

I usually encourage using string-based enums unless there's very good reason not to. I really don't like integer-based ones, because they are useless to reason without having the application code at hand (for example, and usually, when querying database directly).

DB-based are a nice middle ground, but require a migration every time you add a new value to enum (which I don't like) and down migrations are especially complicated.