为什么SQLAlchemy中UnicodeText转TEXT且搭配MariaDB报Operational错误

问题根源 #

SQLAlchemy的UnicodeText类型在MySQL方言下会自动映射为TEXT类型，未配置全局字符串默认长度时部分场景也会推导为VARCHAR，你遇到的两个报错均来自MySQL自身的规则限制：

报错1：BLOB/TEXT列'username'在未指定键长度的情况下被用于键定义 #

原因 #

MySQL不允许对完整的TEXT/BLOB字段创建索引（含唯一索引），这类可变长字段的索引必须指定前缀长度，仅对字段前N个字符建索引。你给username、email字段设置了unique=True约束，SQLAlchemy建表时会自动生成唯一索引，直接触发了该限制。

解决方案 #

根据你的业务需求二选一即可：

• 若无需存储超长用户名、邮箱，直接替换为带长度的Unicode类型，映射到MySQL为带长度的VARCHAR，天然支持建唯一索引：

username = Column(Unicode(32), unique=True, nullable=False)
email = Column(Unicode(128), unique=True, nullable=False)

• 若确实需要用TEXT类型存储这两个字段，单独定义唯一约束并指定索引前缀长度：

__tablename__ = "users"
__table_args__ = (
    UniqueConstraint('username', mysql_length={'username': 32}),
    UniqueConstraint('email', mysql_length={'email': 64}),
)
# 字段定义里去掉unique=True参数
user_id = Column(Integer, primary_key=True)
username = Column(UnicodeText, nullable=False)
email = Column(UnicodeText, nullable=False)

报错2：MySQL方言下VARCHAR需要指定长度 #

原因 #

你plot_config表中的data字段声明为UnicodeText，部分版本的SQLAlchemy+MySQL驱动组合会将其推导为VARCHAR类型，但MySQL要求所有VARCHAR字段必须显式指定长度，因此触发编译报错。

解决方案 #

根据存储内容长度二选一即可：

• 若data字段存储内容不超过65535字节，直接指定Unicode类型长度：

data = Column(Unicode(4096), nullable=False)

• 若存储的是超大JSON/配置类内容，超过VARCHAR上限，直接显式指定使用MySQL原生TEXT类型，避免类型推导异常：

from sqlalchemy.dialects.mysql import TEXT
# 字段定义改为
data = Column(TEXT, nullable=False)

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