-
Notifications
You must be signed in to change notification settings - Fork 0
Migration Guide
This guide helps you migrate your DO Manager database to work with the latest version.
DO Manager includes an automated migration system with an in-app upgrade banner:
- Launch the app - When schema updates are available, a yellow banner appears at the top of the page
- Click "Upgrade Now" - The system automatically applies all pending migrations
- 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_versiontable - Is idempotent (safe to run multiple times)
- Shows detailed error messages if something goes wrong
If you deployed DO Manager before December 2025, you may need to run migrations. The in-app upgrade banner will automatically detect this.
If you're installing DO Manager for the first time, no migration is needed - just use the main schema.sql.
If you prefer to run migrations manually via command line, or if the in-app upgrade isn't accessible:
wrangler d1 execute do-manager-metadata --remote --file=worker/schema.sqlThis script is idempotent and safe to run multiple times.
The migration system tracks six migrations:
Base schema with namespaces, instances, jobs, audit_log, and backups tables.
Adds the webhooks table for event notifications.
Adds the alarm_history table for tracking alarm lifecycle (scheduled, completed, cancelled).
Adds the saved_queries table for storing SQL query templates per namespace.
Adds the color column to the namespaces table for visual organization with color tags.
Adds the tags column to the instances table for tagging and search functionality.
For detailed SQL of each migration, see worker/utils/migrations.ts in the source code.
Check the schema_version table to see applied migrations:
wrangler d1 execute do-manager-metadata --remote --command="SELECT * FROM schema_version"You should see entries for each applied migration version (1-6).
- Refresh the page to re-check migration status
- Check the browser console for API errors
- Check the error message displayed in the banner
- Verify D1 database binding is correctly configured
- Try the manual migration command as a fallback
This is expected if you run migrations multiple times. The columns already exist, and the error is harmless.
Problem: Migration runs but changes don't appear
Possible Causes:
- Wrong database name
- Using
--localinstead of--remote(or vice versa)
Solution: Verify database name:
wrangler d1 listEnsure you're using the correct database name and flag (--remote for production, --local for development).
If you're running DO Manager in Docker:
- The Docker container doesn't include Wrangler
- Run migrations from your local machine with Wrangler installed
- Restart the Docker container after migration
If you're installing DO Manager for the first time, skip migrations and use the main schema:
wrangler d1 execute do-manager-metadata --remote --file=worker/schema.sqlThis includes all migrations already.
For local development, the in-app migration system works the same way. Alternatively:
wrangler d1 execute do-manager-metadata-dev --local --file=worker/schema.sql| Version | Name | Description |
|---|---|---|
| 1 | initial_schema | Base schema with namespaces, instances, jobs, audit_log, backups |
| 2 | webhooks | Event notification webhooks |
| 3 | alarm_history | Alarm lifecycle tracking |
| 4 | saved_queries_and_colors | SQL query templates per namespace |
| 5 | namespace_colors | Visual namespace organization |
| 6 | instance_tags | Instance tagging and search |
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
- Installation - Set up DO Manager
- Docker-Deployment - Deploy with Docker
- Troubleshooting - Common issues