I’ll demonstrate on a PostgreSQL container with a simple table. I’ll be using Podman. You can also use Docker to follow along, just replace podman with docker in the commands.

Make sure Podman/Docker is running, then run the following to get a running PostgreSQL container locally:

podman run -d --name enum-demo -e POSTGRES_PASSWORD=postgres docker.io/library/postgres:18

Then exec into the running container:

$ podman exec -it enum-demo psql -U postgres
psql (18.6 (Debian 18.6-1.pgdg13+2))
Type "help" for help.

postgres=#

Now we can start setting up the table to try out enums. First, we’ll create the enum type itself. It’s going to be a type just like INTEGER or TEXT are types in a database. I’m thinking of CI/CD pipelines to use as an example, so the enum will be called pipeline_status and it’ll only accept the values pending, running, succeeded, and failed. Run this SQL query in the container:

CREATE TYPE pipeline_status AS ENUM ('pending', 'running', 'succeeded', 'failed');

PostgreSQL should return:

CREATE TYPE

Now let’s create a simple table that makes use of the enum. The table will be called pipeline_runs and it’ll have two columns: branch of type TEXT, and status which uses our enum type pipeline_status. Run this in the container:

CREATE TABLE pipeline_runs (
  branch TEXT,
  status pipeline_status
);

PostgreSQL should return:

CREATE TABLE

Now let’s try inserting a row. This SQL query inserts a row where branch is main and status is one of the four predefined enum values (running).

INSERT INTO pipeline_runs (branch, status) VALUES ('main', 'running');

PostgreSQL replies:

INSERT 0 1

We can check for the newly created row:

SELECT * FROM pipeline_runs;

You should see:

 branch | status
--------+---------
 main   | running
(1 row)

Now let’s try inserting a row with an enum value that is not a part of the values we defined. We’ll try inserting cancelled for the status column. We should get an error.

INSERT INTO pipeline_runs (branch, status) VALUES ('main', 'cancelled');

PostgreSQL should say:

