Implementation:Mlflow Mlflow Database CLI

Knowledge Sources	Mlflow_Mlflow
Domains	Database Management, CLI
Last Updated	2026-02-13 20:00 GMT

Overview

A Click-based CLI command group that provides database management commands for MLflow tracking server databases, including schema upgrades and workspace migration.

Description

mlflow/db.py defines the db command group for the MLflow CLI with two commands:

• upgrade: Upgrades the schema of an MLflow tracking database to the latest supported version. It creates a SQLAlchemy engine using mlflow.store.db.utils.create_sqlalchemy_engine_with_retry() and runs _upgrade_db() to apply pending Alembic migrations. The command warns that schema migrations can be slow and are not guaranteed to be transactional, so a database backup is strongly recommended before running.

• migrate-to-default-workspace: Moves workspace-scoped resources into the default workspace. This command supports a --dry-run mode that reports how many rows would be moved per table without making changes, a --verbose flag to list all conflicts instead of truncating output, and a --yes flag to skip the interactive confirmation prompt. The actual migration runs in a single transaction via mlflow.store.db.workspace_migration.migrate_to_default_workspace(). The engine is always disposed in a finally block to ensure proper cleanup.

Both commands accept a url positional argument specifying the database connection URI (e.g., sqlite:///mlflow.db or postgresql://user:pass@host/db).

Usage

Use these commands when maintaining a self-hosted MLflow tracking server with a SQL database backend. The upgrade command is essential after upgrading MLflow to ensure the database schema matches the new version. The migrate-to-default-workspace command is used when consolidating multi-workspace data.

Code Reference

Source Location

• Repository: Mlflow_Mlflow
• File: mlflow/db.py
• Lines: 1-93

Signature

@click.group("db")
def commands():
    """Commands for managing an MLflow tracking database."""

@commands.command()
@click.argument("url")
def upgrade(url): ...

@commands.command("migrate-to-default-workspace")
@click.argument("url")
@click.option("--dry-run/--no-dry-run", default=False, show_default=True)
@click.option("--verbose", "-v", is_flag=True, default=False)
@click.option("--yes", "-y", is_flag=True, default=False)
def migrate_to_default_workspace(url, dry_run, verbose, yes): ...

Import

# Used as part of the MLflow CLI
mlflow db upgrade <database-url>
mlflow db migrate-to-default-workspace <database-url>

I/O Contract

Inputs (upgrade)

Name	Type	Required	Description
url	str	Yes	Database connection URI (e.g., "sqlite:///mlflow.db", "postgresql://user:pass@host/db")

Inputs (migrate-to-default-workspace)

Name	Type	Required	Description
url	str	Yes	Database connection URI
--dry-run / --no-dry-run	flag	No	Check for conflicts and report row counts without migrating (default: --no-dry-run)
--verbose / -v	flag	No	List all conflicts instead of truncating output
--yes / -y	flag	No	Skip the confirmation prompt

Outputs

Name	Type	Description
schema changes	database	Applies Alembic migrations to bring the database schema up to date (upgrade command)
row migration	database	Moves workspace-scoped rows into the default workspace (migrate-to-default-workspace command)
stdout	text	Progress and status messages including per-table row counts

Usage Examples

Upgrade Schema

# Upgrade a SQLite database
mlflow db upgrade sqlite:///mlflow.db

# Upgrade a PostgreSQL database
mlflow db upgrade postgresql://user:password@localhost:5432/mlflow

Workspace Migration (Dry Run)

# Preview workspace migration
mlflow db migrate-to-default-workspace sqlite:///mlflow.db --dry-run --verbose

Workspace Migration (Execute)

# Execute workspace migration, skipping confirmation
mlflow db migrate-to-default-workspace postgresql://user:password@localhost/mlflow --yes

Related Pages

• Environment:Mlflow_Mlflow_Python_Runtime_Environment