在Litestar中使用迁移命令报错：找不到'database'命令

问题描述 #

在Litestar项目里用Advanced-Alchemy做数据库集成、Alembic处理迁移，执行迁移命令时一直报错：No such command 'database'，项目已经配置了pyproject.toml、main.py和相关模型文件。

问题原因 #

1. 搞混了Litestar和Advanced-Alchemy的CLI命令：Litestar本身没有database这个命令，迁移相关命令是Advanced-Alchemy或者Alembic提供的
2. 配置冲突：pyproject.toml里配了[tool.litestar.database]，但项目实际用的是原生SQLAlchemyPlugin，不是Advanced-Alchemy的集成方式，导致CLI识别不了配置
3. Alembic没正确关联项目的模型元数据

解决办法 #

办法一：用Advanced-Alchemy CLI跑迁移 #

1. 调整项目依赖和配置
   • 确保advanced-alchemy已经装好，pyproject.toml里保留脚本配置：

     [tool.poetry.scripts]
     advanced-alchemy = "advanced_alchemy.cli:cli"
     

   • 修改main.py，换成Advanced-Alchemy的Litestar集成，替代原生SQLAlchemyPlugin：

     from litestar import Litestar
     from litestar.openapi.config import OpenAPIConfig
     from app.controllers.user_controller import UserController
     from config import DATABASE_URL
     from advanced_alchemy.extensions.litestar import SQLAlchemyPlugin, SQLAlchemyAsyncConfig
     
     sqlalchemy_config = SQLAlchemyAsyncConfig(
         connection_string=DATABASE_URL,
         expire_on_commit=False,
         create_all=True,
     )
     alchemy = SQLAlchemyPlugin(config=sqlalchemy_config)
     
     openapi_config = OpenAPIConfig(
         title="Users API",
         version="1.0.0",
         description="API",
     )
     
     app = Litestar(
         route_handlers=[UserController],
         openapi_config=openapi_config,
         plugins=[alchemy],
     )
     
     if __name__ == "__main__":
         app.run()
     

   • 把pyproject.toml里的[tool.litestar.database]配置改成对应实际模型的路径：

     [tool.litestar.database]
     connection_string = "postgresql+asyncpg://postgres:postgres@db:5432/tasks_example"
     metadata_module = "models.tasks"  # 指向你的模型模块
     base_class = "BaseModel"  # 对应你定义的抽象基类名称
     

2. 执行迁移命令
   • 第一次用先初始化迁移目录：

     poetry run advanced-alchemy database init
     

   • 生成迁移脚本：

     poetry run advanced-alchemy database revision --autogenerate -m "初始化迁移"
     

   • 执行迁移：

     poetry run advanced-alchemy database upgrade head
     

办法二：直接用Alembic CLI跑迁移 #

要是不想换Advanced-Alchemy的集成，直接配置Alembic关联项目模型就行：

1. 初始化Alembic（还没弄过的话）：

   poetry run alembic init migrations
   

2. 修改migrations/env.py，导入项目的模型元数据：

   # 在env.py里加这段
   from models.tasks import BaseModel
   target_metadata = BaseModel.metadata
   

3. 确保pyproject.toml里的sqlalchemy.url配置正确：

   [tool.alembic]
   script_location = "migrations"
   sqlalchemy.url = "postgresql+asyncpg://postgres:postgres@db:5432/tasks_example"
   

4. 执行迁移命令：
   • 生成迁移脚本：

     poetry run alembic revision --autogenerate -m "初始化迁移"
     

   • 执行迁移：

     poetry run alembic upgrade head
     

额外提醒 #

• 模型里的BaseModel得正确继承Advanced-Alchemy的基类，所有实体模型都要继承这个抽象基类
• 执行命令前记得激活虚拟环境，或者用poetry run前缀
• 要是用的异步数据库，Alembic得额外配置异步支持，可以在env.py里把同步引擎换成异步引擎

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