企业官网建设流程全解析

一、alembic是什么？

Alembic 是一个用于 Python 数据库迁移和版本控制的工具。它与 SQLAlchemy（一个流行的 Python ORM 库）紧密集成，共同为 Python 应用程序提供数据库管理和迁移支持。

python使用mysql时常用SQLAlchemy+Alembic进行ORM和数据库迁移。

二、如何集成到项目中？

1.安装

uv install alembic==1.13.0 or pip install alembic==1.13.0

2.进入项目根目录 初始化Alembic

2.1 终端执行 alembic init alembic init 初始化命令 alembic 环境名称

项目中多出alembic目录

alembic.ini: Alembic 的主配置文件。

env.py: Alembic 运行时环境的 Python 脚本，用于配置 SQLAlchemy 引擎和元数据。

script.py.mako: 迁移脚本的模板文件。

versions/: 存放所有迁移脚本的目录。

图片

2.2 配置 alembic.ini（指定数据库连接字符串）

通过环境变量读取 不要硬编码

图片

2.3 配置 env.py （告诉 Alembic 你的 SQLAlchemy 模型在哪里，以便它能够进行自动检测。）

找到 target_metadata 变量，将其指向你的 SQLAlchemy Base.metadata 对象。

图片

解释一下：Base对象是所有模型类的基类，你创建的所有模型都要继承Base

from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

创建Base虽然创建在哪都可以，最好放在数据库连接层，结构清晰，目录结构如下

图片

2.4 创建SQLAlchemy模型

所有模型集成Base对象，这样后面执行迁移就会自动检测所有更改的字段

图片

3.生成第一个迁移脚本

要提前安装 pip install pymysql

3.1 自动生成

终端输入命令： alembic revision --autogenerate -m "Create initial tables"

alembic revision: 创建一个新的数据库迁移脚本。

--autogenerate: 自动检测你的 SQLAlchemy 模型与数据库当前状态的差异，并生成相应的升级/降级 SQL 语句。

-m "Create initial tables": 为这个迁移脚本添加一个描述性消息，方便你理解其目的。

图片

图片

检查生成的迁移文件sql命令是否正常 不正常就手动或者找ai修复下

3.2 手动生成（推荐）

第一次创建迁移文件 上一次版本号为None

后续按照现有的文件格式创建新的迁移即可，版本号使用基于时间戳的uuid即可，上一个版本的版本号记得填。

upgrade：对应新的sql操作

downgrade：操作失败回滚

有时候alembic对于修改和删除的字段检测不出来，最好就手写迁移脚本

4.执行迁移

终端命令 alembic upgrade head 检查库中表是否存在

图片

逻辑流程图

初始化 Alembic 项目

↓

配置 alembic.ini (数据库连接) & env.py (加载 ORM 模型, 建立连接)

↓

定义 SQLAlchemy Base 和 ORM 模型

↓

ORM 模型发生变化?

├─ 是 (模型与数据库结构不一致)

│ ↓

│ 5. 生成迁移文件 (alembic revision --autogenerate)

│ (Alembic 比较 ORM 模型定义 与 MySQL 数据库实际结构)

│ ↓

│ 6. 人工检查并修改迁移文件 (确保 upgrade/downgrade 逻辑正确)

│ ↓

│ 7. 执行迁移 (alembic upgrade head)

│ (Alembic 读取迁移文件, 更新 MySQL 数据库结构, 并更新 alembic_version 表)

│ ↓

└─ 否 (模型与数据库结构一致)

↓

(无需迁移)

↓

应用程序启动 & 与更新后的 MySQL 数据库交互

三、常用的命令？

alembic revision --autogenerate -m "描述" 自动生成迁移脚本

alembic upgrade head 执行最新迁移

alembic current 查看当前数据库迁移脚本

alembic stamp <revision_id> 将数据库标记为指定版本（不执行迁移）

alembic history 查看迁移历史