Python Async Beanie ODM 迁移功能失效问题求助

问题 #

我想把旧模型的数据迁移到带额外字段的新模型，试了迭代迁移和自由落体迁移都没生效。运行命令：

beanie migrate -uri <connection-string> -db <db-name> -p  <path/to/*_migrate.py> --distance 1  --forward

控制台只输出：

Building migration list

以下是和实际代码类似的示例：

from beanie import Document, free_fall_migration

class OldModel(Document):
    name: str

class NewModel(Document):
    name: str
    new_field: str

class Forward:

    @free_fall_migration(document_models=[OldModel, NewModel])
    async def add_new_field(self, session):
        async for old_data in OldModel.find_all():
            new_data = NewModel(
                **old_data.dict(),
                new_field='yay'
            )
            await new_data.replace(session=session)


class Backward:
    @free_fall_migration(document_models=[OldModel, NewModel])
    async def remove_new_field(self, session):
        async for new_data in NewModel.find_all():
            new_data_dict = new_data.dict()
            new_data_dict.pop('new_field')
            old_data = OldModel(
                **new_data_dict
            )
            await old_data.replace(session=session)

当前环境：

• 操作系统：Windows 11
• Python版本：3.9.x
• Beanie版本：1.18.0b
• MongoDB版本：5

可能的问题与解决步骤 #

1. 模型集合名称不统一 #

OldModel和NewModel默认会使用类名小写作为集合名称（oldmodel和newmodel），但实际迁移应该在同一个集合内更新文档结构。需要给两个模型指定相同的集合名：

from beanie import Document, free_fall_migration

class OldModel(Document):
    name: str

    class Settings:
        collection_name = "your_collection_name"  # 指定统一集合名

class NewModel(Document):
    name: str
    new_field: str

    class Settings:
        collection_name = "your_collection_name"  # 和OldModel保持一致

2. 迁移文件命名不符合规范 #

Beanie要求迁移文件遵循{版本号}_{描述}_migrate.py的命名格式，比如0001_add_new_field_migrate.py，版本号必须是递增的数字序列。如果文件名不符合这个规则，Beanie无法识别迁移类，只会停留在"Building migration list"阶段。

3. Beta版本可能存在兼容性问题 #

你使用的Beanie版本是1.18.0b（beta版），可能存在未修复的迁移逻辑bug。建议升级到最新稳定版：

pip install --upgrade beanie

4. 命令参数调整 #

自由落体迁移不需要--distance参数，该参数是为迭代迁移设计的。尝试简化命令：

beanie migrate -uri <connection-string> -db <db-name> -p <path/to/migrate_files> --forward

注意：-p参数指向的是迁移文件所在的目录，而不是通配符路径（Windows下通配符可能无法被正确解析）。

5. 迁移逻辑的优化 #

原代码中使用replace方法可能会导致文档ID冲突（如果新旧模型的ID字段一致），可以改为更高效的直接更新写法：

# Forward迁移的优化写法
@free_fall_migration(document_models=[OldModel, NewModel])
async def add_new_field(self, session):
    # 直接批量更新集合中的文档，无需创建新模型实例
    await OldModel.get_motor_collection().update_many(
        {},
        {"$set": {"new_field": "yay"}},
        session=session
    )

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