本文详解如何通过 polars 的 write_database 方法将数据高效写入 sqlite 数据库，涵盖连接 uri 格式规范、依赖安装要求、路径写法要点及常见错误规避策略。
本文详解如何通过 polars 的 write_database 方法将数据高效写入 sqlite 数据库，涵盖连接 uri 格式规范、依赖安装要求、路径写法要点及常见错误规避策略。
Polars 自 0.20.0 版本起原生支持数据库写入（需额外依赖），但其 write_database 方法不直接接受原生 sqlite3.Connection 对象，而是依赖 SQLAlchemy 的统一数据库接口。因此，正确写入 SQLite 的关键在于：使用符合 SQLAlchemy 规范的连接 URI 字符串，并确保相关依赖已安装。
✅ 正确步骤与示例代码
首先，安装必要依赖（注意：polars[sqlalchemy] 是必需的，它会自动安装 sqlalchemy 及兼容的 SQLite 驱动）：
pip install polars[sqlalchemy]
⚠️ 若仅安装 polars 而未启用 [sqlalchemy] extras，调用 write_database 时将抛出 AttributeError: module 'polars' has no attribute 'write_database' 或导入失败。
然后，使用标准 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)? 提示：read_database_uri 不依赖 SQLAlchemy，因此无需 [sqlalchemy]；但 write_database 必须依赖 SQLAlchemy，二者功能互补。
✅ 总结与最佳实践
- ✅ 始终使用 sqlite:///... 形式的 URI，注意斜杠数量；
- ✅ 安装时明确指定 polars[sqlalchemy]；
- ✅ 路径优先使用相对路径或标准化绝对路径，避免空格与中文字符；
- ✅ 生产环境建议预先创建数据库目录（如 os.makedirs("./data", exist_ok=True)），防止因目录不存在导致写入失败；
- ✅ if_table_exists="replace" 会先 DROP 再 CREATE，适合开发调试；生产中建议设为 "fail" 并手动建表以保障 schema 安全。
掌握这些要点后，你即可在 Polars 中稳定、高效地完成 SQLite 数据的批量写入任务。
