如何在Peewee批量Upsert时向ArrayField追加元素及解决类型转换问题

问题背景 #

模型定义：

class User(Model):
    id = BigAutoField(primary_key=True, unique=True)
    tags = ArrayField(CharField, null=True)

目标SQL逻辑：

update user as u set tags = array_append(u.tags, val.tag) 
from (values (2, 'test'::varchar)) as val(id, tag) 
where u.id = val.id;

单条Upsert尝试代码及报错：

User.insert(user).on_conflict(
   conflict_target=[User.id],
   update={User.tags: fn.array_append(user['tag'])}
).execute()

错误信息：

function array_append(unknown) does not exist
HINT:  No function matches the given name and argument types. You might need to add explicit type casts.

原因分析 #

1. array_append需传入两个参数：原数组字段和要追加的元素，你漏传了第一个参数（当前用户的tags字段）。
2. 字符串参数未显式转换为PostgreSQL的varchar类型，导致类型不匹配。

解决方案 #

1. 单条Upsert的正确实现 #

使用Peewee的Cast函数转换字符串类型，同时传入原tags字段作为array_append的第一个参数：

from peewee import Cast, fn

# 示例数据
user = {'id': 2, 'tag': 'test'}

User.insert(
    id=user['id'],
    tags=[user['tag']]  # 插入时初始化数组
).on_conflict(
    conflict_target=[User.id],
    update={
        User.tags: fn.array_append(
            User.tags, 
            Cast(user['tag'], 'varchar')  # 显式转换为varchar
        )
    }
).execute()

若原tags为NULL，array_append会自动将其转为数组（如NULL追加'test'后变为['test']）。

2. 批量Upsert的实现 #

方法一：基于values子句构建批量更新

from peewee import ValuesList, fn, Cast

# 批量数据：每个元素为(id, tag)
batch_data = [(2, 'test'), (3, 'dev'), (4, 'prod')]

# 构建values子句
values_clause = ValuesList(batch_data, columns=[User.id, 'tag'])

# 执行批量Upsert
User.insert_from(
    values_clause,
    fields=[User.id]
).on_conflict(
    conflict_target=[User.id],
    update={
        User.tags: fn.array_append(
            User.tags,
            Cast(values_clause.c.tag, 'varchar')
        )
    }
).execute()

方法二：使用insert_many结合EXCLUDED关键字

from peewee import fn, EXCLUDED

# 批量数据：将tag包装为单元素数组
batch_data = [
    {'id': 2, 'tags': ['test']},
    {'id': 3, 'tags': ['dev']},
    {'id': 4, 'tags': ['prod']}
]

User.insert_many(batch_data).on_conflict(
    conflict_target=[User.id],
    update={
        User.tags: fn.array_append(
            User.tags,
            EXCLUDED.tags[0]  # 直接取插入行的tag值
        )
    }
).execute()

3. 类型转换的几种方式 #

Peewee中实现PostgreSQL类型转换的常用方式：

• 使用Cast(expr, type)：Cast('test', 'varchar')
• 使用字段的cast()方法：CharField().cast('test')
• 调用PostgreSQL原生函数：fn.cast('test', 'varchar')

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