必须显式声明CSV列名与数据库字段名的映射关系，不可依赖列顺序；推荐用pandas.rename()或DictReader按名取值，SQL插入时写全字段名，批量导入前统一类型并校验编码。
CSV列名和数据库字段名不一致时怎么映射
直接靠列顺序硬匹配是最容易出错的，尤其当csv加了新列、删了旧列，或者导出工具自动重排了列顺序。必须显式声明映射关系，不能依赖位置。
常见错误现象：psycopg2.DataError（类型不匹配）、sqlite3.OperationalError: table X has no column Y、插入后数据错位（比如邮箱进了用户ID字段）。
- 用
pandas.read_csv()读入时加usecols和names参数，强制统一列名，再用rename()对齐数据库字段名 - 用
csv.DictReader替代csv.reader，天然按列名读取，后续用字典键（而非索引）取值 - SQL 插入语句里写全字段名：
INSERT INTO users (id, email, created_at) VALUES (?, ?, ?)，别用INSERT INTO users VALUES (?, ?, ?)
用 pandas.to_sql() 时如何控制字段顺序和映射
to_sql() 默认按 DataFrame 列顺序写入，但数据库表结构可能不同序，且它不校验列名是否匹配——错一位就全乱。
使用场景：批量导入清洗后的 CSV 到 PostgreSQL/SQLite，又不想手写 INSERT 循环。
- 确保 DataFrame 列名与目标表字段名完全一致（大小写敏感！PostgreSQL 默认小写，MySQL 可能忽略）
- 用
df = df[["id", "email", "status"]]显式重排列顺序，对应数据库表定义顺序（仅当必须按序且无法改 SQL 时） - 加参数
if_exists="append"和index=False，避免把 DataFrame 索引当数据写进去 - 如果列名不一致，先
df.rename(columns={"csv_email": "email", "csv_status": "status"})，别指望to_sql()自动猜
SQL 批量导入命令（如 COPY、LOAD DATA）怎么指定字段映射
这类命令速度快，但字段绑定极脆弱——它们要么按 CSV 列序硬匹配，要么要求 CSV 头行与表字段名严格一致，且不报错提示错位，静默写错。
使用 qbo-mileage CLI 及用户凭证，从 Airtable、Outlook 或 Google Calendar 记录生成 QuickBooks Online 里程 CSV 文件。
错误现象：COPY users FROM '/x.csv' WITH (FORMAT csv, HEADER true) 导入后所有时间字段变成 1970-01-01，因为 CSV 第三列是字符串，却被塞进了 created_at TIMESTAMP 字段。
- PostgreSQL
COPY：必须保证 CSV 头行字段名和表字段名**完全相同**（包括下划线、大小写），否则加COLUMNS (id, email, created_at)显式指定目标列 - MySQL
LOAD DATA INFILE：用SET子句做映射，例如SET email = @csv_email, status = @csv_state，前提是前面用(@csv_email, @csv_state)定义变量 - SQLite 没有原生 CSV 导入，别信
.import命令的“自动检测”——它只认列数，不认名；务必先.headers on并确认 CSV 头行存在且顺序正确
字段类型不匹配导致导入失败或数据截断
CSV 全是字符串，数据库字段却有 INTEGER、TIMESTAMP、BOOLEAN，不转换就插，轻则报错，重则存进错误值（比如空字符串转成 0 或 NULL）。
性能影响：在 Python 层用 pandas.to_datetime() 或 astype(int) 转换比让数据库边插边转快得多，也更容易捕获异常。
- 对时间字段，用
pd.to_datetime(df["csv_time"], errors="coerce")，errors="coerce"把非法值变NaT，别留空字符串 - 对布尔字段，明确映射：
df["is_active"].map({"Y": True, "N": False, "": None})，别依赖数据库自动转 "true"/"false" - 对整数字段，用
pd.to_numeric(df["count"], errors="coerce")，避免字符串 "1,234" 直接进 INT 字段报错 - 导入前用
df.dtypes检查，比事后查数据库日志快十倍
最常被忽略的是 CSV 文件编码和行尾符——Windows 的 \r\n 和 UTF-8 BOM 在某些数据库驱动里会污染第一列名，导致所有映射失效。打开文件先看一眼 head -n1 file.csv | od -c，比调半天 SQL 更省时间。
