alembic

用途

本技能提供在客户支持环境中使用 Alembic 管理数据库迁移的全面指导，覆盖从初始设置到复杂生产部署场景，重点在于维护数据完整性并尽量减少支持业务的中断时间。

Alembic 是一个配合 SQLAlchemy 使用的轻量级数据库迁移工具，通过受版本控制的迁移脚本管理数据库模式随时间的变化。对客户支持系统而言，这意味着：版本控制（跟踪支持数据库的所有模式变更）、可复现性（在开发、预发和生产环境应用相同迁移）、回滚能力（安全撤销有问题的变更）、团队协作（合并多位开发者的模式变更）、数据保留（在模式转换期间迁移数据）。

支持系统中的迁移生命周期包括：开发（本地创建迁移）、测试（在预发环境验证）、审查（生产前代码审查迁移脚本）、部署（以最小停机时间应用到生产）、监控（跟踪迁移状态并处理失败）、回滚（生产出现问题时撤销）。

主要能力

安装与初始化：安装 Alembic 及 PostgreSQL 支持，初始化项目目录与配置文件，配置数据库连接（支持环境变量）。
创建迁移：支持手动创建迁移以获得精确控制，也支持通过 autogenerate 自动检测模式变更。
数据迁移：在模式变更期间转换现有数据，包括大批量数据的分批处理。
运行迁移：升级到最新或指定版本、降级、查看当前状态与迁移历史。
分支与合并：支持特性分支、热修复分支、团队分支，以及跨分支依赖与合并。
测试迁移：提供单元测试与集成测试示例，验证迁移创建的表结构、升级降级循环及数据保留。

使用方式

安装命令：

# Install Alembic with PostgreSQL support
pip install alembic psycopg2-binary sqlalchemy

# Or add to requirements.txt
alembic>=1.13.0
sqlalchemy>=2.0.0
psycopg2-binary>=2.9.0

初始化：

# Initialize Alembic (creates alembic/ directory and alembic.ini)
alembic init alembic

# For multiple database support
alembic init --template multidb alembic

初始化后生成 alembic/ 目录（含 versions/ 迁移文件目录与 env.py 环境配置）、alembic.ini 配置文件。可在 alembic.ini 中设置数据库 URL，更推荐在 env.py 中通过环境变量覆盖。

创建迁移：

# Create empty migration file
alembic revision -m "add ticket priority column"

# Generate migration by comparing models to database
alembic revision --autogenerate -m "add customer satisfaction table"

注意：自动生成的迁移务必审查，它可能遗漏重命名列（表现为删除加新增）、需要数据转换的列类型变更、复杂约束和数据迁移。

运行迁移：

# Upgrade to latest revision (head)
alembic upgrade head

# See what would be executed (SQL only, don't run)
alembic upgrade head --sql

# Upgrade one step at a time
alembic upgrade +1

# Upgrade to specific revision
alembic upgrade abc123

# Downgrade one revision
alembic downgrade -1

# Downgrade to specific revision
alembic downgrade abc123

# Downgrade to base (empty database)
alembic downgrade base

# Show current database revision
alembic current

# Show migration history
alembic history

分支与合并：

# Create base for new branch
alembic revision -m "create reporting branch" \
    --head=base \
    --branch-label=reporting \
    --version-path=alembic/versions/reporting

# Show all branch heads
alembic heads

# Upgrade all branches
alembic upgrade heads

# Merge two branches
alembic merge -m "merge reporting into main" \
    main@head reporting@head

适用场景

适用于使用 SQLAlchemy 的客户支持系统，需要在开发、预发、生产环境之间同步数据库模式变更，需要安全回滚、团队并行开发、在模式转换期间保留或转换数据，以及需要以最小停机时间完成生产部署的场景。

限制

资料未提供关于收费、价格、平台支持范围、性能指标或效果保证的信息。自动生成的迁移可能遗漏重命名列、需数据转换的类型变更、复杂约束和数据迁移，必须人工审查。大批量数据迁移需分批处理以避免内存问题。

技能介绍

用途

主要能力

使用方式

适用场景

限制