alembic使用指南

一、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 檢查庫中表是否存在

邏輯流程圖

1. 初始化 Alembic 項目
   ↓
2. 配置 alembic.ini (數據庫連接) & env.py (加載 ORM 模型, 建立連接)
   ↓
3. 定義 SQLAlchemy Base 和 ORM 模型
   ↓
4. ORM 模型發生變化?
   ├─ 是 (模型與數據庫結構不一致)
   │ ↓
   │ 5. 生成遷移文件 (alembic revision --autogenerate)
   │ (Alembic 比較 ORM 模型定義 與 MySQL 數據庫實際結構)
   │ ↓
   │ 6. 人工檢查并修改遷移文件 (確保 upgrade/downgrade 邏輯正確)
   │ ↓
   │ 7. 執行遷移 (alembic upgrade head)
   │ (Alembic 讀取遷移文件, 更新 MySQL 數據庫結構, 并更新 alembic_version 表)
   │ ↓
   └─ 否 (模型與數據庫結構一致)
   ↓
   (無需遷移)
   ↓
5. 應用程序啟動 & 與更新后的 MySQL 數據庫交互

三、常用的命令？

alembic revision --autogenerate -m "描述" 自動生成遷移腳本
alembic upgrade head  執行最新遷移
alembic current 查看當前數據庫遷移腳本
alembic stamp <revision_id> 將數據庫標記為指定版本（不執行遷移）
alembic history 查看遷移歷史

一般創建完遷移腳本后 alembic upgrade head 直接執行遷移即可。