Implementation:Evidentlyai Evidently CLI Migrate

Knowledge Sources	Evidentlyai_Evidently
Domains	CLI, Database, Migrations
Last Updated	2026-02-14 12:00 GMT

Overview

CLI commands for running and inspecting Alembic database migrations against Evidently's SQL storage backend.

Description

This module provides three components for database migration management:

run_cli_migrations(...) -- A helper function that delegates to evidently.ui.service.storage.sql.utils.run_migrations. It supports three modes: upgrade (default), downgrade, and autogenerate (creating new migration files from model changes). Each mode provides user-facing echo output describing the operation.
migrate -- A Typer CLI command registered as migrate that exposes run_cli_migrations with full CLI argument parsing. It accepts a required database URL, optional revision target, and flags for downgrade and autogenerate modes.
migrate_status -- A Typer CLI command registered as migrate-status that displays the current migration revision and full migration history using Alembic's current and history commands. It dynamically locates the Alembic configuration from the installed Evidently package and sets the sqlalchemy.url at runtime.

Usage

Use migrate to apply, rollback, or create database migrations for Evidently's SQL-backed storage. Use migrate-status to inspect which migration revision the database is currently at and view migration history. These commands require the evidently[sql] extra to be installed.

Code Reference

Source Location

Repository: Evidentlyai_Evidently
File: src/evidently/cli/migrate.py

Signature

def run_cli_migrations(
    database_url: str,
    revision: str = "head",
    downgrade: bool = False,
    autogenerate: bool = False,
    message: Optional[str] = None,
) -> None:

@app.command("migrate")
def migrate(
    database_url: str = Argument(..., help="Database connection URL"),
    revision: str = Option("head", help="Revision to upgrade/downgrade to"),
    downgrade: bool = Option(False, "--downgrade", "-d", help="Downgrade instead of upgrade"),
    autogenerate: bool = Option(False, "--autogenerate", "-a", help="Create new migration from model changes"),
    message: Optional[str] = Option(None, "--message", "-m", help="Message for new migration"),
):

@app.command("migrate-status")
def migrate_status(
    database_url: str = Argument(..., help="Database connection URL"),
):

Import

from evidently.cli.migrate import migrate, migrate_status, run_cli_migrations

I/O Contract

Inputs

Name	Type	Required	Description
database_url	str	Yes	Database connection URL (e.g., "postgresql://user:pass@localhost/db")
revision	str	No (default: "head")	Target migration revision; use "head" for latest, "-1" for one step back
downgrade	bool	No (default: False)	If True, downgrade instead of upgrade
autogenerate	bool	No (default: False)	If True, auto-generate a new migration file from model changes
message	Optional[str]	Conditional	Migration message; required when autogenerate is True

Outputs

Name	Type	Description
(side effect)	None	Applies or rolls back database migrations; prints status messages to stdout
(migrate-status)	None	Prints current revision and migration history to stdout

Usage Examples

# Upgrade to latest migration
evidently migrate postgresql://user:pass@localhost/evidently

# Upgrade to specific revision
evidently migrate postgresql://user:pass@localhost/evidently --revision abc123

# Create new migration from model changes
evidently migrate postgresql://user:pass@localhost/evidently --autogenerate -m "add new column"

# Downgrade one revision
evidently migrate postgresql://user:pass@localhost/evidently --downgrade --revision -1

# Check current migration status
evidently migrate-status postgresql://user:pass@localhost/evidently

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment