SQLAlchemy Alembic：数据库模式迁移与版本控制

各位观众老爷们，大家好！

今天咱们要聊聊数据库界的“时光机”—— SQLAlchemy Alembic。 这玩意儿可不是真的能让你回到过去改 Bug， 而是用来管理数据库模式变更的， 也就是咱们俗称的“数据库迁移”。 想象一下，你开发了一个网站，数据库结构改了一版又一版， 每次上线都得手动改数据库表结构， 稍微不小心， 数据就给你搞丢了， 简直是噩梦！ Alembic 就是来解决这个问题的， 它能帮你自动生成数据库迁移脚本， 记录每次变更， 让你可以轻松地升级、降级数据库， 就像玩游戏存档一样。

为什么要用 Alembic？ 数据库迁移的痛点

在深入 Alembic 的用法之前，咱们先来聊聊为什么要用它， 以及不用它会面临哪些“惨痛”的经历。

• 手动修改数据库表结构，容易出错。 手写的 SQL 脚本一不小心写错个字段名、类型， 整个数据库就瘫痪了。
• 团队协作时，数据库变更难以同步。 你改了一张表， 我改了一张表， 大家都不知道对方改了啥， 结果上线的时候冲突了，吵起来了。
• 版本回滚困难。 如果新版本出了问题，想回到上一个版本， 手动改数据库简直是灾难， 费时费力还容易出错。
• 数据库变更历史难以追踪。 时间长了， 谁也记不清数据库都改了哪些地方， 出了问题排查困难。

Alembic 就是为了解决这些痛点而生的， 它可以：

• 自动化生成迁移脚本，减少手动操作，降低出错概率。
• 规范数据库变更流程，方便团队协作。
• 轻松回滚到任意版本，保证数据安全。
• 记录数据库变更历史，方便追踪和排查问题。

Alembic 的核心概念：

要玩转 Alembic， 首先要了解它的几个核心概念：

• Migration Repository (迁移仓库): 存放所有迁移脚本的地方， 就像一个代码仓库， 记录了数据库的每一次变更。
• Revision (修订版本): 代表数据库的一次变更， 每个 Revision 都有一个唯一的 ID 和相应的迁移脚本。
• Head (最新版本): 当前数据库模式的最新版本。
• Upgrade (升级): 将数据库模式从一个版本升级到另一个版本。
• Downgrade (降级): 将数据库模式从一个版本降级到另一个版本。

Alembic 的安装与配置：

废话不多说， 咱们直接上手！

1. 安装 Alembic：

   pip install alembic

2. 初始化 Alembic：

   alembic init alembic

   这条命令会在当前目录下创建一个名为 alembic 的目录， 里面包含了 Alembic 的配置文件 alembic.ini 和迁移脚本目录 versions。

3. 配置 alembic.ini：

   alembic.ini 文件是 Alembic 的配置文件， 我们需要修改其中的 sqlalchemy.url 属性， 指定数据库连接字符串。

   sqlalchemy.url = postgresql+psycopg2://username:password@host:port/database_name

   请把上面的 username、password、host、port、database_name 替换成你自己的数据库信息。

4. 配置 env.py：

   env.py 文件是 Alembic 的环境配置文件， 我们需要在里面配置 SQLAlchemy 的 metadata 对象， 告诉 Alembic 哪些表需要进行迁移。

   # env.py
   from sqlalchemy import create_engine
   from sqlalchemy.orm import sessionmaker
   from sqlalchemy.ext.declarative import declarative_base
   from sqlalchemy import Column, Integer, String
   
   # 数据库连接字符串
   SQLALCHEMY_DATABASE_URL = "postgresql+psycopg2://username:password@host:port/database_name"
   
   # 创建 SQLAlchemy 引擎
   engine = create_engine(SQLALCHEMY_DATABASE_URL)
   
   # 创建 SessionLocal 类
   SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
   
   # 创建 Base 类
   Base = declarative_base()
   
   # 定义模型类
   class User(Base):
       __tablename__ = "users"
   
       id = Column(Integer, primary_key=True, index=True)
       name = Column(String, index=True)
       email = Column(String, unique=True, index=True)
   
   # 导入 Base.metadata
   target_metadata = Base.metadata

   在这个例子中， 我们定义了一个 User 模型类， 并将其 metadata 赋值给 target_metadata。 Alembic 会根据这个 metadata 来生成迁移脚本。

Alembic 的常用命令：

Alembic 提供了一系列命令来管理数据库迁移， 下面是一些常用的命令：

命令	描述
alembic revisions	列出所有已经创建的 revisions。
alembic current	显示数据库当前所处的 revision。
alembic history	显示数据库的 revision 历史记录。
alembic revision -m "message"	创建一个新的 revision， 并添加注释信息。-m 参数用于指定注释信息， 方便你记住这次变更的内容。
alembic upgrade head	将数据库升级到最新版本。
alembic upgrade <revision>	将数据库升级到指定的 revision。 <revision> 可以是 revision 的 ID， 也可以是 "head" (最新版本) 或 "base" (初始版本)。
alembic downgrade <revision>	将数据库降级到指定的 revision。
alembic stamp head	将数据库标记为最新版本， 但不执行任何迁移操作。 这个命令通常用于在新的环境中部署数据库， 并且数据库已经是最新的情况下。
alembic edit <revision>	编辑指定的 revision 脚本。
alembic show <revision>	显示指定的 revision 脚本的内容。

Alembic 的使用流程：

有了上面的基础知识， 咱们就可以开始使用 Alembic 了。

