ActiveRecord::PGEnum ![Build Status](https://circleci.com/gh/alassek/activerecord-pg_enum.svg?style=shield)
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.
Enumerated Types: The Best of Both Worlds
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';
schema.rb Support
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
end
Version support
Every 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.
Installation
Add this line to your application's Gemfile:
gem 'activerecord-pg_enum'
And then execute:
$ bundle
Usage
Migrations
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
end
Adding 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
end
Adding 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
end
Renaming an enum type
class RenameStatusType < ActiveRecord::Migration[6.0]
def change
rename_enum "status_type", to: "order_status_type"
end
end
ALTER 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
end
ALTER TYPE status_type RENAME VALUE 'on hold' TO 'OnHold';
Module Builder
class ContactInfo < ActiveRecord::Base
include PGEnum(contact_method: %w[Email SMS Phone])
end
The 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" }
end
Additionally, enum
options are fully supported, for example
class User < ActiveRecord::Base
include PGEnum(status: %w[active inactive deleted], _prefix: 'user', _suffix: true)
end
is equivalent to
class User < ActiveRecord::Base
enum status: { active: 'active', inactive: 'inactive', deleted: 'deleted' }, _prefix: 'user', _suffix: true
end
There'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.
Development
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
.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/alassek/activerecord-pg_enum.
License
The gem is available as open source under the terms of the MIT License.