【Pandas】pandas DataFrame to_sql

Pandas2.2 DataFrame

Serialization IO conversion

pandas DataFrame to_sql()

pandas.DataFrame.to_sql() 是 Pandas 提供的用于将 DataFrame 写入 SQL 数据库的方法。它支持多种数据库后端（如 SQLite、PostgreSQL、MySQL 等），通过 SQLAlchemy 引擎实现跨数据库兼容性。

方法签名

DataFrame.to_sql(
    name,
    con,
    *,
    schema=None,
    if_exists='fail',
    index=True,
    index_label=None,
    chunksize=None,
    dtype=None,
    method=None
)

参数说明

返回值

• 返回写入数据库的行数（int）

示例代码

示例 1：基础用法（写入 SQLite 数据库）

import pandas as pd
from sqlalchemy import create_engine

# 创建示例 DataFrame
df = pd.DataFrame({
    'id': [1, 2, 3],
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [25, 30, 35]
})

# 创建 SQLite 数据库连接
engine = create_engine('sqlite:///example.db')

# 写入数据库
df.to_sql('people', con=engine, if_exists='replace', index=False)

结果：

• 在当前目录下生成一个名为 example.db 的 SQLite 数据库文件。
• 其中包含一张名为 people 的表，内容为上述 DataFrame 的数据。

示例 2：写入 PostgreSQL 数据库

# PostgreSQL 连接字符串格式
conn_str = "postgresql://username:password@localhost:5432/mydatabase"

# 创建连接引擎
engine = create_engine(conn_str)

# 写入 PostgreSQL 表（替换已有表）
df.to_sql('people', con=engine, if_exists='replace', index=False, schema='public')

说明：

• 需要先安装 PostgreSQL 支持：

pip install psycopg2-binary

示例 3：自定义列类型（dtype）

from sqlalchemy import VARCHAR, Integer

# 自定义列类型
dtype_mapping = {
    'id': Integer,
    'name': VARCHAR(255),
    'age': Integer
}

# 写入 SQLite 并指定列类型
df.to_sql('people', con=engine, if_exists='replace', dtype=dtype_mapping)

用途：

• 控制数据库字段长度、精度等细节。

示例 4：分块写入（chunksize）

# 分块写入，每批 1000 行
df_large = pd.concat([df] * 10000)  # 模拟大数据集
df_large.to_sql('people', con=engine, if_exists='replace', chunksize=1000)

优点：

• 减少内存占用，适用于百万级以上数据导入。

示例 5：追加写入已有表（if_exists='append'）

# 新增一行数据并追加写入
new_row = pd.DataFrame({'id': [4], 'name': ['David'], 'age': [28]})
new_row.to_sql('people', con=engine, if_exists='append', index=False)

注意：

• 表结构必须一致，否则会报错。

注意事项

• 使用前需安装对应数据库驱动（如 psycopg2 for PostgreSQL, mysqlclient for MySQL）。
• 若目标表不存在，to_sql() 会自动创建；若存在则根据 if_exists 处理。
• 建议使用 chunksize 处理大规模数据，防止内存溢出。
• dtype 参数可用于优化数据库字段类型，提升性能和存储效率。
• 使用 method='multi' 可以显著加快插入速度（尤其在 SQLite 上）。

总结

安装依赖

pip install pandas sqlalchemy

对于不同数据库还需安装额外驱动：

• SQLite（默认支持）
• PostgreSQL：

pip install psycopg2-binary

• MySQL：

pip install mysqlclient