1. 定义模型类：

   首先， 我们需要定义 SQLAlchemy 的模型类， 描述数据库的表结构。

   # models.py
   from sqlalchemy import Column, Integer, String, DateTime
   from sqlalchemy.ext.declarative import declarative_base
   from sqlalchemy.sql import func
   
   Base = declarative_base()
   
   class User(Base):
       __tablename__ = "users"
   
       id = Column(Integer, primary_key=True, index=True)
       name = Column(String, index=True)
       email = Column(String, unique=True, index=True)
       created_at = Column(DateTime(timezone=True), server_default=func.now())

2. 修改 env.py：

   将模型类的 metadata 赋值给 target_metadata。

   # env.py
   from models import Base
   
   target_metadata = Base.metadata

3. 创建初始迁移脚本：

   alembic revision -m "Create users table"

   这条命令会创建一个新的迁移脚本， 位于 alembic/versions 目录下。 脚本的名字类似 xxxxxxxxxxxx_create_users_table.py， 其中 xxxxxxxxxxxx 是一个时间戳。

4. 修改迁移脚本：

   打开新创建的迁移脚本， 可以看到两个函数 upgrade() 和 downgrade()。 upgrade() 函数用于升级数据库， downgrade() 函数用于降级数据库。

   我们需要在 upgrade() 函数中编写创建 users 表的逻辑， 在 downgrade() 函数中编写删除 users 表的逻辑。

   # alembic/versions/xxxxxxxxxxxx_create_users_table.py
   """Create users table
   
   Revision ID: xxxxxxxxxxxx
   Revises:
   Create Date: 2023-10-27 10:00:00.000000
   
   """
   from alembic import op
   import sqlalchemy as sa
   
   # revision identifiers, used by Alembic.
   revision = 'xxxxxxxxxxxx'
   down_revision = None
   branch_labels = None
   depends_on = None
   
   def upgrade() -> None:
       op.create_table(
           "users",
           sa.Column("id", sa.Integer, primary_key=True, index=True),
           sa.Column("name", sa.String, index=True),
           sa.Column("email", sa.String, unique=True, index=True),
           sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
       )
   
   def downgrade() -> None:
       op.drop_table("users")

   Alembic 提供了 op 对象， 里面包含了很多用于操作数据库的函数， 比如 create_table()、drop_table()、add_column()、drop_column() 等。

5. 升级数据库：

   alembic upgrade head

   这条命令会将数据库升级到最新版本， 也就是执行 upgrade() 函数。

6. 添加新的字段：

   假设我们需要给 users 表添加一个 age 字段。

   alembic revision -m "Add age column to users table"

   修改新创建的迁移脚本：

   # alembic/versions/yyyyyyyyyyyy_add_age_column_to_users_table.py
   """Add age column to users table
   
   Revision ID: yyyyyyyyyyyy
   Revises: xxxxxxxxxxxx
   Create Date: 2023-10-27 10:30:00.000000
   
   """
   from alembic import op
   import sqlalchemy as sa
   
   # revision identifiers, used by Alembic.
   revision = 'yyyyyyyyyyyy'
   down_revision = 'xxxxxxxxxxxx'
   branch_labels = None
   depends_on = None
   
   def upgrade() -> None:
       op.add_column("users", sa.Column("age", sa.Integer, nullable=True))
   
   def downgrade() -> None:
       op.drop_column("users", "age")

   然后再次升级数据库：

   alembic upgrade head

7. 回滚数据库：

   如果新的迁移脚本出了问题， 我们可以回滚到上一个版本：

   alembic downgrade xxxxxxxxxxxx

   其中 xxxxxxxxxxxx 是上一个版本的 Revision ID。

Alembic 的高级用法：

除了基本的用法， Alembic 还提供了一些高级功能， 可以满足更复杂的需求。

• 自动生成迁移脚本：

  Alembic 可以自动比较数据库的当前状态和模型类的定义， 然后生成迁移脚本。 这可以大大减少手动编写迁移脚本的工作量。

  alembic revision --autogenerate -m "Autogenerate migration"

  需要注意的是， 自动生成的迁移脚本可能并不完美， 需要仔细检查和修改。

• 使用 Hooks：

  Alembic 提供了 Hooks， 允许你在迁移过程中的不同阶段执行自定义代码。 比如， 你可以在迁移开始前备份数据库， 在迁移完成后发送通知。

  Alembic Hooks 的配置位于 env.py 文件中。

• 多数据库支持：

  Alembic 支持多个数据库， 你可以在 alembic.ini 文件中配置多个数据库连接字符串， 然后在迁移脚本中使用不同的连接。

• Offline 模式：

  在某些情况下， 你可能需要在没有数据库连接的情况下生成迁移脚本。 Alembic 提供了 Offline 模式， 允许你这样做。

Alembic 的最佳实践：

• 每次修改数据库结构都要创建新的迁移脚本。
• 在迁移脚本中添加详细的注释， 方便理解和维护。
• 在开发环境中充分测试迁移脚本。
• 使用版本控制系统 (比如 Git) 管理迁移脚本。
• 定期备份数据库。

总结：

Alembic 是一个强大的数据库迁移工具， 它可以帮助你轻松地管理数据库模式变更， 提高开发效率， 保证数据安全。 希望通过今天的讲解， 大家能够掌握 Alembic 的基本用法， 并在实际项目中灵活运用。 记住， 数据库迁移就像给数据库做手术， 一定要小心谨慎， 做好充分的准备， 才能避免出现意外。

好了， 今天的分享就到这里， 感谢大家的观看！ 如果有什么问题， 欢迎在评论区留言， 我会尽力解答。 咱们下期再见！