sqlor/aidocs/sor.md

SQLor 技术文档

SQLor 是一个用于简化数据库操作的异步 Python 数据库访问类，支持参数化 SQL 执行、分页查询、CRUD 操作（Create, Read, Update, Delete）、元数据获取、动态 SQL 构建等功能。它设计为可扩展，适用于多种数据库后端。

---

目录

1. 概述
2. 依赖与环境要求
3. 核心功能
4. 主要类与方法说明
   • db_type_2_py_type
   • SQLorException
   • findNamedParameters
   • uniParams
   • readsql
   • SQLor 类
     • 初始化
     • 元数据管理
     • 连接与游标控制
     • SQL 处理与转换
     • 查询执行
     • 分页与排序
     • 聚合操作（Pivot）
     • 表结构信息获取
     • DDL 与表定义操作
     • CRUD 操作（C/U/R/D）
5. 使用示例
6. 异常处理
7. 配置说明

---

概述

SQLor 提供了一个统一接口来执行 SQL 查询和命令，并通过命名参数 ${var}$ 支持模板化 SQL。其主要特点包括：

• 异步/同步双模式支持。
• 参数自动替换与安全绑定。
• 自动识别 SELECT, INSERT/UPDATE/DELETE, DDL 类型并返回相应结果。
• 支持分页、排序、条件过滤。
• 内置对表结构（字段、主键、外键、索引）的元数据查询。
• 支持自定义函数注册钩子（before/after 钩子）。
• 可扩展的类型转换机制。
• 简化的 CRUD 接口（I/C/R/U/D）。

---

依赖与环境要求

第三方依赖

from appPublic.myImport import myImport
from appPublic.dictObject import DictObject
from appPublic.unicoding import uDict
from appPublic.myTE import MyTemplateEngine
from appPublic.objectAction import ObjectAction
from appPublic.argsConvert import ArgsConvert, ConditionConvert
from appPublic.registerfunction import RegisterFunction
from appPublic.log import info, exception, debug

⚠️ 注意：这些模块属于 appPublic 包，需确保已安装或项目中包含该包。

Python 内置模块

• os
• sys
• decimal
• datetime
• codecs
• re
• json
• traceback

环境变量

os.environ['NLS_LANG'] = 'SIMPLIFIED CHINESE_CHINA.UTF8'

仅在 Oracle 数据库环境下需要设置 NLS 编码以支持中文 UTF-8。

---

核心功能

功能	描述
参数化 SQL	使用 ${var}$ 占位符进行变量注入
异步支持	支持 async/await 模式运行 SQL
分页查询	自动生成分页 SQL（需子类实现模型）
排序与过滤	支持动态排序字段和条件表达式
元数据提取	获取表、字段、主键、索引等结构信息
CRUD 封装	提供 C()(创建), R()(读取), U()(更新), D()(删除) 方法
回调机制	支持逐行处理查询结果
类型转换	自动将数据库类型转为 Python 原生类型

---

tables()

返回数据库中所有表的列表。

indexes(tablename)

返回某表的所有索引信息（需子类实现 indexesSQL()）

fields(tablename)

返回字段列表，包含名称、类型（映射后），例如：

[
  {"name": "id", "type": "int"},
  {"name": "name", "type": "string"}
]

primary(tablename)

返回主键字段列表。

fkeys(tablename)

返回外键关系。

getTableDesc(tablename)

综合获取表的完整描述（summary + fields + indexes），并缓存至 metadatas。

---

DDL 与表操作

createTable(tabledesc)

使用模板引擎渲染建表语句并执行。

依赖 self.ddl_template 和 MyTemplateEngine。

---

事务控制

commit()

提交事务，重置 dataChanged=False

rollback()

回滚事务

---

CRUD 接口（I/C/R/U/D）

遵循 RESTful 风格简写：

I(tablename)

等价于 getTableDesc() — 获取表结构定义。

C(tablename, ns)

插入新记录。

• 自动提取 ns 中存在于表字段的部分
• 触发 before / after 钩子函数
• 生成 INSERT 语句

R(tablename, ns, filters=None)

读取记录。

• 若传入 page 参数 → 返回分页 {total, rows}
• 否则返回匹配行列表
• 支持简单等值条件或复杂 DBFilter

U(tablename, ns)

更新记录。

• 使用主键做 WHERE 条件
• 更新非主键字段
• 支持钩子函数

D(tablename, ns)

删除记录。

• 使用主键匹配删除
• 支持钩子函数

---

使用示例

1. 初始化 SQLor 实例

dbdesc = {
    'dbname': 'mydb'
}
sqlor = SQLor(dbdesc=dbdesc)
sqlor.setCursor(False, conn, cursor)  # 同步模式

2. 执行参数化查询

sql = "SELECT * FROM users WHERE age > ${min_age}$"
result = []
await sqlor.execute(sql, {'min_age': 18}, lambda rec: result.append(rec))

3. 分页查询

desc = {
    "sql_string": "SELECT id, name FROM users",
    "sortfield": "name"
}
ns = {"page": 1, "rows": 10}
data = await sqlor.runSQLPaging(desc, ns)
# → {"total": 100, "rows": [...]}

4. CRUD 操作

# 创建
await sqlor.C("users", {"name": "Alice", "age": 25})

# 读取（分页）
res = await sqlor.R("users", {"page": 1, "rows": 10})

# 更新
await sqlor.U("users", {"id": 1, "age": 26})

# 删除
await sqlor.D("users", {"id": 1})

5. 获取表结构

desc = await sqlor.I("users")
print(desc['fields'])

---

异常处理

所有 SQL 执行异常都会被捕获并记录日志：

exception(f"{markedSQL=},{datas=}, {e=}, {fe=}")
raise e

推荐外部捕获 Exception 或自定义 SQLException。

---

配置说明

占位符配置

符号	默认	用途
sqltp / sqlts	$[ / ]$	控制结构模板（如 IF）
sqlvp / sqlvs	${ / }$	变量参数占位符

示例：

SELECT * FROM t WHERE status = ${status}$
$[ IF active ]$ AND active = 1 $[ ENDIF ]$

分页模型扩展

子类应重写 pagingSQLmodel() 提供数据库特定的分页语法。

例如 MySQL 子类：

def pagingSQLmodel(self):
    return "SELECT * FROM (%s) t LIMIT ${rows}$ OFFSET ${from_line}$"

Oracle 示例：

def pagingSQLmodel(self):
    return """
    SELECT * FROM (
        SELECT a.*, ROWNUM rn FROM (
            %s ORDER BY ${sort}$
        ) a WHERE ROWNUM <= ${end_line}$
    ) WHERE rn > ${from_line}$
    """

---

总结

SQLor 是一个轻量级但功能完整的数据库抽象层，适合用于 Web API 后端、ETL 工具或管理后台的数据访问组件。其优势在于：

✅ 清晰的 CRUD 接口
✅ 支持异步高性能场景
✅ 安全的参数绑定
✅ 易于扩展不同数据库方言

⚠️ 待改进点：

• 修复 SQLException.__init__ 错误
• commit() 中 self.datachanged 应为 self.dataChanged
• pagingdata() 中 cnt_desc 未定义
• setMeta 中 getMeta(self.tablename) 应为 self.getMeta(...)

---

📝 版本: v1.0
📅 最后更新: 2025-04-05
👨‍💻 作者: Auto-generated Documentation Tool