You need to enable JavaScript to run this app. 如何在flask_sqlalchemy中使用SQLite的UPSERT(ON CONFLICT)?
优惠活动
大模型
产品
解决方案
定价
更多

如何在flask_sqlalchemy中使用SQLite的UPSERT(ON CONFLICT)?

问题根因说明

你之前配置完全不生效的核心原因有两个:

  • sqlite_on_conflict 参数仅可绑定到主键约束、唯一约束、唯一索引上,用于指定冲突时的处理逻辑,你之前把该参数加在外键约束定义上属于挂载对象错误,SQLAlchemy不会把这个参数编译到最终生成的SQL语句中
  • SQLite 原生支持UPSERT语法是从3.24版本才引入的,对应SQLAlchemy对原生UPSERT的支持是从1.4版本才正式落地的,1.3版本即使参数挂载位置正确,也仅能兼容生成旧版的INSERT OR IGNORE语法,无法实现冲突时更新字段的完整UPSERT能力
结合Flask-SQLAlchemy的正确实现方案

以下方案基于SQLAlchemy 1.4以上版本,适配SQLite的原生UPSERT能力,不需要手动做存在性校验。

场景1:冲突时直接忽略插入(等价于INSERT OR IGNORE)

有两种实现方式可选:

  • 方式一:静态表定义配置
    把冲突处理参数挂载到对应的唯一约束/主键约束上,适合所有针对该表的插入操作都需要默认忽略冲突的场景,正确示例:
    class SomeModel(db.Model):
        __table_args__ = (
            # 外键定义正常编写,不需要加冲突参数
            db.ForeignKeyConstraint(
                ('id', 'other_id'),
                ('other_table.id', 'other_table.other_id')
            ),
            # 把冲突参数挂到对应的唯一约束上
            db.UniqueConstraint(
                'id', 'other_id',
                name='uq_somemodel_id_otherid',
                sqlite_on_conflict='IGNORE'
            )
        )
        id = db.Column(db.Integer, primary_key=True)
        other_id = db.Column(db.Integer, primary_key=True)
        content = db.Column(db.String(255))
    
  • 方式二:动态语句实现
    不需要修改表定义,适合局部插入操作需要忽略冲突的场景,灵活性更高,示例代码:
    from sqlalchemy import insert
    from models import SomeModel
    # 从外部API获取的待写入数据
    api_data = [
        {"id": 1, "other_id": 2, "content": "接口返回的内容1"},
        {"id": 3, "other_id": 4, "content": "接口返回的内容2"}
    ]
    # 构造带冲突忽略逻辑的插入语句
    stmt = insert(SomeModel).values(api_data).on_conflict_do_nothing(
        # 指定冲突判定的索引列,和表上定义的唯一约束保持一致
        index_elements=['id', 'other_id']
    )
    db.session.execute(stmt)
    db.session.commit()
    
    开启SQLALCHEMY_ECHO=True后,可以在日志中看到正确生成的SQLite原生UPSERT语句,不存在配置不生效的问题。

场景2:冲突时更新字段(完整UPSERT逻辑)

当遇到唯一键冲突时,不忽略插入,而是用新获取的接口数据覆盖已有记录的对应字段,直接用on_conflict_do_update方法实现,示例:

stmt = insert(SomeModel).values(api_data).on_conflict_do_update(
    index_elements=['id', 'other_id'],
    # 冲突时指定需要更新的字段,excluded对象引用待插入的新值
    set_={
        'content': stmt.excluded.content
    }
)
db.session.execute(stmt)
db.session.commit()
注意事项
  • on_conflict_do_nothing和on_conflict_do_update是SQLAlchemy针对SQLite方言提供的专属方法,仅当数据库为SQLite时生效,如果后续需要切换到其他数据库,需要调整对应方言的冲突处理逻辑,或升级到SQLAlchemy 2.0使用跨数据库通用的UPSERT语法
  • 如果使用动态语句的方式实现UPSERT,不需要在表定义中额外配置sqlite_on_conflict参数,动态语句会自动编译对应的原生SQL
  • 1.3版本的SQLAlchemy不支持完整的UPSERT语法,仅能兼容低版本SQLite的INSERT OR IGNORE逻辑,要实现冲突更新的能力建议升级到1.4及以上版本

内容的提问来源于stack exchange,提问作者gribvirus74

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.16 16:54:02