Note: This was originally written before Rails added support for native enums. See the comments in version support.
The enum feature in Rails has bad developer ergonomics. It uses integer types at the DB layer, which means trying to understand SQL output is a pain.
Using the easy form of the helper syntax is a minor footgun:
enum status: %w[new active archived]It's not obvious that the above code is order-dependent, but if you decide to add a new enum anywhere but the end, you're in trouble.
If you choose the use varchar fields instead, now you have to write annoying check constraints and lose the efficient storage.
enum status: { new: "new", active: "active", archived: "archived" }Nobody has time to write that nonsense.
Did you know you can define your own types in PostgreSQL? You can, and this type system also supports enumeration.
CREATE TYPE status_type AS ENUM ('new', 'active', 'archived');Not only does this give you full type safety at the DB layer, the implementation is highly efficient. An enum value only takes up four bytes.
The best part is that PostgreSQL supports inserting new values at any point of the list without having to migrate your data.
ALTER TYPE status_type ADD VALUE 'pending' BEFORE 'active';The principle motivation of this gem is to seamlessly integrate PG enums into your schema.rb file. This means you can use them in your database columns without switching to structure.sql.
ActiveRecord::Schema.define(version: 2019_06_19_214914) do
# These are extensions that must be enabled in order to support this database
enable_extension "plpgsql"
create_enum "status_type", %w[new pending active archived]
create_table "orders", id: :serial, force: :cascade do |t|
t.enum "status", as: "status_type", default: "new"
end
endEvery version of Rails with an enum macro is supported. This means 4.1 through master. Yes, this was annoying and difficult.
The monkeypatches in this library are extremely narrow and contained; the dirty hacks I had to do to make 4.1 work, for instance, have no impact on 6.0.
Monkeypatching Rails internals is scary. So this library has a comprehensive test suite that runs against every known minor version.
Rails 7 added support for native enums, but they have so far neglected to support altering or dropping enums in the API, so this gem remains to fill in the gaps. I expect to slowly deprecate this over time.
Add this line to your application's Gemfile:
gem 'activerecord-pg_enum'And then execute:
$ bundle
Defining a new ENUM
class AddContactMethodType < ActiveRecord::Migration[5.2]
def up
create_enum "contact_method_type", %w[Email Phone]
end
def down
drop_enum "contact_method_type"
end
endAdding a value to an existing ENUM (you must disable the wrapping transaction on PostgreSQL versions older than 12)
class AddSMSToContactMethodType < ActiveRecord::Migration[5.2]
disable_ddl_transaction!
def up
add_enum_value "contact_method_type", "SMS", before: "Phone"
end
def down
raise ActiveRecord::IrreversibleMigration
end
endAdding an enum column to a table
class AddStatusToOrder < ActiveRecord::Migration[5.2]
def change
change_table :orders do |t|
t.enum :status, as: "status_type", default: "new"
end
end
endRenaming an enum type
class RenameStatusType < ActiveRecord::Migration[6.0]
def change
rename_enum "status_type", to: "order_status_type"
end
endALTER TYPE status_type RENAME TO order_status_type;PostgreSQL 10+ required:
Changing an enum label
class ChangeStatusHoldLabel < ActiveRecord::Migration[6.0]
def change
rename_enum_value "status_type", from: "on hold", to: "OnHold"
end
endALTER TYPE status_type RENAME VALUE 'on hold' TO 'OnHold';class ContactInfo < ActiveRecord::Base
include PGEnum(contact_method: %w[Email SMS Phone])
endThe generated module calls the official enum method converting array syntax into strings. The above example is equivalent to:
class ContactInfo < ActiveRecord::Base
enum contact_method: { Email: "Email", SMS: "SMS", Phone: "Phone" }
endAdditionally, enum options are fully supported, for example
class User < ActiveRecord::Base
include PGEnum(status: %w[active inactive deleted], _prefix: 'user', _suffix: true)
endis equivalent to
class User < ActiveRecord::Base
enum status: { active: 'active', inactive: 'inactive', deleted: 'deleted' }, _prefix: 'user', _suffix: true
endThere's no technical reason why you couldn't detect enum columns at startup time and automatically do this wireup, but I feel that the benefit of self-documenting outweighs the convenience.
After checking out the repo, run bin/setup to install dependencies. Then, run appraisal rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
Test a specific version with appraisal 6.0 rake spec. This is usually necessary because different versions have different Ruby version support.
To install this gem onto your local machine, run bundle exec rake install.
Bug reports and pull requests are welcome on GitHub at https://github.com/alassek/activerecord-pg_enum.
The gem is available as open source under the terms of the MIT License.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent