使用SQLAlchemy向MariaDB插入数据触发charmap编码错误的原因是什么

• 连接字符串未显式指定兼容Unicode的字符集：默认情况下SQLAlchemy连接MariaDB时如果没有指定charset参数，驱动会默认使用Latin-1等ASCII兼容的窄字符集传输数据，当插入\u2013（长破折号）这类超出Latin-1编码范围的Unicode字符时，就会触发编码失败报错。
• 目标表/字段的字符集配置不兼容：如果插入的表或对应存储文本的字段使用的是Latin-1、GBK等不支持全量Unicode字符的编码，即使连接层字符集配置正确，写入数据库时也会触发编码转换错误。
• 数据库驱动未开启Unicode传输配置：部分旧版本的MariaDB连接驱动（如pymysql、mysqlclient）默认关闭Unicode字符串自动转码，需要显式配置开启才能正确处理Python原生Unicode字符串。

1. 首先修改连接字符串，追加charset=utf8mb4参数，示例如下：

con_string = f"{db_driver}://{db_user}:{db_password}@{db_host}:{db_port}/{db_name}?charset=utf8mb4"
engine = sqlalchemy.create_engine(con_string, pool_pre_ping=True)

2. 确认目标数据表及对应文本字段的字符集已设置为utf8mb4，可通过以下SQL语句查询修改：

-- 查询表字符集
SHOW CREATE TABLE `你的表名`;
-- 修改表及字段字符集
ALTER TABLE `你的表名` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

3. 如果使用pymysql驱动，可在create_engine时追加驱动参数强制开启Unicode处理：

engine = create_engine(con_string, pool_pre_ping=True, connect_args={"use_unicode": True, "charset": "utf8mb4"})

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