# 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)
- **Bulk Delete** multiple buckets at once (v1.3.0+)

## 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

```bash
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

```bash
curl https://YOUR_DOMAIN/api/buckets
```

**Response:**

```json
{
  "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

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

## Deleting Buckets

### Single Bucket Deletion

#### 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:**

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

**Delete bucket and all contents:**

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

### Bulk Bucket Deletion (v1.3.0+)

Delete multiple buckets at once from the main bucket list page.

#### Via Web UI

1. **Select Buckets** - Click the checkbox in the top-left corner of each bucket card
   - Selected buckets are highlighted with a blue border and background
   - Checkbox appears on hover or when any bucket is selected
2. **Review Selection** - The bulk action toolbar appears showing:
   - Number of buckets selected (e.g., "3 buckets selected")
   - **Clear Selection** button (gray)
   - **Delete Selected** button (red)

3. **Initiate Deletion** - Click the **Delete Selected** button
   - The application fetches file counts for all selected buckets
   - Shows "Preparing..." status during file count calculation

4. **Confirm Deletion** - Review the confirmation modal showing:
   - List of all buckets to be deleted
   - Total file count across all selected buckets
   - Warning about permanent deletion
5. **Track Progress** - During deletion:
   - Progress message: "Deleting bucket X of Y..."
   - Visual progress bar showing completion percentage
   - Modal cannot be closed during deletion

6. **Completion** - After deletion:
   - Bucket list automatically refreshes
   - Selection is cleared
   - Any errors are displayed for individual failures

#### Features

- **Visual Selection** - Selected buckets highlighted with blue border and background
- **Bulk Action Toolbar** - Persistent toolbar showing selection count and actions
- **Enhanced Confirmation Modal**:
  - Lists all buckets to be deleted by name
  - Shows total file count across all buckets
  - Progress tracking during deletion
  - Visual progress bar
- **Force Delete** - Automatically deletes all files within each bucket before removing the bucket
- **Error Handling** - If one bucket fails, the operation continues with remaining buckets
- **Safety Features** - Clear warnings about permanent deletion that cannot be undone

#### Use Cases

- Clean up multiple test or development buckets
- Remove outdated project buckets in batch
- Delete multiple empty buckets efficiently
- Streamline bucket management workflow

#### Important Notes

- ⚠️ **This cannot be undone!** All data in all selected buckets is permanently deleted.
- Each bucket is processed sequentially, not in parallel
- Force delete is automatic - all files are deleted before the bucket is removed
- Individual bucket failures don't stop the entire operation
- Progress is displayed in real-time
- For large buckets with many files, deletion may take several minutes per bucket

## 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
- Review the bucket list in bulk delete confirmation modal before confirming
- Use bulk delete for test/development buckets
- Clear selection if you accidentally selected the wrong bucket

❌ **DON'T:**

- Delete buckets without confirmation
- Rename critical buckets without planning
- Use force delete without checking contents
- Select production buckets for bulk deletion without careful review
- Rush through the bulk delete confirmation modal

## 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](API-Reference#bucket-management) page for complete endpoint documentation:

- [List Buckets](API-Reference#list-buckets)
- [Create Bucket](API-Reference#create-bucket)
- [Rename Bucket](API-Reference#rename-bucket)
- [Delete Bucket](API-Reference#delete-bucket)

---

**Next Steps:**

- Learn about [File Operations](File-Operations)
- Explore the [API Reference](API-Reference)
- Check [Troubleshooting](Troubleshooting) if you encounter issues