Bucket Management

Bucket Management

Guide to managing R2 buckets with R2-Manager-Worker.

Overview

Bucket management is the core functionality of R2-Manager-Worker. You can:

• Create new buckets
• List all buckets with their sizes
• Rename buckets
• Delete buckets (with optional force delete of all objects)

Creating Buckets

Via Web UI

1. Click New Bucket button in the top bar
2. Enter a bucket name
3. Click Create

Bucket Naming Rules:

• Only lowercase letters (a-z), numbers (0-9), and hyphens (-)
• Cannot begin or end with a hyphen
• Must be 3-63 characters long
• Examples:
  • ✅ my-files-2024
  • ✅ project-data
  • ❌ -invalid (starts with hyphen)
  • ❌ MyFiles (uppercase)
  • ❌ ab (too short)

Via API

curl -X POST https://YOUR_DOMAIN/api/buckets \
  -H "Content-Type: application/json" \
  -d '{"name": "my-files"}'

Listing Buckets

Via Web UI

Buckets automatically appear in the dashboard with:

• Bucket name
• Creation date
• Total storage size
• Quick action buttons

Via API

curl https://YOUR_DOMAIN/api/buckets

Response:

{
  "result": {
    "buckets": [
      {
        "name": "my-files",
        "creation_date": "2024-01-01T00:00:00.000Z",
        "size": 5242880
      }
    ]
  }
}

Renaming Buckets

Via Web UI

1. Click the bucket you want to rename
2. Click the Rename button
3. Enter the new name
4. Confirm

How It Works

Since R2 doesn't support native bucket renaming, the process:

1. Creates a new bucket with the new name
2. Copies all objects from the old bucket
3. Deletes the old bucket

Important Notes:

• Large buckets can take several minutes
• File metadata is preserved
• All files keep the same names

Via API

curl -X PATCH https://YOUR_DOMAIN/api/buckets/old-name \
  -H "Content-Type: application/json" \
  -d '{"newName": "new-name"}'

Deleting Buckets

Via Web UI

1. Click the bucket you want to delete
2. Click the Delete button
3. Choose:
   • Empty & Delete - Delete bucket and all contents
   • Delete Empty Only - Fails if bucket has files

Via API

Delete empty bucket:

curl -X DELETE https://YOUR_DOMAIN/api/buckets/my-bucket

Delete bucket and all contents:

curl -X DELETE https://YOUR_DOMAIN/api/buckets/my-bucket?force=true

Important Notes

• ⚠️ This cannot be undone! All data is permanently deleted.
• Force delete can take a long time for large buckets
• Be careful when using force=true

Bucket Size Calculation

Bucket sizes shown in the UI are calculated by:

1. Iterating through all objects in the bucket
2. Summing their individual sizes
3. Displaying in human-readable format (KB, MB, GB)

Notes:

• Size calculation happens automatically when listing buckets
• Can take time for very large buckets (10,000+ objects)
• Size is approximate (may not include all metadata)

Best Practices

Naming

✅ DO:

• Use descriptive names: customer-assets, project-2024
• Use dates for time-specific buckets: backups-2024-01
• Use hyphens for readability: my-important-files

❌ DON'T:

• Use special characters or spaces
• Use uppercase letters
• Use generic names: bucket1, data
• Use names of other projects

Organization

✅ DO:

• Create separate buckets for different projects
• Use folder structure within buckets (prefixes)
• Document the purpose of each bucket

❌ DON'T:

• Put all files in one bucket
• Mix different data types
• Forget what a bucket contains

Safety

✅ DO:

• Backup important data before deletions
• Test rename operations on small buckets first
• Use force delete with caution

❌ DON'T:

• Delete buckets without confirmation
• Rename critical buckets without planning
• Use force delete without checking contents

Troubleshooting

Bucket Creation Fails

Problem: Error when creating bucket

Solutions:

1. Check bucket name follows naming rules
2. Ensure name isn't already taken
3. Verify API token has R2 permissions
4. Check account isn't over quota

Can't Rename/Delete Bucket

Problem: Rename or delete operation fails

Solutions:

1. Check bucket exists: npx wrangler r2 bucket list
2. Verify you're authenticated
3. Check API token permissions
4. For large buckets, wait for operation to complete

Bucket Size Wrong

Problem: Size shown in UI doesn't match expected

Solutions:

1. Refresh the page
2. Check if files are still uploading
3. Consider metadata in file sizes
4. Use R2 console to verify actual size

API Reference

See the API Reference page for complete endpoint documentation:

• List Buckets
• Create Bucket
• Rename Bucket
• Delete Bucket

---

Next Steps:

• Learn about File Operations
• Explore the API Reference
• Check Troubleshooting if you encounter issues