Sqlmodel/Sqlalchemy报错：无法为映射表组装主键列

核心问题分析 #

报错本质是SQLAlchemy（SQLModel基于它）无法将Student模型正确映射到数据库student表，主要由两个原因导致：

1. 模型加载时机错误，执行create_all时Student模型未注册到SQLModel.metadata
2. 模型字段名与数据库表字段名完全不匹配，引发ORM映射失败

具体解决步骤 #

1. 调整模型导入顺序，确保create_all前加载所有模型

SQLModel需要将模型注册到全局metadata对象中，才能正确创建表或完成ORM映射。当前代码先执行init_engine()，之后才导入路由（间接导入模型），导致SQLModel.metadata.create_all()运行时没有Student表的信息。

修改main.py，先导入模型再初始化引擎：

from fastapi import FastAPI

# 先导入所有模型，确保注册到SQLModel.metadata
from src.models.student import Student
from src.dependencies.sqlmodel import init_engine

def main():
    init_engine()

main()

from src.routes.routes import api_router
app = FastAPI()
app.include_router(api_router)

更规范的做法是在src/models/__init__.py中导出所有模型：

from .student import Student

然后在main.py中批量导入：

from src.models import *

2. 统一模型字段与数据库表字段名

你的Student模型字段为nombre、apellido、edad，但Alembic迁移脚本中创建的表字段是name、last_name、age，两者完全不匹配，导致ORM无法识别表结构。

方案一：修改模型字段名匹配数据库

from sqlmodel import SQLModel, Field

class StudentBase(SQLModel):
    name: str
    last_name: str
    age: int | None = Field(default=None, ge=17)

class Student(StudentBase, table=True):
    identifier: int = Field(primary_key=True)

方案二：给模型字段添加别名匹配数据库
如果不想修改模型字段名，可通过alias参数映射到数据库字段：

from sqlmodel import SQLModel, Field

class StudentBase(SQLModel):
    nombre: str = Field(alias="name")
    apellido: str = Field(alias="last_name")
    edad: int | None = Field(default=None, ge=17, alias="age")

class Student(StudentBase, table=True):
    identifier: int = Field(primary_key=True)

注意：后续使用Alembic生成迁移脚本时，要确保脚本字段名与模型一致，避免再次冲突。

3. 修复依赖文件中的缺失导入

src/dependencies/sqlmodel.py缺少必要的导入，补充后才能正常运行：

import os
from typing import Generator, Annotated
from fastapi import Depends
from sqlmodel import SQLModel, create_engine, Session

root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../.."))
SQLITE_FILE_PATH = os.path.join(root, "database.db")

__engine = None

def init_engine():
    global __engine
    print(SQLITE_FILE_PATH)
    __engine = create_engine(f"sqlite:///{SQLITE_FILE_PATH}", echo=True)
    SQLModel.metadata.create_all(__engine)

def get_session() -> Generator[Session, None, None]:
    with Session(__engine) as session:
        yield session
SessionDep = Annotated[Session, Depends(get_session)]

4. 重置数据库（可选）

如果之前的数据库表结构混乱，可删除现有的database.db文件，重新运行项目让SQLModel自动创建正确的表结构（需确保模型导入顺序正确），或者重新生成Alembic迁移脚本并执行。

内容的提问来源于stack exchange，提问作者fedest