Environment:Evidentlyai Evidently SQL Storage Environment

Knowledge Sources	Evidently pyproject.toml sql extras
Domains	Infrastructure, Storage
Last Updated	2026-02-14 10:00 GMT

Overview

Optional environment adding SQLAlchemy, Alembic, and PostgreSQL support for persistent storage of Evidently UI workspaces, snapshots, and datasets.

Description

This environment extends the core Evidently installation with SQL-based storage capabilities. It enables the Evidently UI service to persist project metadata, snapshots, metric data, and datasets in a PostgreSQL database instead of the default file-based storage. It includes Alembic for database schema migrations.

Usage

Use this environment when deploying the Evidently UI service with persistent SQL storage, running database migrations, or using the Docker-based service deployment. Required for production deployments that need durable storage beyond local files.

System Requirements

Category	Requirement	Notes
OS	Any (Linux, macOS, Windows)	Same as core environment
Python	>= 3.10	Same as core environment
Database	PostgreSQL >= 12	Or SQLite for local development
Network	Database connectivity	Access to PostgreSQL instance

Dependencies

Python Packages

`sqlalchemy` >= 2.0.0
`psycopg2-binary` >= 2.9.0
`alembic` >= 1.13.0

Credentials

The following environment variables are used:

`EVIDENTLY_SECRET`: Secret token for securing the Evidently UI service API.
`EVIDENTLY_DEBUG`: Set to any value to enable debug mode in the UI service.
`EVIDENTLY_API_KEY`: API token for `CloudWorkspace` authentication (reads from env if not passed as argument).
Database URL is passed as a CLI argument or via configuration file, not an environment variable.

Quick Install

# Install Evidently with SQL storage support
pip install evidently[sql]

Code Evidence

SQL import guard from `src/evidently/ui/service/storage/sql/__init__.py:1-7`:

try:
    import alembic  # noqa: F401
    import sqlalchemy  # noqa: F401
except ImportError as e:
    raise ImportError(
        "SQLAlchemy is required for SQL storage support. "
        "Please install it with: pip install evidently[sql]"
    ) from e

Alembic migration import guard from `src/evidently/cli/migrate.py:81-86`:

try:
    from alembic import command
    from alembic.config import Config
except ImportError as e:
    raise ImportError(
        "Alembic is required for migrations. Please install it with: pip install evidently[sql]"
    ) from e

CloudWorkspace API key validation from `src/evidently/ui/workspace.py:1344-1347`:

token = os.environ.get("EVIDENTLY_API_KEY", default=None)
if token is None:
    raise ValueError(
        "To use CloudWorkspace you must provide a token through argument or env variable EVIDENTLY_API_KEY"
    )

Common Errors

Error Message	Cause	Solution
`ImportError: SQLAlchemy is required for SQL storage support`	sqlalchemy or alembic not installed	`pip install evidently[sql]`
`ImportError: Alembic is required for migrations`	alembic not installed	`pip install evidently[sql]`
`ValueError: To use CloudWorkspace you must provide a token`	No API key provided for cloud workspace	Set `EVIDENTLY_API_KEY` env var or pass `token` argument
`--message is required when using --autogenerate`	Migration autogenerate called without message	Add `-m "description"` to the migrate command

Compatibility Notes

SQLite: Supported for local development via SQLAlchemy, but PostgreSQL is recommended for production.
Docker deployment: The official Docker image (`docker/Dockerfile.service`) uses `INSTALL_EXTRAS="[sql]"` to include SQL support by default.
PostgreSQL 16: The Docker Compose example uses `postgres:16-alpine`.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment