CLI

Advanced Alchemy provides a command-line interface for database migrations and management.

Prerequisites

  • Python 3.9+

  • Advanced Alchemy installed with cli extra

Installation

Install Advanced Alchemy with CLI support:

Using pip
python3 -m pip install advanced-alchemy[cli]
Using UV
uv add advanced-alchemy[cli]
Using pipx
pipx install advanced-alchemy[cli]
Using PDM
pdm add advanced-alchemy[cli]
Using Poetry
poetry add advanced-alchemy[cli]

Overview

The CLI provides:

  • Database migration management

  • Migration history inspection

  • Branch management for migrations

  • Database utilities (drop, dump)

  • Extensibility for custom commands

Basic Usage

The CLI can be invoked using the alchemy command:

alchemy --help

Global Options

Global options

Option

Explanation

--config TEXT

Required. Dotted path to SQLAlchemy config(s), it’s an instance of SQLAlchemyConfig (sync or async). Example: --config path.to.alchemy-config.config

--bind-key TEXT

Optional. Specify which SQLAlchemy config to use

--no-prompt

Optional. Skip confirmation prompts

--verbose

Optional. Enable verbose output

Configuration

Create a configuration file for the CLI:

alchemy-config.py
from advanced_alchemy.config import SQLAlchemyAsyncConfig

# Create config using your database
config = SQLAlchemyAsyncConfig(
    connection_string="postgresql+asyncpg://user:pass@localhost/db"
)

If the file is named alchemy-config.py, use it like this:

alchemy <command> --config path.to.alchemy-config.config

Quick Start

Initialize migrations:

alchemy init --config path.to.alchemy-config.config

Create a migration:

alchemy make-migrations -m "initial schema" --config path.to.alchemy-config.config

Apply migrations:

alchemy upgrade --config path.to.alchemy-config.config

Next Steps

  • Migrations - Migration workflow and troubleshooting

  • Commands - Complete command reference