🔧 Managing Files on AWS S3 with Ruby Shouldn’t Be a Hassle — So I Built S3FileManager

#coding #programming #ruby #rails

May 13, 2025

As developers, we tend to take small file operations for granted—until they start piling up. Let me paint a picture:

You upload a file to an S3 bucket. Then your PM asks: “Can we rename it?” Then a bug pops up because two versions of the file are floating around. Then you forget if you already deleted the old one… And suddenly, your storage is messy, your logs are full of copy-paste errors, and you’re questioning life choices.

So I took a break, made a fresh mate , and said: “There has to be a cleaner way.”

Let’s Build Smarter Tools Together

If you’re working on a Ruby project and want to better organize, automate, or scale your app using AWS , I’d love to hear from you.

Whether you’re building a side project or scaling a platform, clean tools make a big difference — and I’m always happy to share ideas or learn from others in the community.

AWS #RubyCommunity #DevTools #Rails

Enter S3FileManager

I built a simple Ruby class to make working with AWS S3 a breeze. With just a few lines of code, I can:

Upload a file
Delete a file
Rename a file (via copy + delete)
Overwrite a file (aka “edit”)

All abstracted in a single, readable, reusable class.

Here’s the core:


class S3FileManager
  def initialize(bucket_name:, region: 'us-east-1')
    @s3 = Aws::S3::Resource.new(region: region)
    @bucket = @s3.bucket(bucket_name)
  end

  def upload(local_path, remote_key)
    @bucket.object(remote_key).upload_file(local_path)
  end

  def delete(remote_key)
    @bucket.object(remote_key).delete
  end

  def rename(old_key, new_key)
    @bucket.object(new_key).copy_from(@bucket.object(old_key))
    @bucket.object(old_key).delete
  end

  def overwrite(remote_key, new_local_path)
    upload(new_local_path, remote_key)
  end
end

Example usage:


manager = S3FileManager.new(bucket_name: 'my-awesome-bucket')

manager.upload('local/image.png', 'images/profile.png')
manager.rename('images/profile.png', 'images/profile_old.png')
manager.overwrite('images/profile_old.png', 'local/new_image.png')
manager.delete('images/profile_old.png')

Why This Matters

Clean Abstraction : You don’t need to write repetitive S3 logic across your app. Less Error-Prone : No more forgetting to delete old files or mismatching paths. More Expressive : Your code says exactly what it does: rename, delete, upload.

Plus, it’s a joy to work with something that feels Ruby-ish — expressive, elegant, and easy to test.

Lessons Learned

Rename in S3 isn’t real — it’s actually a copy followed by a delete.
Think ahead when dealing with object keys and folders — especially if you’re dealing with user-uploaded files.
Design for reuse — what started as a helper method became a class I now drop into multiple projects.

Want to Collaborate?

If you’ve tackled similar file-handling pain points — or want to improve this class (add logging? versioning? signed URLs?) — I’d love to hear from you.

Drop a comment, message me, or fork the gist if you’d like to play with the code.

Let’s keep Ruby expressive and fun.