CQL 教程/中文适配子包/CQSqlite 数据库

CQSqlite 数据库

用全中文 API 操作 SQLite 数据库：连接、建表、增删改查与事务，底层基于 Python 内置 sqlite3。

23.1简介

CQSqlite 是基于 Python 内置 sqlite3 的中文适配，无需安装任何额外依赖，安装核心 CQL 后即可使用：

cql

从 CQSqlite 导入 连接

数据库 = 连接("app.db")            # 打开文件数据库
内存数据库 = 连接(":memory:")       # 内存数据库
内存数据库.关闭()

SQLite 是单文件数据库，无需启动服务器进程。
参考示例：examples/db_hello.cql（cql run examples/db_hello.cql）。
核心 API：连接、执行、查询、查询字典、提交、回滚。

23.2连接与建表

用 连接(路径) 打开数据库，连接(":memory:") 创建内存数据库（程序退出后数据消失，适合测试）：

cql

从 CQSqlite 导入 连接

数据库 = 连接(":memory:")
数据库.执行("CREATE TABLE 用户(编号 INTEGER PRIMARY KEY AUTOINCREMENT, 姓名 TEXT, 年龄 INTEGER)")

执行 方法执行一条 SQL 语句并返回数据库对象自身，因此可以链式调用：

cql

数据库.执行("CREATE TABLE 用户(编号 INTEGER PRIMARY KEY, 姓名 TEXT)").执行("CREATE TABLE 订单(编号 INTEGER PRIMARY KEY)")

23.3增删改

插入、更新、删除都使用 执行，参数用 ? 占位符传参（防注入），改完必须 提交() 才生效：

cql

# 插入
数据库.执行("INSERT INTO 用户(姓名, 年龄) VALUES(?, ?)", ("小明", 18))
数据库.执行("INSERT INTO 用户(姓名, 年龄) VALUES(?, ?)", ("小红", 20))
数据库.提交()
打印("最后插入编号：", 数据库.最后插入ID)

# 更新
数据库.执行("UPDATE 用户 SET 年龄 = ? WHERE 姓名 = ?", (19, "小明"))
数据库.提交()

# 删除
数据库.执行("DELETE FROM 用户 WHERE 姓名 = ?", ("小红",))
数据库.提交()

批量插入用 执行多条(语句, 参数序列)，执行多语句脚本用 执行脚本(脚本)。

23.4查询

查询返回的行对象同时支持按列名（行["姓名"]）与按下标（行[0]）两种取值方式：

cql

行们 = 数据库.查询("SELECT * FROM 用户 ORDER BY 编号")
循环 行 在 行们:
    打印("  {} 岁：{}".format(行["年龄"], 行["姓名"]))

# 返回字典列表，可直接打印
打印(数据库.查询字典("SELECT * FROM 用户"))

# 返回单行，无结果时返回 空
一行 = 数据库.查询一条("SELECT 姓名 FROM 用户 WHERE 姓名 = ?", ("小明",))
如果 一行 != 空:
    打印(一行[0])

# 元信息
打印("表列表：", 数据库.表列表())
打印("用户表的列：", 数据库.列名("用户"))

三种查询方法：

查询(语句, 参数=None)：返回全部行。
查询字典(语句, 参数=None)：返回字典列表（如 [{'编号': 1, '姓名': '小明', '年龄': 18}]）。
查询一条(语句, 参数=None)：返回第一行，无结果时返回 空。

23.5事务与上下文管理器

连接对象支持 with 上下文管理器：正常结束自动提交，出现异常自动回滚，无需手动调用 提交() / 回滚()：

cql

伴随 连接("app.db") 作为 数据库:
    数据库.执行("INSERT INTO 用户(姓名, 年龄) VALUES(?, ?)", ("小刚", 22))
    数据库.执行("UPDATE 用户 SET 年龄 = ? WHERE 姓名 = ?", (23, "小刚"))
    # 块正常结束自动提交，抛异常则自动回滚

手动事务则使用 提交() 与 回滚()：

cql

尝试:
    数据库.执行("INSERT INTO 用户(姓名) VALUES(?)", ("小刚",))
    数据库.提交()
捕获 异常 作为 e:
    数据库.回滚()
    打印("操作失败：", e)

23.6API 一览

中文 API	说明
`连接(路径=":memory:", 超时=5.0)`	打开数据库，默认内存数据库
`打开(路径)` / `内存数据库()`	便捷构造
`执行(语句, 参数=None)`	执行增删改，返回自身（链式）
`执行多条(语句, 参数序列)`	批量执行
`执行脚本(脚本)`	执行多语句脚本
`查询(语句, 参数=None)`	返回全部行（行支持行["列名"] 与行[0]）
`查询一条(语句, 参数=None)`	返回第一行，无结果返回空
`查询字典(语句, 参数=None)`	返回字典列表
`提交()` / `回滚()` / `关闭()`	事务与关闭
`最后插入ID` / `行数` / `总变更数`	属性
`表列表()` / `列名(表)`	元信息
上下文管理器	`伴随连接(...) 作为数据库:` 正常结束自动提交，异常自动回滚
异常	`错误`、`数据库错误`、`完整性错误`、`操作错误`、`编程错误` 等

23.7注意事项

SQL 用英文：SQL 语句本身使用英文关键字（CQL 转译器不会改写字符串字面量）。
记得提交：插入 / 更新 / 删除后需 提交() 才生效，或在 with 块中自动提交。

注意：未调用 提交() 就关闭连接，未提交的改动会丢失。