本文详解 polars 中 write_database() 方法向 sqlite 写入数据的正确用法，涵盖连接 uri 格式规范、依赖安装要求、路径书写细节及常见错误规避方法。
本文详解 polars 中 write_database() 方法向 sqlite 写入数据的正确用法，涵盖连接 uri 格式规范、依赖安装要求、路径书写细节及常见错误规避方法。
Polars 自 0.20.0 版本起支持通过 write_database() 直接将 DataFrame 写入关系型数据库（包括 SQLite），但该功能并非开箱即用——它依赖外部 SQL 驱动库，对 SQLite 而言，必须安装支持 SQLAlchemy 的扩展。
✅ 前置依赖：安装 polars[sqlalchemy]
默认安装的 Polars 不包含数据库驱动。需显式安装带 SQLAlchemy 支持的版本：
pip install polars[sqlalchemy]
⚠️ 注意：polars[sqlalchemy] 会自动安装 sqlalchemy 和 pysqlite3（或系统 sqlite3）。若环境受限，也可单独执行 pip install sqlalchemy pysqlite3，但推荐使用 polars[sqlalchemy] 确保兼容性。
✅ 正确构造 SQLite 连接 URI
Polars 要求传入标准 SQLAlchemy 兼容的数据库 URI 字符串（非原生 sqlite3.Connection 对象）。SQLite URI 格式严格遵循以下规则：
| 场景 | URI 示例 | 说明 |
|---|---|---|
| 内存数据库 | "sqlite:///:memory:" | 仅用于测试，进程退出即销毁 |
| 当前目录下的文件 | "sqlite:///database.db" | 三个斜杠，表示相对路径（./database.db） |
| 绝对路径（Linux/macOS） | "sqlite:////home/user/data.db" | 四个斜杠，第四个起始绝对路径 |
| 绝对路径（Windows） | "sqlite:///C:/project/data.db" | Windows 使用正斜杠或双反斜杠，仍为三个斜杠前缀 |
❌ 错误示例（导致 unable to open database file）：
# ❌ 错误：缺少协议前缀或斜杠数量不对
df.write_database("t", "test.db") # 缺少 sqlite:///
df.write_database("t", "sqlite://test.db") # 应为 sqlite:///（三斜杠）
df.write_database("t", "sqlite:////test.db") # 若 test.db 在当前目录，四斜杠将解析为 /test.db（根目录），文件不存在✅ 正确写入示例：
import polars as pl
df = pl.DataFrame({
"id": [101, 102, 103],
"name": ["Alice", "Bob", "Charlie"],
"score": [88.5, 92.0, 79.5]
})
# ✅ 写入当前目录下的 database.db（推荐新手使用）
df.write_database(
table_name="students",
connection="sqlite:///database.db",
if_table_exists="replace" # 可选: "fail", "append", "replace"
)执行后，Polars 会自动创建 database.db 文件，并建表 students，字段类型按 Polars 数据类型智能映射（如 Int64 → INTEGER, Float64 → REAL, String → TEXT）。
? 验证与读取（可选）
写入成功后，可用 pl.read_database_uri() 读回验证（需额外安装 connectorx）：
pip install connectorx # 或使用 polars[connectorx]
result = pl.read_database_uri(
query="SELECT * FROM students WHERE score > 80",
uri="sqlite:///database.db"
)
print(result)⚠️ 关键注意事项
- 路径权限：确保 Python 进程对目标目录有写权限；若指定绝对路径，请确认路径存在且可写。
- 并发安全：SQLite 默认不支持多线程/多进程同时写入；生产中高并发场景请改用 PostgreSQL 或加锁控制。
- 类型映射限制：Polars 暂不支持写入 List, Struct, Binary 等复杂类型到 SQLite（会报错），请预先 .cast() 为基本类型。
- 事务控制：write_database() 默认启用事务；若中途失败，表将回滚，不会残留半成品数据。
✅ 总结
使用 Polars 写入 SQLite 的核心三步：
1️⃣ 安装 polars[sqlalchemy]；
2️⃣ 构造符合规范的 sqlite:///path.db URI（牢记三斜杠起始 + 相对/绝对路径逻辑）；
3️⃣ 调用 df.write_database(table_name, connection, if_table_exists=...)。
掌握 URI 规则，即可零错误完成高效数据持久化。
