Principle:Mlflow Mlflow Database Schema Management
| Knowledge Sources | |
|---|---|
| Domains | Database Administration, Schema Migration, CLI Tooling |
| Last Updated | 2026-02-13 20:00 GMT |
Overview
A command-line interface for managing database schema upgrades and workspace-scoped data migrations against a tracking store's relational backend.
Description
Database schema management provides administrative commands for evolving and maintaining the relational database that serves as a tracking store's backend. It exposes two primary operations through a command group:
Schema upgrade takes a database connection URL and applies all pending migrations to bring the schema to the latest supported version. It creates a database engine with automatic retry logic to handle transient connection failures, then delegates to an internal upgrade function that applies migration scripts in sequence. This operation is inherently non-transactional for large migrations, so operators are strongly advised to take backups before proceeding.
Workspace migration moves resources that were scoped to non-default workspaces into a single default workspace. This is a consolidation operation useful when transitioning from a multi-workspace to a single-tenant deployment. It operates in two phases:
- Dry run phase: Scans all workspace-scoped tables, counts how many rows would be moved, and optionally reports conflicts in verbose mode. No data is modified.
- Execution phase: After presenting the row counts and receiving confirmation (or if auto-confirmed via a flag), it performs the actual migration within a single transaction.
The command supports several operational safety features:
- A dry-run mode that reports what would change without making modifications.
- A verbose mode that lists all conflicts instead of truncating output.
- A skip-confirmation flag for automated/scripted usage.
- Proper engine disposal in a finally block to prevent connection leaks regardless of success or failure.
- Error wrapping that converts runtime errors into user-friendly CLI error messages.
Usage
This principle applies when:
- A tracking store's database schema must be upgraded to support a newer version of the application.
- An operator needs to consolidate multi-workspace data into a single default workspace.
- Automated deployment pipelines need to run migrations non-interactively.
- Pre-migration impact assessment is required before committing to a schema or data change.
Theoretical Basis
The schema management commands follow a two-phase migration with safety gates pattern:
SCHEMA UPGRADE:
1. Parse database URL from command arguments
2. Create database engine with retry logic for transient failures
3. Apply all pending migration scripts in version order
4. Report completion
WORKSPACE MIGRATION:
1. Parse database URL and option flags
2. Create database engine with retry logic
3. Execute dry-run scan:
- For each workspace-scoped table:
- Count rows not in the default workspace
- Aggregate total row count
4. If dry_run flag is set:
- Report per-table counts and exit
5. If total is zero:
- Report "no rows to move" and exit
6. Display per-table counts to operator
7. If auto-confirm flag is not set:
- Prompt for confirmation (abort on decline)
8. Execute migration within a single transaction
9. Report total rows moved
10. Dispose of database engine (always, via finally block)
The key design principles are:
- Idempotent schema upgrades: Migration scripts are versioned and tracked, so re-running the upgrade command on an already-current database is a no-op.
- Dry-run previews: The dry-run always executes before the real migration, even in non-dry-run mode, to provide the operator with accurate counts before confirmation.
- Transactional data migration: While schema upgrades may not be fully transactional (due to DDL limitations in some databases), the workspace data migration runs within a single transaction to ensure atomicity.
- Defensive resource management: The database engine is always disposed in a finally block, preventing connection pool exhaustion if the migration fails.