本文介绍如何使用 `python-mariadb` 连接器配合流式游标（unbuffered cursor）与分块读取，避免一次性加载全量数据导致的内存暴涨，实现 5 亿行级数据的稳定、低开销导入。
在处理大规模 MariaDB 数据时，传统 cursor.fetchall() + pd.DataFrame() 的方式极易引发内存峰值（如原文中从 35GB 跃升至 90GB），根源在于：
- 缓冲游标默认缓存全部结果集于客户端内存；
- Python 整数对象（PyLong）存在显著内存开销，远超原始 C 类型（如 INT 占 4 字节，但 Python 中常达 28+ 字节）；
- fetchall() 返回的 list[tuple] 是完整副本，叠加 DataFrame 构造过程中的多次拷贝，形成“内存雪球”。
✅ 推荐方案：无缓冲游标 + 二进制协议 + 分块流式加载
核心优化点有三：
Mysql Skill 1.0.0 (3)
下载
MySQL 数据库管理技能，能够通过自然语言查询和管理数据库，支持 SELECT/INSERT/UPDATE/DELETE、表管理、备份恢复等操作。当用户提及 MySQL、数据库查询、建表或数据备份时使用此技能。
- 禁用游标缓冲：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 误转、减少每元素内存占用 |
该方案实测可将 5 亿行 × 2 列整数数据的峰值内存稳定控制在 ≤10 GB（原文数据），同时保持代码简洁与数据库兼容性，是生产环境中处理超大数据集的可靠实践。
