Fixing Rails Active Storage with UUID Models

If you’re using UUIDs as primary keys in your Rails application, you might have encountered issues with Active Storage attachments. This is because Active Storage’s default migrations don’t respect the application-wide primary key type configuration. Let’s fix this!

The Problem

When you set up your Rails application to use UUIDs as primary keys (which is a best practice fullstop in my opinion), you typically configure it in migrations:

  create_table "accounts", id: :uuid, default: -> { "gen_random_uuid()" }, force: :cascade do |t|
    t.string "title"
    t.boolean "active"
    ...
  end

However, if you ran rails active_storage:install before this change, the generated migrations will assume you use the default of bigint for primary keys. This can lead to foreign key mismatches and potential issues with your attachments.

The most common error you’ll encounter is when trying to remove an entry with Active Storage variants:

undefined method `attachment_reflections' for nil:NilClass

This error occurs because the polymorphic association between your model and the Active Storage attachment is broken due to the mismatched primary key types. The record_id in the active_storage_attachments table is trying to reference a UUID, but it’s stored as a bigint.

We see these lines in the Rails 8 Active Storage migrations:

  private
    def primary_and_foreign_key_types
      config = Rails.configuration.generators
      setting = config.options[config.orm][:primary_key_type]
      primary_key_type = setting || :primary_key
      foreign_key_type = setting || :bigint
      [ primary_key_type, foreign_key_type ]
    end

The Solution

There are two ways to fix this:

1. Configure Active Storage to use UUIDs

Add this configuration to your config/application.rb:

config.generators do |g|
  g.orm :active_record, primary_key_type: :uuid
end

This will ensure that all new Active Storage tables use UUIDs as their primary keys.

2. Either: modify existing migrations

If you’ve already run the Active Storage migrations, you’ll need to modify them. Here’s how to update the tables:

class FixActiveStorageUuidSupport < ActiveRecord::Migration[7.1]
  def change
    # Drop existing tables
    drop_table :active_storage_attachments
    drop_table :active_storage_blobs
    drop_table :active_storage_variant_records

    # Recreate with UUID support
    create_table :active_storage_blobs, id: :uuid do |t|
      t.string   :key,          null: false
      t.string   :filename,     null: false
      t.string   :content_type
      t.text     :metadata
      t.string   :service_name, null: false
      t.bigint   :byte_size,    null: false
      t.string   :checksum

      t.timestamps

      t.index [ :key ], unique: true
    end

    create_table :active_storage_attachments, id: :uuid do |t|
      t.string     :name,     null: false
      t.references :record,   null: false, polymorphic: true, index: false, type: :uuid
      t.references :blob,     null: false, type: :uuid

      t.timestamps

      t.index [ :record_type, :record_id, :name, :blob_id ], name: "index_active_storage_attachments_uniqueness", unique: true
      t.foreign_key :active_storage_blobs, column: :blob_id, type: :uuid
    end

    create_table :active_storage_variant_records, id: :uuid do |t|
      t.belongs_to :blob, null: false, index: false, type: :uuid
      t.string :variation_digest, null: false

      t.index %i[ blob_id variation_digest ], name: "index_active_storage_variant_records_uniqueness", unique: true
      t.foreign_key :active_storage_blobs, column: :blob_id, type: :uuid
    end
  end
end

3. Or: Remake the whole schema from scratch if the app is new

bin/rails db:drop
rm db/schema.rb
bin/rails db:create
bin/rails db:migrate

You’ll see the schema changes to UUIDs for the active_storage tables

Notes

1. Make sure you have the pgcrypto extension enabled in your PostgreSQL database:

   class EnableUuidExtension < ActiveRecord::Migration[7.1]
     def change
    enable_extension 'pgcrypto'
     end
   end
   

2. This migration must be the first one to run in your application.
3. If you have existing attachments, you’ll need to handle the data migration carefully and perhaps not just trust a random blogger with this, test it more.