Upgrade Guide

Upgrade Guide

This guide helps you upgrade your R2 Bucket Manager metadata database to work with the latest version.

Automated In-App Upgrades (Recommended)

R2 Bucket Manager includes an automated upgrade system with an in-app banner:

1. Launch the app - When schema updates are available, a yellow banner appears at the top of the page
2. Click "Upgrade Now" - The system automatically applies all pending migrations
3. Done! - A green success banner confirms the upgrade completed

The automated system:

• Detects legacy installations and handles them automatically
• Tracks applied migrations in a schema_version table
• Is idempotent (safe to run multiple times)
• Shows detailed error messages if something goes wrong

Do I Need to Upgrade?

If you deployed R2 Bucket Manager before December 2025, you may need to run migrations. The in-app upgrade banner will automatically detect this.

If you're installing R2 Bucket Manager for the first time, no migration is needed - just use the main schema.sql.

Manual Migration (Alternative)

If you prefer to run migrations manually via command line, or if the in-app upgrade isn't accessible:

wrangler d1 execute r2-manager-metadata --remote --file=worker/schema.sql

This script is idempotent and safe to run multiple times.

What Gets Upgraded?

The migration system tracks four migrations:

Version 1: Initial Schema

Base schema with bulk_jobs, job_audit_events, and audit_log tables for job tracking and audit logging.

Version 2: Webhooks

Adds the webhooks table for event notifications (file uploads, downloads, bucket operations, job events).

Version 3: Bucket Tags

Adds the bucket_tags table for custom text-based bucket organization and searchable tagging.

Version 4: Bucket Colors

Adds the bucket_colors table for visual bucket organization with color tags.

---

For detailed SQL of each migration, see worker/utils/migrations.ts in the source code.

Verify Migration Success

Check the schema_version table to see applied migrations:

wrangler d1 execute r2-manager-metadata --remote --command="SELECT * FROM schema_version"

You should see entries for each applied migration version (1-4).

Troubleshooting

Banner not showing when expected

• Refresh the page to re-check migration status
• Check the browser console for API errors

"Upgrade Now" fails

• Check the error message displayed in the banner
• Verify D1 database binding is correctly configured
• Try the manual migration command as a fallback

Error: "duplicate column name"

This is expected if you run migrations multiple times. The columns already exist, and the error is harmless.

Migration Doesn't Apply

Problem: Migration runs but changes don't appear

Possible Causes:

• Wrong database name
• Using --local instead of --remote (or vice versa)

Solution: Verify database name:

wrangler d1 list

Ensure you're using the correct database name and flag (--remote for production, --local for development).

Docker Users

If you're running R2 Bucket Manager in Docker:

1. The Docker container doesn't include Wrangler
2. Run migrations from your local machine with Wrangler installed
3. Restart the Docker container after migration

Fresh Installation

If you're installing R2 Bucket Manager for the first time, skip migrations and use the main schema:

wrangler d1 execute r2-manager-metadata --remote --file=worker/schema.sql

This includes all migrations already.

Local Development

For local development, the in-app migration system works the same way. Alternatively:

wrangler d1 execute r2-manager-metadata-dev --local --file=worker/schema.sql

Migration History

Version	Name	Description
1	initial_schema	Base schema with bulk_jobs, job_audit_events, audit_log
2	webhooks	Event notification webhooks
3	bucket_tags	Custom text-based bucket tagging
4	bucket_colors	Visual bucket organization with colors

Need Help?

If you encounter any issues with the migration, please open an issue on GitHub with:

• The error message
• Your database binding name
• Whether you're running in production (--remote) or development (--local)
• Output of wrangler d1 list

Next Steps

• Installation & Setup - Set up R2 Bucket Manager
• Configuration Reference - Environment variables and settings
• Troubleshooting - Common issues and solutions