如何通过 Polars 将 DataFrame 导入 SQLite 数据库中？

本文共计905个文字，预计阅读时间需要4分钟。

通过Polars的`write_database`方法将数据高效写入SQLite数据库，需要遵循以下步骤：

Polars 自 0.20.0 版本起原生支持数据库写入（需额外依赖），但其 write_database 方法不直接接受原生 sqlite3.Connection 对象，而是依赖 SQLAlchemy 的统一数据库接口。因此，正确写入 SQLite 的关键在于：使用符合 SQLAlchemy 规范的连接 URI 字符串，并确保相关依赖已安装。

✅ 正确步骤与示例代码

首先，安装必要依赖（注意：polars[sqlalchemy] 是必需的，它会自动安装 sqlalchemy 及兼容的 SQLite 驱动）：

pip install polars[sqlalchemy]

然后，使用标准 URI 格式写入数据：

import polars as pl df = pl.DataFrame({ "id": [101, 102, 103], "name": ["Alice", "Bob", "Charlie"], "score": [88.5, 92.0, 76.3] }) # ✅ 正确：使用 SQLAlchemy 兼容的 SQLite URI df.write_database( table_name="students", connection="sqlite:///./data/students.db", # 相对路径（当前目录下 data/ 子目录） if_table_exists="replace" # 可选值："fail", "replace", "append" )

? 连接 URI 格式说明（易错点重点）

SQLite 的 URI 必须严格遵循 SQLAlchemy 的格式，核心规则如下：

URI 示例	含义	注意事项
sqlite:///memory.db	创建内存数据库（进程内临时库）	文件名可任意，但实际不落盘
sqlite:///test.db	当前目录下的 test.db	3 个斜杠：sqlite:/// + 路径
sqlite:////absolute/path/test.db	绝对路径（Linux/macOS）	4 个斜杠：sqlite://// + /path/...
sqlite:///C:/projects/data.db	Windows 绝对路径（推荐用正斜杠）	避免反斜杠转义问题；也可用 sqlite:///C%3A/projects/data.db 编码

❌ 错误写法（导致 unable to open database file）：

# 错误1：漏掉协议前缀或斜杠数量不对 df.write_database("t", "test.db") # ❌ 缺少 sqlite:/// df.write_database("t", "sqlite://test.db") # ❌ 应为 sqlite:/// df.write_database("t", "sqlite:///test.db/") # ❌ 末尾斜杠可能被误解析为路径分隔符 # 错误2：传入原生 sqlite3.Connection（不支持） conn = sqlite3.connect("test.db") df.write_database("t", conn) # ❌ 报错：expected str or URL, got Connection

? 补充说明：读取 SQLite 表（可选）

写入后如需读取，推荐使用 pl.read_database_uri（轻量、高性能），需额外安装 connectorx（非强制，但比 SQLAlchemy 读取更快）：

pip install connectorx

# 读取刚写入的表 result = pl.read_database_uri( query="SELECT * FROM students WHERE score > 80", uri="sqlite:///./data/students.db" ) print(result)

✅ 总结与最佳实践

• ✅ 始终使用 sqlite:///... 形式的 URI，注意斜杠数量；
• ✅ 安装时明确指定 polars[sqlalchemy]；
• ✅ 路径优先使用相对路径或标准化绝对路径，避免空格与中文字符；
• ✅ 生产环境建议预先创建数据库目录（如 os.makedirs("./data", exist_ok=True)），防止因目录不存在导致写入失败；
• ✅ if_table_exists="replace" 会先 DROP 再 CREATE，适合开发调试；生产中建议设为 "fail" 并手动建表以保障 schema 安全。

掌握这些要点后，你即可在 Polars 中稳定、高效地完成 SQLite 数据的批量写入任务。