用to_sql写入MySQL前必须设对if_exists和index：if_exists='fail'表存在时报错，index=True会多写一列索引；新表用'replace'（但会删表重建），追加用'append'并确保结构一致，始终显式设index=False。
用 to_sql 写入前必须设对 if_exists 和 index
写不进表、数据重复、多出一列 index，八成是这两个参数没配对。默认 if_exists='fail'，表存在直接报错 ValueError: Table 'xxx' already exists.；而 index=True（默认）会把 DataFrame 行索引当一列写进去，常导致字段错位或主键冲突。
实操建议：
- 新表写入用
if_exists='replace'，但注意它会先DROP TABLE再重建——有外键或权限限制时失败 - 追加数据用
if_exists='append'，确保目标表结构与 DataFrame 列名、类型严格一致，否则报ProgrammingError: column "xxx" of relation "yyy" does not exist - 除非真要存索引，否则显式写
index=False，避免生成无意义的index列
批量写入慢？换 method='multi' 或原生 execute_batch
to_sql 默认逐行 INSERT，1 万行可能耗时几十秒。开 method='multi' 能拼成一条含多值的 INSERT，提速 3–5 倍，但 PostgreSQL 对单条语句长度有限制（默认 max_query_size=1GB，实际受 work_mem 影响），超长会报 OperationalError: server closed the connection unexpectedly。
更稳的方案是绕过 to_sql，用 psycopg2.extras.execute_batch：
立即学习“Python免费学习笔记（深入）”；
from psycopg2.extras import execute_batch
with engine.connect() as conn:
execute_batch(conn, "INSERT INTO tbl (a,b) VALUES (%s,%s)", df.values.tolist(), page_size=1000)
关键点：
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
-
page_size控制每批执行行数，1000 是较安全的起点；调太高易触发内存或超时 - 必须确保
df.values.tolist()中每个子列表顺序和 SQL 占位符完全对应 - 不能自动建表，目标表得提前存在且字段类型兼容
中文乱码、JSON 字段写不进？检查 engine 的 encoding 和 dtype
PostgreSQL 连接默认编码通常是 utf8，但若数据库集群初始化用的是 SQL_ASCII 或连接字符串漏了 client_encoding=utf8，DataFrame 里的中文会变 ????；而 JSON 列写入失败，常因 Pandas 把字典转成 str 后直接当文本插，PostgreSQL 拒绝解析。
解决方法：
- 创建 engine 时强制指定编码：
create_engine("postgresql://u:p@h/d", connect_args={"client_encoding": "utf8"}) - 对 JSON 字段，提前用
df['json_col'] = df['json_col'].apply(json.dumps)转成字符串，再配合dtype={'json_col': sqlalchemy.types.JSON}传给to_sql（需 SQLAlchemy ≥ 1.4） - 时间字段若含时区，用
df['ts'].dt.tz_convert('UTC').dt.tz_localize(None)剥离时区再写，否则可能报can't adapt type 'datetimeoffset'
大宽表（>50 列）写入失败？关掉 fast_executemany 并分块
有人在连接字符串里加 fast_executemany=true（这是 pyodbc 的参数，对 psycopg2 无效），结果报错 KeyError: 'fast_executemany'；还有人一次性传 200 列的 DataFrame，to_sql 构造 SQL 时字段列表过长，触发 PostgreSQL 的 too many range table entries 错误。
正确做法：
- 确认驱动：psycopg2 不支持
fast_executemany，别白配 - 用
chunksize分批，例如to_sql(..., chunksize=500)，既控内存又避单次 SQL 过长 - 列太多时，考虑先
df = df[relevant_columns]筛出真正要写的列，别一股脑全塞进去
最麻烦的不是语法，是字段类型隐式转换——比如整数列含 NaN，Pandas 会升格为 float64，写入 INT 列就崩。动手前先 df.dtypes 和目标表 \d tbl 对一遍，比啥都管用。
