shrine

# [Shrine]

<img src="https://shrinerb.com/img/logo.png" width="100" alt="Shrine logo: a red paperclip" align="right" />

Shrine is a toolkit for handling file attachments in Ruby applications. Some highlights:

* **Modular design** – the [plugin system] allows you to load only the functionality you need
* **Memory friendly** – streaming uploads and [downloads][Retrieving Uploads] make it work great with large files
* **Cloud storage** – store files on [disk][FileSystem], [AWS S3][S3], [Google Cloud][GCS], [Cloudinary] and others
* **Persistence integrations** – works with [Sequel], [ActiveRecord], [ROM], [Hanami] and [Mongoid] and others
* **Flexible processing** – generate thumbnails [eagerly] or [on-the-fly] using [ImageMagick] or [libvips]
* **Metadata validation** – [validate files][validation] based on [extracted metadata][metadata]
* **Direct uploads** – upload asynchronously [to your app][simple upload] or [to the cloud][presigned upload] using [Uppy]
* **Resumable uploads** – make large file uploads [resumable][resumable upload] on [S3][uppy-s3_multipart] or [tus][tus-ruby-server]
* **Background jobs** – built-in support for [background processing][backgrounding] that supports [any backgrounding library][Backgrounding Libraries]

If you're curious how it compares to other file attachment libraries, see the
[Advantages of Shrine]. Otherwise, follow along with the **[Getting Started
guide]**.

## Links

| Resource                   | URL                                                                                      |
| :----------------          | :-----------------------------------------------------------------------------           |
| Website & Documentation    | [shrinerb.com](https://shrinerb.com)                                                     |
| Demo code                  | [Roda][roda demo] / [Rails][rails demo]                                                  |
| Wiki                       | [github.com/shrinerb/shrine/wiki](https://github.com/shrinerb/shrine/wiki)               |
| Discussion forum           | [github.com/shrinerb/shrine/discussions](https://github.com/shrinerb/shrine/discussions) |
| Alternate Discussion forum | [discourse.shrinerb.com](https://discourse.shrinerb.com)                                 |

## Setup

Run:

```sh
bundle add shrine
```

Then add `config/initializers/shrine.rb` which sets up the storage and loads
ORM integration:

```rb
require "shrine"
require "shrine/storage/file_system"

Shrine.storages = {
  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"), # temporary
  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads"),       # permanent
}

Shrine.plugin :activerecord           # loads Active Record integration
Shrine.plugin :cached_attachment_data # enables retaining cached file across form redisplays
Shrine.plugin :restore_cached_data    # extracts metadata for assigned cached files
```

Next, add the `<name>_data` column to the table you wan