ERROR:  invalid input value for enum pipeline_status: "cancelled"
LINE 1: ...TO pipeline_runs (branch, status) VALUES ('main', 'cancelled...
                                                             ^

The cancelled value isn’t one of ('pending', 'running', 'succeeded', 'failed'), so PostgreSQL gives us an error. PostgreSQL itself is enforcing enums! No ORMs here.

Note that the values in the enum are case sensitive. So inserting Pending instead of pending will fail:

INSERT INTO pipeline_runs (branch, status) VALUES ('main', 'Pending');

PostgreSQL returns the error:

ERROR:  invalid input value for enum pipeline_status: "Pending"
LINE 1: ...TO pipeline_runs (branch, status) VALUES ('main', 'Pending')...
                                                             ^

Another caveat is that inserting NULL as the value for status is still allowed unless the column is also created with NOT NULL.

Let’s say we actually want cancelled to be a part of the enum. We can modify the enum like so:

ALTER TYPE pipeline_status ADD VALUE 'cancelled';

PostgreSQL responds with:

ALTER TYPE

Now that cancelled is a valid value, we can try inserting again and we won’t get an error:

INSERT INTO pipeline_runs (branch, status) VALUES ('main', 'cancelled');

PostgreSQL responds with:

INSERT 0 1

We should have two rows total now. We can double check:

SELECT * FROM pipeline_runs;

You should see:

 branch |  status
--------+-----------
 main   | running
 main   | cancelled
(2 rows)

We successfully added a value to the pipeline_status enum and used it in a new row.

One final note: there isn’t a clean way to remove a value from an enum. You can add values, but you would need to rebuild the enum if you want to remove any values. Plan ahead!

Now that the demo is over, exit the PostgreSQL prompt by running:

\q

Then clean up the container and, optionally, the image:

$ podman rm -f enum-demo
enum-demo

$ podman rmi docker.io/library/postgres:18
Untagged: docker.io/library/postgres:18
Deleted: 07ee628d2e71f8956c85fc5466906a6d4038cf00f6db07f067d810ef8fec8161

We created an enum type with predefined values, tried inserting both valid and invalid values, and it was all enforced at the database level with no abstractions from an ORM!

Defining a Uniqueness Constraint in the Migration

Creating a uniqueness constraint in a migration requires us to add an index on two columns/attributes. The key here is to place the attributes in an array and set them to be unique as a pair. The line in the migration looks like this:

t.index [:attribute, :another_attribute], unique: true

Here’s a more realistic example. Assume the following:

• We have an existing Account model
• We want to create a new table for a Statement model.
• An account can have many statements
• A statement belongs to one account
• We want a maximum of 1 statement per date, per account (which means we need the date and account_id attributes to be unique together)

To accomplish the above, we add indexes to date and account_id and set them to be unique as a pair.

class CreateStatements < ActiveRecord::Migration[6.0]
  def change
    create_table :statements do |t|
      t.references :account, foreign_key: true, index: true
      t.date :date
      # date and account_id are unique as a pair
      t.index [:date, :account_id], unique: true
    end
  end
end

Now an Account can have many Statements, but only a maximum of 1 per date. Without this constraint, an existing statement with today’s date would prevent any other statements from being created today, even for separate accounts.

Uniqueness constraints can also be added after a table has been created. All we need to do is add the indexes to both attributes like before. Also, instead of using t.index we use add_index:

class AddUniqueIndexToStatements < ActiveRecord::Migration[6.1]
  def change
    add_index :statements, [:account_id, :date], unique: true
  end
end

Model Validation

Now that the constraint is set in the database, we can also add it in the model. To do that, we add a uniqueness validation of an attribute and scope it to another attribute. For example, in the Statement model previously mentioned it looks like this:

validates :date, uniqueness: { scope: :account_id, message: "Statement already exists for this date." }

And that’s it! The model’s attributes are now unique as a pair and validated at both the database layer and model layer.

Migration

The migration for an expense model that has a decimal field looks like this:

class CreateExpenses < ActiveRecord::Migration[6.0]
  def change
    create_table :expenses do |t|
      t.decimal :amount, precision: 5, scale: 2
      t.timestamps
    end
  end
end

Notice that we’re specifying precision and scale in the decimal column:

• Precision is the total number of digits in the number, both before and after the decimal point.
• Scale is the number of digits after the decimal.

So this field will take a decimal value up to 999.99.

Model

For the expense model, we want to add validations so that the amount is positive and is less than 1000. This is based on the precision and scale we defined in the migration. We can also add validation to take into account decimal places by using a regular expression that allows values up to 999.99.

class Expense < ApplicationRecord
  validates :amount, numericality: { greater_than_or_equal_to: 0, less_than: BigDecimal(10**3) },
                     format: { with: /\A\d{1,3}(\.\d{1,2})?\z/ }
end

Controller

For the expense model, we have a standard controller. We don’t need to do anything here in regards to decimal precision. I’m showing this for completeness of the example.

class ExpensesController < ApplicationController

  def index
    @expenses = @user.expenses
  end

  def new
    @expense = Expense.new
  end

  def create
    @expense = Expense.new(expense_params)

    if @expense.save
      flash[:notice] = 'Expense created'
      redirect_to(expenses_path)
    else
      flash[:alert] = @expense.errors.full_messages.join(', ')
      render('new')
    end
  end
end

ERB Form

In the form, we need to use step to add front-end validation and to be able to accept decimal values in the field.

<%= form_with model: @expense, url: {controller: 'expenses', action: 'create'} do |f| %>
  <%= f.label :amount %>
  <%= f.number_field :amount, step: 0.01, class: 'input' %>
  <%= f.submit "Add", class: 'button is-primary' %>
<% end %>

In this form, step: 0.01 is the same as specifying a scale of 2 in the database. Decimal values will only be accepted if they have two decimal places and are in increments of 0.01. (If we had specified step: 0.05, then values accepted would have to be in increments of 0.05, such as 1, 1.05, and 1.10). Without step, the form would only take whole numbers without decimals.

Thanks to our model validation, a user won’t be able to submit values like 555.555 even if they were clever enough to skip front-end validation.

SQLite vs PostgreSQL Validation

Let’s say we didn’t have any front-end or model validations. How would the database handle decimal inputs that exceed both precision and scale? We can do some experiments in the Rails console.

Exceeding Scale Constraints

First, we’ll try the value 555.555, which exceeds the scale of 2.

Rails console with SQLite:

$ rails c

e = Expense.new(amount: 555.555)
 => #<Expense id: nil, amount: 0.55556e3, created_at: nil, updated_at: nil>

e.save!
  TRANSACTION (0.0ms)  begin transaction
  Expense Create (0.6ms)  INSERT INTO "expenses" ("amount", "created_at", "updated_at") VALUES (?, ?, ?)  [["amount", 555.56], ["created_at", "2021-03-22 09:49:35.881478"], ["updated_at", "2021-03-22 09:49:35.881478"]]
  TRANSACTION (1.1ms)  commit transaction
 => true

e.amount
 => 0.55556e3

After saving a new expense with the amount 555.555, the resulting amount is 0.55556e3, or 555.56. The database rounded our input since it was set to a scale of 2 in the migration.

Rails console with PostgreSQL:

$ rails c

e = Expense.new(amount: 555.555)
 => #<Expense id: nil, amount: 0.55556e3, created_at: nil, updated_at: nil>

e.save!
  D, [2021-03-23T01:47:26.928433 #1] DEBUG -- :   TRANSACTION (0.4ms)  BEGIN
  D, [2021-03-23T01:47:26.929505 #1] DEBUG -- :   Expense Create (0.7ms)  INSERT INTO "expenses" ("amount", "created_at", "updated_at") VALUES ($1, $2, $3) RETURNING "id"  [ ["amount", "555.56"], ["created_at", "2021-03-23 01:47:26.927355"], ["updated_at", "2021-03-23 01:47:26.927355"]]
  D, [2021-03-23T01:47:26.931487 #1] DEBUG -- :   TRANSACTION (1.6ms)  COMMIT
 => true

e.amount
 => 0.55556e3

PostgreSQL behaves the same way and rounds to two decimal places if the scale is exceeded.

Exceeding Precision Constraints

Next we’ll try the value 123456.01, which exceeds the precision of 5.

Rails console with SQLite:

$ rails c

e = Expense.new(amount: 123456.01)
 => #<Expense id: nil, amount: 0.12346e6, created_at: nil, updated_at: nil>

e.save!
  TRANSACTION (0.1ms)  begin transaction
  Expense Create (0.8ms)  INSERT INTO "expenses" ("amount", "created_at", "updated_at") VALUES (?, ?, ?)  [["amount", 123460.0], ["created_at", "2021-03-23 02:10:09.951895"], ["updated_at", "2021-03-23 02:10:09.951895"]]
  TRANSACTION (0.5ms)  commit transaction
 => true

e.amount
 => 0.12346e6

Interestingly, SQLite saves the value 123456.01 incorrectly as 123460.0 with no errors whatsoever. This is undesired behavior because it defeats the point of defining a precision in the first place.

Rails console with PostgreSQL:

$ rails c

e = Expense.new(amount: 123456.01)
 => #<Expense id: nil, amount: 0.12346e6, created_at: nil, updated_at: nil>

e.save!
  D, [2021-03-23T01:54:25.490193 #1] DEBUG -- :   TRANSACTION (0.5ms)  BEGIN
  D, [2021-03-23T01:54:25.491212 #1] DEBUG -- :   Expense Create (0.7ms)  INSERT INTO "expenses" ("amount", "created_at", "updated_at") VALUES ($1, $2, $3) RETURNING "id"  [["amount", "123460.0"], ["created_at", "2021-03-23 01:54:25.489022"], ["updated_at", "2021-03-23 01:54:25.489022"]]
  D, [2021-03-23T01:54:25.491842 #1] DEBUG -- :   TRANSACTION (0.4ms)  ROLLBACK
  Traceback (most recent call last):
          1: from (irb):17:in `<main>'
  ActiveRecord::RangeError (PG::NumericValueOutOfRange: ERROR:  numeric field overflow)
  DETAIL:  A field with precision 5, scale 2 must round to an absolute value less than 10^3.

PostgreSQL rejects the value and shows us an error telling us that the number does not fit in with the precision and scale constraints. This is preferable to storing an incorrect value.

While Rails offers several ways of validating decimals, it’s still important to choose the correct database to handle decimals.