Active Storage

Active Storage makes it simple to upload and reference files in cloud services like Amazon S3, Google Cloud Storage, or Microsoft Azure Storage, and attach those files to Active Records. Supports having one main service and mirrors in other services for redundancy. It also provides a disk service for testing or local deployments, but the focus is on cloud storage.

Files can be uploaded from the server to the cloud or directly from the client to the cloud.

Image files can furthermore be transformed using on-demand variants for quality, aspect ratio, size, or any other MiniMagick supported transformation.

Compared to other storage solutions

A key difference to how Active Storage works compared to other attachment solutions in Rails is through the use of built-in Blob and Attachment models (backed by Active Record). This means existing application models do not need to be modified with additional columns to associate with files. Active Storage uses polymorphic associations via the Attachment join model, which then connects to the actual Blob.

Blob models store attachment metadata (filename, content-type, etc.), and their identifier key in the storage service. Blob models do not store the actual binary data. They are intended to be immutable in spirit. One file, one blob. You can associate the same blob with multiple application models as well. And if you want to do transformations of a given Blob, the idea is that you'll simply create a new one, rather than attempt to mutate the existing one (though of course you can delete the previous version later if you don't need it).

Installation

Run rails active_storage:install to copy over active_storage migrations.

Examples

One attachment:

``ruby
class User < ApplicationRecord
# Associates an attachment and a blob. When the user is destroyed they are
# purged by default (models destroyed, and resource files deleted).
has_one_attached :avatar
end

Attach an avatar to the user.

class AvatarsController < ApplicationController
def update
# params[:avatar] contains a ActionDispatch::Http::UploadedFile object
Current.user.avatar.attach(params.require(:avatar))
redirect_to Current.user
end
end
`

Many attachments:

`ruby
class Message < ApplicationRecord
has_many_attached :images
end
`

`erb
<%= form_with model: @message, local: true do |form| %>
<%= form.text_field :title, placeholder: "Title" %>

<%= form.text_area :content %>



<%= form.file_field :images, multiple: true %>

<%= form.submit %>
<% end %>
`

`ruby
class MessagesController < ApplicationController
def index
# Use the built-in with_attached_images scope to avoid N+1
@messages = Message.all.with_attached_images
end

def create
message = Message.create! params.require(:message).permit(:title, :content)
message.images.attach(params[:message][:images])
redirect_to message
end

def show
@message = Message.find(params[:id])
end
end
`

Variation of image attachment:

`erb
<%# Hitting the variant URL will lazy transform the original blob and then redirect to its new service location %>
<%= image_tag user.avatar.variant(resize: "100x100") %>
`

Direct uploads

Active Storage, with its included JavaScript library, supports uploading directly from the client to the cloud.

$3

1. Include activestorage.js in your application's JavaScript bundle.

Using the asset pipeline:
`js
//= require activestorage
`
Using the npm package:
`js
import * as ActiveStorage from "activestorage"
ActiveStorage.start()
`
2. Annotate file inputs with the direct upload URL.

`ruby
<%= form.file_field :attachments, multiple: true, direct_upload: true %>
`
3. That's it! Uploads begin upon form submission.

$3

| Event name | Event target | Event data (event.detail) | Description |
| --- | --- | --- | --- |
| direct-uploads:start |