Delete a bucket

Delete a bucket. storage-api refuses to drop a bucket that still contains objects — call empty_bucket first if you want to wipe everything in one go.

This is a destructive, irreversible operation. Once deleted, the bucket id is free to be re-used by create_bucket, but historic signed URLs, public URLs, and object UUIDs are gone.

Service-role key required

Bucket admin endpoints reject the publishable / anon key with 401 Unauthorized. Construct the client with the service-role JWT.

Signature

supabase.storage.delete_bucket(id)

Parameters

Name	Type	Required	Description
`id`	String	Required	Bucket identifier to delete. Must reference an empty bucket — call empty_bucket first to clear it.

Returns

Hash

The raw storage-api response body, typically { "message" => "Successfully deleted" }.

Example — delete an empty bucket

supabase.storage.delete_bucket("scratch")
# => { "message" => "Successfully deleted" }

Example — empty + delete in one go

supabase.storage.empty_bucket("old-uploads")
supabase.storage.delete_bucket("old-uploads")

Example — handle a non-empty bucket

begin
  supabase.storage.delete_bucket("user-uploads")
rescue Supabase::Storage::Errors::StorageApiError => e
  if e.message.include?("not empty")
    supabase.storage.empty_bucket("user-uploads")
    retry
  else
    raise
  end
end