Alembic 开源项目使用教程
1. 项目的目录结构及介绍
Alembic 是一个用于 SQLAlchemy 的数据库迁移工具。以下是 Alembic 项目的基本目录结构及其介绍:
alembic/
├── README.rst
├── alembic
│ ├── env.py
│ ├── script.py.mako
│ ├── versions/
│ │ ├── 123456789abc_add_some_columns.py
│ │ ├── ...
│ ├── README
│ ├── alembic.ini
├── setup.py
├── tests/
README.rst
: 项目介绍和使用说明。alembic/
: 核心目录,包含所有迁移脚本和配置文件。env.py
: 环境配置文件,用于设置数据库连接和迁移环境。script.py.mako
: 迁移脚本模板。versions/
: 包含所有具体的迁移脚本文件。alembic.ini
: 主配置文件,包含数据库连接字符串和其他配置选项。
setup.py
: 用于安装和分发项目的脚本。tests/
: 包含项目的测试脚本。
2. 项目的启动文件介绍
Alembic 的启动文件主要是 env.py
,它负责设置迁移环境并执行迁移脚本。以下是 env.py
的主要内容和功能:
from alembic import context
from sqlalchemy import engine_from_config, pool
# 导入你的 SQLAlchemy Base 和 engine 配置
from myapp import Base, engine
# 配置信息
config = context.config
# 绑定 SQLAlchemy Base 到 Alembic 的上下文
target_metadata = Base.metadata
# 运行迁移
def run_migrations_offline():
context.configure(
url=config.get_main_option("sqlalchemy.url"),
target_metadata=target_metadata,
literal_binds=True,
dialect_opts={"paramstyle": "named"},
)
with context.begin_transaction():
context.run_migrations()
def run_migrations_online():
connectable = engine_from_config(
config.get_section(config.config_ini_section),
prefix="sqlalchemy.",
poolclass=pool.NullPool,
)
with connectable.connect() as connection:
context.configure(
connection=connection,
target_metadata=target_metadata
)
with context.begin_transaction():
context.run_migrations()
if context.is_offline_mode():
run_migrations_offline()
else:
run_migrations_online()
env.py
文件通过context.config
读取配置文件alembic.ini
中的配置信息。- 它绑定 SQLAlchemy 的
Base
和engine
到 Alembic 的上下文。 - 根据运行模式(在线或离线),执行相应的迁移操作。
3. 项目的配置文件介绍
Alembic 的主配置文件是 alembic.ini
,它包含了数据库连接字符串和其他配置选项。以下是 alembic.ini
的主要内容和功能:
[alembic]
# 数据库连接字符串
sqlalchemy.url = sqlite:///alembic.db
# 迁移脚本目录
script_location = alembic
# 版本文件前缀
version_locations = %(script_location)s/versions
# 其他配置选项
...
sqlalchemy.url
: 数据库连接字符串,指定数据库的类型和连接信息。script_location
: 迁移脚本目录,指定存放迁移脚本的位置。version_locations
: 版本文件前缀,指定版本文件的存放位置。- 其他配置选项可以根据需要进行设置,如日志级别、自动生成选项等。
通过以上配置,Alembic 可以正确地连接到数据库并执行迁移操作。