SQLModel 的 create_all() 仅在表不存在时创建，不会修改已存在的表结构；若需响应模型变更（如新增字段、修改类型），必须借助 Alembic 等迁移工具进行版本化、可回滚的 schema 更新。
sqlmodel 的 `create_all()` 仅在表不存在时创建，不会修改已存在的表结构；若需响应模型变更（如新增字段、修改类型），必须借助 alembic 等迁移工具进行版本化、可回滚的 schema 更新。
SQLModel 基于 SQLAlchemy 构建，其 create_all() 方法本质是调用 SQLAlchemy 的同名函数。该方法设计为幂等且非侵入式：它只会检查元数据中定义的表是否在数据库中存在，若不存在则创建；若已存在，则跳过——绝不会 ALTER TABLE、添加列、修改约束或删除字段。因此，当你修改 Vehicle 模型（例如将 vehicle_name: str | None 改为 vehicle_name: str = Field(default="unknown")），再次运行 Vehicle.metadata.create_all(engine) 不会产生任何数据库变更。
✅ 正确做法：使用 Alembic 实现可控、可追溯的数据库迁移。
Alembic 是 SQLAlchemy 官方推荐的迁移工具，支持自动生成差异脚本、手动编辑迁移逻辑、升级/降级版本，并与 SQLModel 完全兼容。以下是典型工作流：
-
初始化 Alembic 环境（首次执行）：
pip install alembic alembic init alembic
-
配置 alembic.ini 和 alembic/env.py：
在 env.py 中导入你的模型并设置 target_metadata：# alembic/env.py（关键片段） from sqlmodel import SQLModel from your_app.models import Vehicle # 替换为实际路径
def run_migrations_online():
一款AI音频处理工具，主要用于MiniMax统一媒体生成技能，用于TokenPlan工作流。当用户要求生成音频、语音、TTS、旁白、图片、插图、姿势等媒体内容时使用，适合需要提升相关任务效率的用户。
... 省略连接配置 ...
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=SQLModel.metadata, # ✅ 关键：指向 SQLModel 全局 metadata
)
# ...
3. **生成迁移脚本（自动检测模型差异）**： ```bash alembic revision --autogenerate -m "Add not_null constraint to vehicle_name"
Alembic 将对比当前模型与数据库实际 schema，生成类似 alembic/versions/xxx_add_not_null_constraint.py 的脚本，其中包含 upgrade() 和 downgrade() 函数。
-
应用迁移：
alembic upgrade head
⚠️ 注意事项：
- --autogenerate 并非万能：对重命名列、拆分表等复杂变更需手动补全迁移逻辑；
- 生产环境务必先在测试库验证迁移脚本，避免 upgrade 失败导致数据丢失；
- 不要直接修改已提交的迁移文件——应通过新迁移修正，保持历史线性可追溯；
- 开发阶段可配合 SQLModel.metadata.drop_all(engine) + create_all() 快速重置（仅限本地/测试环境，严禁用于生产）。
总结：SQLModel 聚焦于数据建模与 ORM 操作，而非 schema 演进管理。将 create_all() 视为“初始化工具”，而将 Alembic 视为“演进引擎”——二者分工明确，协同构建健壮的数据层基础设施。
