Upgrade Guide

Upgrade Guide

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

Note: This guide covers D1 Manager's internal metadata database upgrades. For migrating data between D1 databases, see Migration Wizard.

Automated In-App Upgrades (Recommended)

D1 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 D1 Manager before December 2025, you may need to run migrations. The in-app upgrade banner will automatically detect this.

If you're installing D1 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 d1-manager-metadata --remote --file=worker/schema.sql

This script is idempotent and safe to run multiple times.

What Gets Upgraded?

The migration system tracks five migrations:

Version 1: Initial Schema

Base schema with databases, query_history, saved_queries, and undo_history tables.

Version 2: Job History

Adds the bulk_jobs, job_audit_events, and bookmark_history tables for job tracking and Time Travel functionality.

Version 3: Color Tags

Adds the database_colors and table_colors tables for visual organization with color tags.

Version 4: Webhooks

Adds the webhooks table for external observability notifications.

Version 5: Scheduled Backups

Adds the scheduled_backups table for automated R2 backup schedules.

---

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 d1-manager-metadata --remote --command="SELECT * FROM schema_version"

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

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 D1 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 D1 Manager for the first time, skip migrations and use the main schema:

wrangler d1 execute d1-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 d1-manager-metadata-dev --local --file=worker/schema.sql

Migration History

Version	Name	Description
1	initial_schema	Base schema with databases, query_history, saved_queries, undo_history
2	job_history	Job tracking with bulk_jobs, job_audit_events, bookmark_history
3	color_tags	Visual organization with database_colors, table_colors
4	webhooks	External observability notifications
5	scheduled_backups	Automated R2 backup schedules

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 - Set up D1 Manager
• Docker Deployment - Deploy with Docker
• Troubleshooting - Common issues