高效导入 MariaDB 大数据集到 Python：低内存占用的流式处理方案_技术教程

本文介绍如何使用 `python-mariadb` 连接器配合流式游标（unbuffered cursor）与分块读取，避免一次性加载全量数据导致的内存暴涨，实现 5 亿行级数据的稳定、低开销导入。

在处理大规模 MariaDB 数据时，传统 cursor.fetchall() + pd.DataFrame() 的方式极易引发内存峰值（如原文中从 35GB 跃升至 90GB），根源在于：

缓冲游标默认缓存全部结果集于
客户端内存；
Python 整数对象（PyLong）存在显著内存开销，远超原始 C 类型（如 INT 占 4 字节，但 Python 中常达 28+ 字节）；
fetchall() 返回的 list[tuple] 是完整副本，叠加 DataFrame 构造过程中的多次拷贝，形成“内存雪球”。

✅ 推荐方案：无缓冲游标 + 二进制协议 + 分块流式加载

核心优化点有三：

禁用游标缓冲：buffered=False 避免客户端预存全部结果；
启用二进制协议：binary=True 让 MariaDB 直接发送原始字节（如 BIGINT → 8 字节），而非字符串序列化（如 "17592186044416" → 14+ 字节 + 字符串对象开销）；
按需分块获取：用 fetchmany(size) 流式拉取，边读边构表，杜绝全量驻留。

import pandas as pd
import mariadb

# 建立连接（关键：禁用缓冲 & 启用二进制协议）
conn = mariadb.connect(
    user='your_user',
    host='localhost',
    database='my_database',
    # 可选：设置 socket 超时或 read_timeout 防止长查询阻塞
)

cursor = conn.cursor(buffered=False, binary=True)  # ← 核心配置
query = "SELECT column_1, column_2 FROM my_table"
cursor.execute(query)

# 初始化空 DataFrame（指定 dtype 提前规避类型推断开销）
# 假设两列均为 INT，可显式声明以节省内存并防止 float 自动转换
df = pd.DataFrame(columns=['column_1', 'column_2'], dtype='int32')

chunk_size = 2**18  # 推荐 256K ~ 1M 行/批；过大仍可能触发瞬时峰值
while True:
    rows = cursor.fetchmany(chunk_size)
    if not rows:
        break
    # 每批转为 DataFrame 并追加（copy=False 减少拷贝）
    chunk_df = pd.DataFrame(rows, columns=['column_1', 'column_2'])
    df = pd.concat([df, chunk_df], ignore_index=True, copy=False)

cursor.close()
conn.close()

⚠️ 注意事项： dtype 一致性：若列含 NULL，int32 不支持，需改用 Int32Dtype()（pandas nullable integer）或 float32；否则 pd.DataFrame(rows) 可能自动升为 float64（如问题中所述）。解决方案： chunk_df = pd.DataFrame(rows, columns=['c1','c2']).astype({'c1': 'Int32', 'c2': 'Int32'})性能权衡：chunk_size 过小（如 1K）会增加网络往返和 Python 循环开销；过大（如 10M）可能使单次 fetchmany 内存激增。建议从 2**18（256K）起步，根据实际内存监控调整。替代更优解（推荐进阶）：若允许引入 SQLAlchemy，pd.read_sql(..., chunksize=N) 结合 mariadb:// URL（需安装 sqlalchemy 和 pymysql 或 mysqlclient 作为驱动）可自动处理类型映射与内存复用，且 pd.concat(chunks, copy=False) 更高效——但需接受 UserWarning（实际兼容性良好，MariaDB 11.2+ 已广泛验证）。

? 总结：内存优化的关键路径

阶段	高开销操作	优化手段	效果
连接初始化	默认缓冲游标	buffered=False	消除服务端结果集客户端缓存
数据传输	文本协议序列化	binary=True	减少 50%+ 网络载荷与解析开销
内存驻留	fetchall() 全量加载	fetchmany(N) 流式分块	将峰值内存从 O(N) 降至 O(1)（恒定批大小）
DataFrame 构建	动态 dtype 推断	显式 dtype= + nullable 类型	避免 float 误转、减少每元素内存占用