alembic 教程

用来做 orm 模型与数据库的迁移与映射。使用方式跟 git类似，表现在两个方面：

1. alembic 的所有命令都以 alembic 开头；
2. alembic 的迁移文件也是铜鼓版本进行控制的。

安装方式：

pip install alembic

用法：

1. 初始化 alembic 仓库：

在终端中，cd 到项目目录，然后执行 alembic init alembic,创建一个名字叫 alembic 的仓库。

2. 创建模型类： 创建一个 models.py 模块，然后在里面定义自己的模型。示例如下：

engine = create_engine(DB_URI)  # 创建数据库引擎
Base = declarative_base(engine)  # 基类


class User(Base):
    __tablename__ = 'user'
    id = Column(Integer, autoincrement=True, primary_key=True)
    name = Column(String(30), nullable=False)
    age = Column(Integer, default=0)

    def __init__(self, id, name):
        self.id = id
        self.name = name

    def __repr__(self):
        return "<User (name:{})>".format(self.name)

3. 修改配置文件：

• 在 alembic.ini中设置数据库的连接，
  sqlalchemy.url = driver://user:pass@localhost/dbname,示例如下：

sqlalchemy.url = mysql+mysqldb://root:chenkuan1110@localhost/alembic_demo?charset=utf8

• 为了使模型类跟新到数据库，需要在 env.py 文件中设置 target_metadata,默认为target_metadata=None。

from models import Base
... # 省略代码
target_metadata = Base.metadata  # 设置创建模型的元类
... # 省略代码

4. 自动生成迁移文件： 使用 alembic revision --autogenerate -m 'message' 将当前模型中的状态生成迁移文件。

5. 跟新数据库： 使用 alembic upgrade head 将刚刚生成的迁移文件，真正导入数据库中。
   同理，如果需要降级，那么使用 alembic downgrade head。

6. 修改代码后，重复操作 4～5的步骤。

7. 命令和参数解释：

   • init: 创建一个 alembic 仓库。
   • revision: 创建一个新的版本文件。
   • --autogenerate: 自动将当前模型的修改，生成迁移脚本。
   • -m : 本次迁移做了哪些修改，可以可以指定这个参数，方便回顾。
   • upgrade ：将指定版本的迁移文件映射到数据库中，会执行版本文件的 upgrade 函数。
   • head: 代表当前的迁移版本的版本号。
   • downgrade: 会执行指定版本的文件中的 downgrade 函数。
   • heads : 展示当前可用的 heads 脚本文件。
   • history : 列出所有的迁移版本及其信息。
   • current ：展示当前数据库中的版本号。

另外，在第一次执行 upgrade 的时候会在数据库中创建一个叫做 alembic_version 表，这个表只有一个数据，记录当前数据库映射的是哪个版本的迁移文件。

经典错误：

错误描述	原因	解决办法
FAILED: Target database is not up to data.	主要原因是 heads 和 current 不相同。 current 落后于 heads 版本。	将 current 移动到 head上。 alembic upgrad head
FAILED: Can't locate revision identifed by 'xxxxxxx'	数据库中存的版本号不在迁移脚本文件中	删除数据库中 alembic_version 表中的数据，重新执行 alembic upgrade head