# SQLor 技术文档

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

---

## 目录

1. [概述](#概述)
2. [依赖与环境要求](#依赖与环境要求)
3. [核心功能](#核心功能)
4. [主要类与方法说明](#主要类与方法说明)
   - [`db_type_2_py_type`](#db_type_2_py_type)
   - [`SQLorException`](#sqlorexception)
   - [`findNamedParameters`](#findnamedparameters)
   - [`uniParams`](#uniparams)
   - [`readsql`](#readsql)
   - [`SQLor` 类](#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）。

---

## 依赖与环境要求

### 第三方依赖

```python
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`

### 环境变量

```python
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)`
返回字段列表，包含名称、类型（映射后），例如：
```python
[
  {"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 实例

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

### 2. 执行参数化查询

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

### 3. 分页查询

```python
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 操作

```python
# 创建
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. 获取表结构

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

---

## 异常处理

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

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

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

---

## 配置说明

### 占位符配置

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

示例：
```sql
SELECT * FROM t WHERE status = ${status}$
$[ IF active ]$ AND active = 1 $[ ENDIF ]$
```

### 分页模型扩展

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

例如 MySQL 子类：
```python
def pagingSQLmodel(self):
    return "SELECT * FROM (%s) t LIMIT ${rows}$ OFFSET ${from_line}$"
```

Oracle 示例：
```python
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