yimo-kit 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- yimo/__init__.py +26 -0
- yimo/kit/__init__.py +98 -0
- yimo/kit/ai/__init__.py +110 -0
- yimo/kit/ai/_internal/__init__.py +27 -0
- yimo/kit/ai/_internal/failover.py +535 -0
- yimo/kit/ai/_internal/pool.py +526 -0
- yimo/kit/ai/_internal/rerank_transport.py +137 -0
- yimo/kit/ai/_internal/retry_after.py +51 -0
- yimo/kit/ai/_internal/sdk_client.py +463 -0
- yimo/kit/ai/_internal/service_base.py +115 -0
- yimo/kit/ai/_internal/types.py +28 -0
- yimo/kit/ai/agent/__init__.py +127 -0
- yimo/kit/ai/agent/approval.py +66 -0
- yimo/kit/ai/agent/errors.py +128 -0
- yimo/kit/ai/agent/loop.py +643 -0
- yimo/kit/ai/agent/mcp.py +278 -0
- yimo/kit/ai/agent/registry.py +203 -0
- yimo/kit/ai/agent/session.py +150 -0
- yimo/kit/ai/agent/skill.py +370 -0
- yimo/kit/ai/agent/types.py +161 -0
- yimo/kit/ai/chat_service.py +724 -0
- yimo/kit/ai/decision/__init__.py +57 -0
- yimo/kit/ai/decision/decima.py +853 -0
- yimo/kit/ai/decision/laya.py +552 -0
- yimo/kit/ai/embedding_service.py +198 -0
- yimo/kit/ai/exceptions.py +109 -0
- yimo/kit/ai/image_service.py +84 -0
- yimo/kit/ai/messages.py +105 -0
- yimo/kit/ai/model_builder.py +121 -0
- yimo/kit/ai/model_client.py +62 -0
- yimo/kit/ai/profiles.py +577 -0
- yimo/kit/ai/rerank_service.py +136 -0
- yimo/kit/ai/runner.py +1127 -0
- yimo/kit/common_kit.py +221 -0
- yimo/kit/config/__init__.py +44 -0
- yimo/kit/config/kit_config.py +210 -0
- yimo/kit/config/log_config.py +171 -0
- yimo/kit/crawl/__init__.py +71 -0
- yimo/kit/crawl/article_io.py +325 -0
- yimo/kit/crawl/article_models.py +172 -0
- yimo/kit/crawl/deepseek_kit.py +673 -0
- yimo/kit/crawl/web_article_kit.py +638 -0
- yimo/kit/crawl/wx_article_kit.py +692 -0
- yimo/kit/db/__init__.py +101 -0
- yimo/kit/db/audit.py +625 -0
- yimo/kit/db/base_db_kit.py +1265 -0
- yimo/kit/db/crud.py +423 -0
- yimo/kit/db/engine.py +235 -0
- yimo/kit/db/exceptions.py +45 -0
- yimo/kit/db/models/__init__.py +33 -0
- yimo/kit/db/models/base.py +56 -0
- yimo/kit/db/mysql_kit.py +348 -0
- yimo/kit/db/pg_kit.py +442 -0
- yimo/kit/db/query.py +338 -0
- yimo/kit/db/session.py +85 -0
- yimo/kit/db/sqlite_kit.py +462 -0
- yimo/kit/db/transaction.py +109 -0
- yimo/kit/docs/__init__.py +34 -0
- yimo/kit/docs/anydoc_kit.py +490 -0
- yimo/kit/docs/docx_kit.py +895 -0
- yimo/kit/docs/md2doc_kit.py +1801 -0
- yimo/kit/docs/mineru_kit.py +1497 -0
- yimo/kit/docs/rc_docparser_kit.py +654 -0
- yimo/kit/file_kit.py +518 -0
- yimo/kit/license_kit.py +533 -0
- yimo/kit/redis_kit.py +392 -0
- yimo_kit-0.1.0.dist-info/METADATA +1673 -0
- yimo_kit-0.1.0.dist-info/RECORD +70 -0
- yimo_kit-0.1.0.dist-info/WHEEL +4 -0
- yimo_kit-0.1.0.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,1265 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Copyright (c) 2021-2026 溢墨修心(Yimo). All Rights Reserved.
|
|
3
|
+
|
|
4
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
you may not use this file except in compliance with the License.
|
|
6
|
+
You may obtain a copy of the License at
|
|
7
|
+
|
|
8
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
|
|
10
|
+
Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
See the License for the specific language governing permissions and
|
|
14
|
+
limitations under the License.
|
|
15
|
+
|
|
16
|
+
Project: yimo
|
|
17
|
+
Author: 溢墨修心(Yimo)
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
# date: 2026-08-22
|
|
23
|
+
"""数据库 Kit 共享基类(DRY 收敛)
|
|
24
|
+
|
|
25
|
+
三个数据库 Kit(PgKit / MySqlKit / SQLiteKit)在重构前拥有约 400 行几乎
|
|
26
|
+
逐行相同的代码(连接管理 / ORM / 原生 SQL / 原生表操作 / 事务 / 表操作),
|
|
27
|
+
仅 DB_TYPE 与 get_table_info 的 SQL 不同。本基类将全部共享实现收敛,子类
|
|
28
|
+
只声明 DB_TYPE 并覆写 get_table_info(SQLite 另含向量操作)。
|
|
29
|
+
|
|
30
|
+
2026-10-11:将原本仅 SQLiteKit 具备的 4 个方言无关方法(raw_connection /
|
|
31
|
+
create_raw_table / raw_insert / raw_get_by)上移到本基类,使三个 Kit 在该层
|
|
32
|
+
的能力与签名完全一致(共享方法 19 → 23)。
|
|
33
|
+
|
|
34
|
+
设计要点:
|
|
35
|
+
- 所有公开方法保留原签名与语义,外部调用零影响。
|
|
36
|
+
- 使用 PEP 695 方法级泛型 `T: SQLModel` 表达「模型类 → 实例」。
|
|
37
|
+
- 数据参数用 `dict[str, object]`(比 `dict[str, Any]` 严格)。
|
|
38
|
+
- 三层边界不变:本层方法自动提交(内部 session_scope);CRUDBase 不提交;
|
|
39
|
+
transaction() 上下文管理器管理多操作原子性。
|
|
40
|
+
- 类中存在公开方法 `list`,会遮蔽内置 `list` 类型;因此所有返回/参数中
|
|
41
|
+
的列表类型统一显式写作 `builtins.list[...]`,避免 mypy 将 `list[T]`
|
|
42
|
+
解析为方法名。
|
|
43
|
+
"""
|
|
44
|
+
|
|
45
|
+
import builtins
|
|
46
|
+
import json
|
|
47
|
+
import re
|
|
48
|
+
import threading
|
|
49
|
+
from abc import ABC, abstractmethod
|
|
50
|
+
from collections.abc import Generator
|
|
51
|
+
from contextlib import contextmanager
|
|
52
|
+
from typing import cast
|
|
53
|
+
|
|
54
|
+
from sqlalchemy import JSON, TextClause, bindparam, text
|
|
55
|
+
from sqlalchemy.pool import PoolProxiedConnection
|
|
56
|
+
from sqlmodel import Session, SQLModel
|
|
57
|
+
|
|
58
|
+
from yimo.kit.common_kit import CommonKit
|
|
59
|
+
from yimo.kit.config.log_config import get_default_logger
|
|
60
|
+
from yimo.kit.db.audit import (
|
|
61
|
+
UPDATED_AT,
|
|
62
|
+
AuditConfig,
|
|
63
|
+
candidate_columns,
|
|
64
|
+
deleted_predicate,
|
|
65
|
+
fill_insert_for,
|
|
66
|
+
fill_update,
|
|
67
|
+
fill_update_for,
|
|
68
|
+
table_columns,
|
|
69
|
+
touch_columns,
|
|
70
|
+
)
|
|
71
|
+
from yimo.kit.db.crud import CRUDBase
|
|
72
|
+
from yimo.kit.db.engine import (
|
|
73
|
+
MYSQL,
|
|
74
|
+
close_engine,
|
|
75
|
+
create_tables,
|
|
76
|
+
get_engine,
|
|
77
|
+
list_tables,
|
|
78
|
+
table_exists,
|
|
79
|
+
)
|
|
80
|
+
from yimo.kit.db.exceptions import DBError
|
|
81
|
+
from yimo.kit.db.session import session_scope
|
|
82
|
+
|
|
83
|
+
logger = get_default_logger(__name__)
|
|
84
|
+
|
|
85
|
+
# 字段数据:列名到值的映射(object 覆盖全部 SQLModel 支持类型)
|
|
86
|
+
type FieldData = dict[str, object]
|
|
87
|
+
|
|
88
|
+
# 向量检索的默认距离类型:三库能力集的交集(SQLite 仅支持 L2),
|
|
89
|
+
# 由三个数据库 Kit 的 search_vectors 共用,避免各 Kit 默认值漂移。
|
|
90
|
+
# 默认值不得按后端覆写——否则同一份代码换 import 后会在静默中改变度量语义。
|
|
91
|
+
DEFAULT_DISTANCE_TYPE = "L2"
|
|
92
|
+
|
|
93
|
+
# CRUD 实例缓存:CRUDBase 无状态(仅存 model),按 model 复用避免重复实例化
|
|
94
|
+
# 值类型取宽基类 SQLModel,规避 PEP 695 类型参数上界约束
|
|
95
|
+
_crud_cache: dict[type, CRUDBase[SQLModel, SQLModel, SQLModel]] = {}
|
|
96
|
+
_crud_lock = threading.Lock()
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def _get_crud[T: SQLModel](model: type[T]) -> CRUDBase[T, T, T]:
|
|
100
|
+
"""按模型获取(并缓存)CRUD 实例"""
|
|
101
|
+
crud = _crud_cache.get(model)
|
|
102
|
+
if crud is None:
|
|
103
|
+
with _crud_lock:
|
|
104
|
+
crud = _crud_cache.get(model)
|
|
105
|
+
if crud is None:
|
|
106
|
+
new_crud: CRUDBase[T, T, T] = CRUDBase(model)
|
|
107
|
+
crud = cast(CRUDBase[SQLModel, SQLModel, SQLModel], new_crud)
|
|
108
|
+
_crud_cache[model] = crud
|
|
109
|
+
return cast(CRUDBase[T, T, T], crud)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def to_vector_literal(vector: builtins.list[float]) -> str:
|
|
113
|
+
"""把 float 列表转换为向量文本字面量(如 [0.1, 0.2] → "[0.1,0.2]")
|
|
114
|
+
|
|
115
|
+
供共享相同文本格式的数据库后端复用:PgKit(pgvector 的 vector 类型)与
|
|
116
|
+
MySqlKit(STRING_TO_VECTOR)。SQLiteKit 走 float32 bytes,不使用本函数。
|
|
117
|
+
"""
|
|
118
|
+
return "[" + ",".join(repr(float(value)) for value in vector) + "]"
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def vector_insert_placeholders(
|
|
122
|
+
columns: builtins.list[str],
|
|
123
|
+
id_col: str,
|
|
124
|
+
column: str,
|
|
125
|
+
vector_placeholder: str = ":vec",
|
|
126
|
+
) -> str:
|
|
127
|
+
"""生成向量表 INSERT 的占位符串(供三个数据库 Kit 的 build_insert_vectors 共用)
|
|
128
|
+
|
|
129
|
+
绑定参数名与列名**解耦**:id 列固定为 ``:id``、向量列固定为 ``vector_placeholder``、
|
|
130
|
+
其余列用 ``:列名``。这样调用方覆写 ``id_col`` / ``column``(自建 DDL 场景)时,
|
|
131
|
+
参数字典的键不受列名影响。
|
|
132
|
+
|
|
133
|
+
Args:
|
|
134
|
+
columns: 列名列表(按 INSERT 顺序)
|
|
135
|
+
id_col: id 列名 → ``:id``
|
|
136
|
+
column: 向量列名 → ``vector_placeholder``
|
|
137
|
+
vector_placeholder: 向量列的占位符文本(MySQL 传 ``"STRING_TO_VECTOR(:vec)"``)
|
|
138
|
+
|
|
139
|
+
⚠ 内部符号(不在 ``yimo.kit.db.__all__``):调用方请用
|
|
140
|
+
`BaseDbKit.build_insert_vectors`,无需关心绑定名。
|
|
141
|
+
"""
|
|
142
|
+
|
|
143
|
+
def _one(name: str) -> str:
|
|
144
|
+
if name == column:
|
|
145
|
+
return vector_placeholder
|
|
146
|
+
if name == id_col:
|
|
147
|
+
return ":id"
|
|
148
|
+
return f":{name}"
|
|
149
|
+
|
|
150
|
+
return ", ".join(_one(name) for name in columns)
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
# 向量插入的内部保留绑定名(与 vector_insert_placeholders 的映射一一对应)
|
|
154
|
+
_RESERVED_BIND_NAMES = frozenset({"id", "vec"})
|
|
155
|
+
|
|
156
|
+
# 绑定参数名须为标识符:否则 SQLAlchemy 无法解析 `:name`(列名含空格等会得到
|
|
157
|
+
# "A value is required for bind parameter" 这类无法定位的报错)
|
|
158
|
+
_BIND_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def _check_identifier(name: str) -> None:
|
|
162
|
+
"""校验表名 / 列名为合法标识符(拼接进 SQL 前的白名单)
|
|
163
|
+
|
|
164
|
+
Raises:
|
|
165
|
+
ValueError: 含字母、数字、下划线以外的字符,或以数字开头
|
|
166
|
+
"""
|
|
167
|
+
if not _BIND_NAME_RE.match(name):
|
|
168
|
+
raise ValueError(
|
|
169
|
+
f"{name!r} 不是合法标识符(表名/列名仅允许字母、数字、下划线)"
|
|
170
|
+
)
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
# 写入侧需要特殊处理的序列类型(会被 prepare_statement 当作 IN 展开,须先消除)
|
|
174
|
+
_WRITE_SEQUENCE_TYPES = (list, tuple, set, frozenset)
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def _adapt_write_values(
|
|
178
|
+
db_type: str, table_name: str, data: dict[str, object]
|
|
179
|
+
) -> None:
|
|
180
|
+
"""按目标列类型适配写入值(**原地修改** data;惰性探测)
|
|
181
|
+
|
|
182
|
+
规则(二次评估定稿):
|
|
183
|
+
|
|
184
|
+
- ``dict``:任何驱动都无法直接绑定 → 一律编码为 JSON 文本;
|
|
185
|
+
- ``list`` / ``tuple`` / ``set`` / ``frozenset``:仅当目标列是 JSON 类型时编码;
|
|
186
|
+
其它列抛 ``ValueError``——这些序列会被 ``prepare_statement`` 当作 ``IN`` 展开,
|
|
187
|
+
写进 ``VALUES`` 会破坏 SQL 结构(数组 / 向量请用字符串或 ``execute()`` 手写)。
|
|
188
|
+
|
|
189
|
+
只有 ``data`` 中确实出现上述类型时才探测列(纯标量写入零额外查询)。
|
|
190
|
+
"""
|
|
191
|
+
if not any(isinstance(v, (dict, *_WRITE_SEQUENCE_TYPES)) for v in data.values()):
|
|
192
|
+
return
|
|
193
|
+
|
|
194
|
+
columns = table_columns(db_type, table_name)
|
|
195
|
+
for name, value in list(data.items()):
|
|
196
|
+
if isinstance(value, dict):
|
|
197
|
+
data[name] = json.dumps(value, ensure_ascii=False)
|
|
198
|
+
continue
|
|
199
|
+
if isinstance(value, _WRITE_SEQUENCE_TYPES):
|
|
200
|
+
column_type = columns.get(name)
|
|
201
|
+
if column_type is None:
|
|
202
|
+
raise ValueError(
|
|
203
|
+
f"{name!r} 的值是序列,但表 {table_name} 中查不到该列"
|
|
204
|
+
f"(或列探测失败):请确认表已提交建好;"
|
|
205
|
+
f"JSON 列请传 dict / list;向量请用 to_vector_literal(...);"
|
|
206
|
+
f"数组等其它类型请用 execute() 手写 SQL"
|
|
207
|
+
)
|
|
208
|
+
if isinstance(column_type, JSON):
|
|
209
|
+
data[name] = json.dumps(list(value), ensure_ascii=False)
|
|
210
|
+
else:
|
|
211
|
+
raise ValueError(
|
|
212
|
+
f"{name!r} 的值是序列,且目标列不是 JSON 类型:"
|
|
213
|
+
f"JSON 列请传 dict / list;向量请用 to_vector_literal(...);"
|
|
214
|
+
f"数组等其它类型请用 execute() 手写 SQL"
|
|
215
|
+
)
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def _check_extra_key(key: str, id_col: str, column: str) -> None:
|
|
219
|
+
"""校验 ``extra_data`` 的键可作为绑定参数名(拼装前抛出可操作的 ``ValueError``)
|
|
220
|
+
|
|
221
|
+
三类问题(均实测):
|
|
222
|
+
① 保留绑定名 ``id`` / ``vec`` → ``params`` 被覆盖,SQLite 静默写坏数据;
|
|
223
|
+
② 与 ``id_col`` / ``column`` 重复 → SQLite 接受重复列名并丢弃调用方给的值;
|
|
224
|
+
③ 不是合法标识符 → 报错无法定位("A value is required for bind parameter")。
|
|
225
|
+
"""
|
|
226
|
+
if key in _RESERVED_BIND_NAMES:
|
|
227
|
+
raise ValueError(
|
|
228
|
+
f"extra_data 含保留绑定名 {key!r}:向量插入的内部绑定名固定为 "
|
|
229
|
+
f"'id'(id 列)与 'vec'(向量列),同名业务列会覆盖它们;"
|
|
230
|
+
f"请重命名该键,或改用自定义 SQL(配合 Kit.transaction())"
|
|
231
|
+
)
|
|
232
|
+
if key in (id_col, column):
|
|
233
|
+
raise ValueError(
|
|
234
|
+
f"extra_data 含重复列 {key!r}:该列已由 id_col / column 覆盖"
|
|
235
|
+
)
|
|
236
|
+
if not _BIND_NAME_RE.match(key):
|
|
237
|
+
raise ValueError(
|
|
238
|
+
f"extra_data 的键 {key!r} 不是合法标识符,无法生成绑定参数名"
|
|
239
|
+
)
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
def normalize_extra_cols(
|
|
243
|
+
extra_cols: dict[str, str] | builtins.list[dict[str, str]] | None,
|
|
244
|
+
) -> builtins.list[tuple[str, str]]:
|
|
245
|
+
"""归一化 ``create_vector_table`` 的额外列定义(两种入参形态)
|
|
246
|
+
|
|
247
|
+
接受 ``{列名: 方言类型串}``(推荐,与 `create_raw_table` 同形,**键序即 DDL 列序**)
|
|
248
|
+
或既有 ``[{"name": ..., "type": ...}]``;空值返回空列表。
|
|
249
|
+
两种形态产出**逐字一致**的 DDL。
|
|
250
|
+
"""
|
|
251
|
+
if not extra_cols:
|
|
252
|
+
return []
|
|
253
|
+
if isinstance(extra_cols, dict):
|
|
254
|
+
return [(name, col_type) for name, col_type in extra_cols.items()]
|
|
255
|
+
return [(col["name"], col["type"]) for col in extra_cols]
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
def generate_snowflake_ids(count: int) -> builtins.list[int]:
|
|
259
|
+
"""生成 count 个雪花 ID(int64;当前 18 位,上限 19 位)
|
|
260
|
+
|
|
261
|
+
供三个数据库 Kit 的向量方法在调用方未提供 id(``ids=None``)时兜底使用:
|
|
262
|
+
id 由**应用侧(kit)生成**而非数据库自增,保证三库语义一致,同时避免
|
|
263
|
+
PostgreSQL 序列不随显式 id 推进的问题(BIGSERIAL → 纯 BIGINT 主键)。
|
|
264
|
+
|
|
265
|
+
⚠ 雪花 ID 超过 2^53,经 JSON 传给 JavaScript 会丢精度,需按字符串传输。
|
|
266
|
+
"""
|
|
267
|
+
return [CommonKit.generate_snowflake_id() for _ in range(count)]
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
# 可参与 IN 展开的参数类型(按类型白名单判断,绝不用 Iterable:
|
|
271
|
+
# 否则字符串会被逐字符展开)
|
|
272
|
+
_EXPANDING_TYPES = (list, tuple, set, frozenset)
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
def prepare_statement(
|
|
276
|
+
sql: str, params: FieldData | builtins.list[FieldData] | None = None
|
|
277
|
+
) -> tuple[TextClause, FieldData | builtins.list[FieldData] | None]:
|
|
278
|
+
"""把 SQL 文本 + 参数转为(可直接执行的语句, 参数)
|
|
279
|
+
|
|
280
|
+
供调用方在**自有事务**(`*Kit.transaction()`)内执行原生 SQL,
|
|
281
|
+
与 ``query`` / ``execute`` 使用**同一套参数规则**(单一事实源)——
|
|
282
|
+
单字典形态下后两者等价于 ``session.execute(*prepare_statement(sql, params))``;
|
|
283
|
+
本函数**不建连接、不改状态、不执行**。
|
|
284
|
+
|
|
285
|
+
两种参数形态(与 ``execute`` 对称):
|
|
286
|
+
|
|
287
|
+
- **单字典**:值为 ``list`` / ``tuple`` / ``set`` / ``frozenset`` 的键按
|
|
288
|
+
SQLAlchemy **expanding** 语义绑定,可直接书写 ``WHERE id IN :ids``
|
|
289
|
+
(三库通用);第二项为归一化后的参数字典;
|
|
290
|
+
- **字典列表**(批量 / executemany):第二项**原样返回该列表**,语句为
|
|
291
|
+
裸 ``text(sql)``(**不做** ``IN`` 展开——批量与展开参数互斥,与
|
|
292
|
+
``execute`` 的批量约束一致);经 ``_validate_batch_rows`` 本地预校验
|
|
293
|
+
(各行键集一致、行值为标量)。
|
|
294
|
+
|
|
295
|
+
典型用法(调用方**无须 import sqlalchemy**)::
|
|
296
|
+
|
|
297
|
+
from yimo.kit.db import SQLiteKit, prepare_statement
|
|
298
|
+
|
|
299
|
+
stmt, bound = prepare_statement(
|
|
300
|
+
"DELETE FROM t WHERE id IN :ids", {"ids": [1, 2, 3]}
|
|
301
|
+
)
|
|
302
|
+
with SQLiteKit.transaction() as session:
|
|
303
|
+
session.execute(stmt, bound) # 第二个值必须一并传入
|
|
304
|
+
|
|
305
|
+
stmt, rows = prepare_statement( # 批量(executemany)
|
|
306
|
+
"INSERT INTO t (a, b) VALUES (:a, :b)", [{"a": 1, "b": 2}]
|
|
307
|
+
)
|
|
308
|
+
with SQLiteKit.transaction() as session:
|
|
309
|
+
session.execute(stmt, rows)
|
|
310
|
+
|
|
311
|
+
三条实现约束(**单字典形态**,与 ``query`` / ``execute`` 现有语义完全一致):
|
|
312
|
+
|
|
313
|
+
1. 只对**确实出现在 SQL 文本中**的参数名做 expanding —— 否则传入"未使用的
|
|
314
|
+
序列参数"会触发 SQLAlchemy 的 ``ArgumentError: This text() construct
|
|
315
|
+
doesn't define a bound parameter …``,该报错对使用方没有意义;
|
|
316
|
+
2. 按类型白名单判断(见 `_EXPANDING_TYPES`),字符串不会被当作列表;
|
|
317
|
+
3. ``set`` / ``frozenset`` 归一化为 ``list`` —— SQLAlchemy 的 expanding 只接受
|
|
318
|
+
**可下标序列**(直接传 set 会抛 ``TypeError: 'set' object is not
|
|
319
|
+
subscriptable``);``IN`` 与顺序无关,故归一化不改变语义。
|
|
320
|
+
|
|
321
|
+
Args:
|
|
322
|
+
sql: SQL 语句(使用命名参数 ``:param``)
|
|
323
|
+
params: **单个参数字典**(值为 ``list`` / ``tuple`` / ``set`` / ``frozenset``
|
|
324
|
+
的键按 ``IN`` 展开,三库通用)或**参数字典的列表**(批量,行值须为标量)
|
|
325
|
+
|
|
326
|
+
Returns:
|
|
327
|
+
``(语句, 参数)``:执行时**必须**把第二个值一并传给 ``session.execute``;
|
|
328
|
+
``params`` 为 None 时第二项即 None,为列表时**原样返回该列表**
|
|
329
|
+
|
|
330
|
+
Note:
|
|
331
|
+
``:name::type`` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 ``text()``
|
|
332
|
+
识别**(该写法在支持本函数之前同样不可用),请改用 ``CAST(:name AS type)``。
|
|
333
|
+
|
|
334
|
+
Raises:
|
|
335
|
+
ValueError: 列表形态的行键集不一致或行值含序列类型(来自
|
|
336
|
+
``_validate_batch_rows``,与 ``execute`` 批量形态同一规则)
|
|
337
|
+
|
|
338
|
+
See Also:
|
|
339
|
+
``query`` / ``execute``:kit 自管事务的原生 SQL 入口(同样支持列表参数)。
|
|
340
|
+
"""
|
|
341
|
+
if isinstance(params, builtins.list):
|
|
342
|
+
# 批量形态:语句不做 IN 展开,参数行列表原样返回(由 execute/session
|
|
343
|
+
# 以 executemany 执行);空列表不校验、不报错(构造期无副作用)
|
|
344
|
+
if params:
|
|
345
|
+
_validate_batch_rows(params)
|
|
346
|
+
return text(sql), params
|
|
347
|
+
|
|
348
|
+
statement = text(sql)
|
|
349
|
+
if not params:
|
|
350
|
+
return statement, params
|
|
351
|
+
|
|
352
|
+
normalized: FieldData = {}
|
|
353
|
+
expanding: list[object] = []
|
|
354
|
+
for name, value in params.items():
|
|
355
|
+
if isinstance(value, _EXPANDING_TYPES):
|
|
356
|
+
if isinstance(value, (set, frozenset)):
|
|
357
|
+
value = list(value)
|
|
358
|
+
normalized[name] = value
|
|
359
|
+
# 约束 1:只对确实出现在 SQL 文本中的参数名做 expanding
|
|
360
|
+
if re.search(rf":{re.escape(name)}\b", sql):
|
|
361
|
+
expanding.append(bindparam(name, expanding=True))
|
|
362
|
+
else:
|
|
363
|
+
normalized[name] = value
|
|
364
|
+
|
|
365
|
+
if expanding:
|
|
366
|
+
statement = statement.bindparams(*expanding) # type: ignore[arg-type]
|
|
367
|
+
return statement, normalized
|
|
368
|
+
|
|
369
|
+
|
|
370
|
+
def _validate_batch_rows(rows: builtins.list[FieldData]) -> None:
|
|
371
|
+
"""批量执行(executemany)的本地预校验:键集一致 + 不含序列参数
|
|
372
|
+
|
|
373
|
+
约束来自 DBAPI 的 executemany 语义(实测):
|
|
374
|
+
|
|
375
|
+
1. 各行字典的**键集必须完全一致** —— 否则 SQLAlchemy 报
|
|
376
|
+
``StatementError: A value is required for bind parameter 'xxx'``,
|
|
377
|
+
不指明是哪一行,对使用方没有意义;
|
|
378
|
+
2. 行值须为**标量** —— 批量与 ``IN`` 展开(expanding)**互斥**:对批量语句
|
|
379
|
+
做 expanding 标注后按行执行会得到 ``OperationalError: near "?": syntax error``
|
|
380
|
+
这类驱动级错误(三库通用行为)。
|
|
381
|
+
|
|
382
|
+
在本地提前给出**可操作的** ``ValueError``(含行号与差异明细),
|
|
383
|
+
避免把上述两类无意义报错暴露给使用方。
|
|
384
|
+
|
|
385
|
+
Args:
|
|
386
|
+
rows: 批量参数(非空)
|
|
387
|
+
|
|
388
|
+
Raises:
|
|
389
|
+
ValueError: 键集不一致,或行值中含序列类型
|
|
390
|
+
"""
|
|
391
|
+
base = set(rows[0])
|
|
392
|
+
for index, row in enumerate(rows):
|
|
393
|
+
keys = set(row)
|
|
394
|
+
if keys != base:
|
|
395
|
+
raise ValueError(
|
|
396
|
+
f"批量参数第 {index} 行的键集与第 0 行不一致:"
|
|
397
|
+
f"缺少 {sorted(base - keys)},多出 {sorted(keys - base)};"
|
|
398
|
+
f"executemany 要求各行键集完全一致"
|
|
399
|
+
)
|
|
400
|
+
for name, value in row.items():
|
|
401
|
+
if isinstance(value, _EXPANDING_TYPES):
|
|
402
|
+
raise ValueError(
|
|
403
|
+
f"批量参数第 {index} 行的 {name!r} 是序列类型:"
|
|
404
|
+
f"批量执行(executemany)与 IN 展开(expanding)互斥;"
|
|
405
|
+
f"如需 IN 语义请改用单个参数字典(execute 的单字典形态),"
|
|
406
|
+
f"或逐行调用 execute"
|
|
407
|
+
)
|
|
408
|
+
|
|
409
|
+
|
|
410
|
+
class BaseDbKit(ABC):
|
|
411
|
+
"""数据库工具类共享基类
|
|
412
|
+
|
|
413
|
+
子类需声明 `DB_TYPE` 并实现 `get_table_info`。所有方法均为类方法,
|
|
414
|
+
业务代码无需实例化。
|
|
415
|
+
"""
|
|
416
|
+
|
|
417
|
+
# 数据库类型标识(postgresql / mysql / sqlite),由子类覆写
|
|
418
|
+
DB_TYPE: str
|
|
419
|
+
|
|
420
|
+
# 向量列的占位符(后端覆写点):MySQL 需经 STRING_TO_VECTOR 转换
|
|
421
|
+
VECTOR_PLACEHOLDER: str = ":vec"
|
|
422
|
+
|
|
423
|
+
# ==================== 向量写入的共享构造(只拼装,不执行) ====================
|
|
424
|
+
|
|
425
|
+
@classmethod
|
|
426
|
+
def _vector_param(cls, vector: builtins.list[float]) -> object:
|
|
427
|
+
"""向量 → 绑定参数值(**私有钩子**,子类覆写;基类=文本字面量)
|
|
428
|
+
|
|
429
|
+
PostgreSQL(pgvector)与 MySQL(``STRING_TO_VECTOR``)共用文本字面量;
|
|
430
|
+
`SQLiteKit` 覆写为 float32 小端字节。
|
|
431
|
+
"""
|
|
432
|
+
return to_vector_literal(vector)
|
|
433
|
+
|
|
434
|
+
@classmethod
|
|
435
|
+
def build_insert_vectors(
|
|
436
|
+
cls,
|
|
437
|
+
table_name: str,
|
|
438
|
+
vectors: builtins.list[builtins.list[float]],
|
|
439
|
+
ids: builtins.list[int] | None = None,
|
|
440
|
+
extra_data: builtins.list[dict[str, object]] | None = None,
|
|
441
|
+
id_col: str = "id",
|
|
442
|
+
column: str = "embedding",
|
|
443
|
+
) -> builtins.list[tuple[str, builtins.list[dict[str, object]]]]:
|
|
444
|
+
"""构造向量表 INSERT 语句(**只拼装、不执行、不管事务**)
|
|
445
|
+
|
|
446
|
+
供调用方在**自己的事务**内写入向量行(与其它表行同事务提交)::
|
|
447
|
+
|
|
448
|
+
with SQLiteKit.transaction() as session:
|
|
449
|
+
session.execute(text("INSERT INTO docs_item (...) VALUES (...)"), {...})
|
|
450
|
+
for sql, params in SQLiteKit.build_insert_vectors("docs_doc_vectors",
|
|
451
|
+
vectors, ids=[...],
|
|
452
|
+
id_col="rowid"):
|
|
453
|
+
session.execute(text(sql), params)
|
|
454
|
+
|
|
455
|
+
Args:
|
|
456
|
+
table_name: 表名
|
|
457
|
+
vectors: 向量列表,每个向量为 float 列表(也接受二维 numpy 数组)
|
|
458
|
+
ids: 可选的 ID 列表(长度需与 vectors 一致);None 时由 Kit 生成雪花 ID
|
|
459
|
+
(生成值可从返回的参数列表读取)
|
|
460
|
+
extra_data: 额外列数据列表(长度需与 vectors 一致)
|
|
461
|
+
id_col: 主键列名(默认 ``id``,供自建 DDL 的表使用)
|
|
462
|
+
column: 向量列名(默认 ``embedding``,供自建 DDL 的表使用)
|
|
463
|
+
|
|
464
|
+
Returns:
|
|
465
|
+
按**列集分组**的 ``[(SQL, 参数列表), ...]``:同列集的行合并为一条可
|
|
466
|
+
``executemany`` 的语句(常规同构 ``extra_data`` 只返回 1 条)。SQL 为
|
|
467
|
+
SQLAlchemy ``text()`` 风格(``:id`` / ``:vec`` / ``:列名``)。
|
|
468
|
+
|
|
469
|
+
Raises:
|
|
470
|
+
ValueError: 入参自洽性校验失败——长度/维度不一致、``extra_data`` 键为保留绑定名
|
|
471
|
+
(``id`` / ``vec``)或与 ``id_col`` / ``column`` 重复、键不是合法标识符、
|
|
472
|
+
``id_col == column``
|
|
473
|
+
|
|
474
|
+
Note:
|
|
475
|
+
- **无副作用**:不建连接、不接触数据库、不改任何状态;对**不存在的表**也正常返回。
|
|
476
|
+
- **执行载体**:SQLite 可直接在 ``raw_connection()``(DBAPI 支持 ``:name``)或
|
|
477
|
+
``transaction()`` 上执行;**PG / MySQL 的原生 DBAPI 不支持 ``:name``**
|
|
478
|
+
(psycopg2 / pymysql 需 ``%(name)s``),须经 ``Kit.transaction()`` 的 session 执行。
|
|
479
|
+
- ``insert_vectors`` 的执行语义即"本方法 + 自带事务",两者共用同一份拼装逻辑。
|
|
480
|
+
"""
|
|
481
|
+
if id_col == column:
|
|
482
|
+
raise ValueError(f"id_col 与 column 不能同名(当前均为 {id_col!r})")
|
|
483
|
+
# 用 len() 而非真值判断:入参可为 list 或二维 numpy 数组
|
|
484
|
+
if len(vectors) == 0:
|
|
485
|
+
return []
|
|
486
|
+
if ids is None:
|
|
487
|
+
ids = generate_snowflake_ids(len(vectors))
|
|
488
|
+
if len(ids) != len(vectors):
|
|
489
|
+
raise ValueError("ids 长度必须与 vectors 一致")
|
|
490
|
+
if extra_data is not None and len(extra_data) != len(vectors):
|
|
491
|
+
raise ValueError("extra_data 长度必须与 vectors 一致")
|
|
492
|
+
|
|
493
|
+
dims = len(vectors[0])
|
|
494
|
+
if any(len(vec) != dims for vec in vectors):
|
|
495
|
+
raise ValueError(
|
|
496
|
+
f"同一批次的向量长度必须一致(首个向量 {dims} 维,存在其它维度的向量)"
|
|
497
|
+
)
|
|
498
|
+
|
|
499
|
+
# 按「列集合」分组:executemany 要求同一语句的参数列表**键集一致**
|
|
500
|
+
groups: dict[tuple[str, ...], builtins.list[dict[str, object]]] = {}
|
|
501
|
+
for i, vector in enumerate(vectors):
|
|
502
|
+
columns: builtins.list[str] = [id_col, column]
|
|
503
|
+
params: dict[str, object] = {"id": ids[i], "vec": cls._vector_param(vector)}
|
|
504
|
+
if extra_data is not None:
|
|
505
|
+
for key, value in extra_data[i].items():
|
|
506
|
+
_check_extra_key(key, id_col, column)
|
|
507
|
+
columns.append(key)
|
|
508
|
+
params[key] = value
|
|
509
|
+
groups.setdefault(tuple(columns), []).append(params)
|
|
510
|
+
|
|
511
|
+
statements: builtins.list[tuple[str, builtins.list[dict[str, object]]]] = []
|
|
512
|
+
for columns_tuple, params_list in groups.items():
|
|
513
|
+
columns_list = list(columns_tuple)
|
|
514
|
+
placeholders = vector_insert_placeholders(
|
|
515
|
+
columns_list, id_col, column, cls.VECTOR_PLACEHOLDER
|
|
516
|
+
)
|
|
517
|
+
statements.append(
|
|
518
|
+
(
|
|
519
|
+
f"INSERT INTO {table_name} ({', '.join(columns_list)}) "
|
|
520
|
+
f"VALUES ({placeholders})",
|
|
521
|
+
params_list,
|
|
522
|
+
)
|
|
523
|
+
)
|
|
524
|
+
return statements
|
|
525
|
+
|
|
526
|
+
# ==================== 连接管理 ====================
|
|
527
|
+
|
|
528
|
+
@classmethod
|
|
529
|
+
def connect(cls) -> bool:
|
|
530
|
+
"""初始化数据库连接(延迟创建引擎并验证连通性)
|
|
531
|
+
|
|
532
|
+
Returns:
|
|
533
|
+
True 表示连接成功
|
|
534
|
+
"""
|
|
535
|
+
try:
|
|
536
|
+
engine = get_engine(cls.DB_TYPE)
|
|
537
|
+
with engine.connect() as conn:
|
|
538
|
+
conn.execute(text("SELECT 1"))
|
|
539
|
+
logger.info("✅ 数据库连接成功")
|
|
540
|
+
return True
|
|
541
|
+
except Exception as e:
|
|
542
|
+
logger.error(f"❌ 数据库连接失败: {e}")
|
|
543
|
+
return False
|
|
544
|
+
|
|
545
|
+
@classmethod
|
|
546
|
+
def close(cls) -> None:
|
|
547
|
+
"""关闭数据库连接"""
|
|
548
|
+
close_engine(cls.DB_TYPE)
|
|
549
|
+
logger.info("🔌 数据库连接已关闭")
|
|
550
|
+
|
|
551
|
+
@classmethod
|
|
552
|
+
def is_connected(cls) -> bool:
|
|
553
|
+
"""检查数据库是否可连接"""
|
|
554
|
+
try:
|
|
555
|
+
engine = get_engine(cls.DB_TYPE)
|
|
556
|
+
with engine.connect() as conn:
|
|
557
|
+
conn.execute(text("SELECT 1"))
|
|
558
|
+
return True
|
|
559
|
+
except Exception:
|
|
560
|
+
return False
|
|
561
|
+
|
|
562
|
+
@classmethod
|
|
563
|
+
def raw_connection(cls) -> PoolProxiedConnection:
|
|
564
|
+
"""获取原生 DBAPI 连接(引擎侧扩展加载已由 engine.py 自动完成)
|
|
565
|
+
|
|
566
|
+
PostgreSQL 返回 psycopg2 连接、MySQL 返回 pymysql 连接、SQLite 返回
|
|
567
|
+
sqlite3 连接(sqlite-vector 扩展已自动加载)。用于执行驱动特有函数与
|
|
568
|
+
静态 DDL。
|
|
569
|
+
|
|
570
|
+
⚠ 调用方负责提交与关闭连接。psycopg2 / pymysql 默认**不开启自动提交**,
|
|
571
|
+
与 sqlite3 的使用习惯不同:需要落库时必须显式 commit。
|
|
572
|
+
"""
|
|
573
|
+
return get_engine(cls.DB_TYPE).raw_connection()
|
|
574
|
+
|
|
575
|
+
# ==================== ORM 操作(自动管理 session) ====================
|
|
576
|
+
|
|
577
|
+
@classmethod
|
|
578
|
+
def create[T: SQLModel](cls, model: type[T], data: FieldData) -> T:
|
|
579
|
+
"""创建单条记录
|
|
580
|
+
|
|
581
|
+
Args:
|
|
582
|
+
model: SQLModel 模型类
|
|
583
|
+
data: 字段名到值的映射
|
|
584
|
+
|
|
585
|
+
Returns:
|
|
586
|
+
创建后的模型实例(含主键)
|
|
587
|
+
"""
|
|
588
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
589
|
+
crud = _get_crud(model)
|
|
590
|
+
obj = crud.create(session, data)
|
|
591
|
+
session.expunge(obj) # 脱离 session,使返回值在 session 关闭后仍可用
|
|
592
|
+
return obj
|
|
593
|
+
|
|
594
|
+
@classmethod
|
|
595
|
+
def create_multi[T: SQLModel](
|
|
596
|
+
cls, model: type[T], data_list: builtins.list[FieldData]
|
|
597
|
+
) -> builtins.list[T]:
|
|
598
|
+
"""批量创建记录
|
|
599
|
+
|
|
600
|
+
Args:
|
|
601
|
+
model: SQLModel 模型类
|
|
602
|
+
data_list: 字段字典列表
|
|
603
|
+
|
|
604
|
+
Returns:
|
|
605
|
+
创建后的模型实例列表
|
|
606
|
+
"""
|
|
607
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
608
|
+
crud = _get_crud(model)
|
|
609
|
+
objs = crud.create_multi(
|
|
610
|
+
session, cast(builtins.list[T | FieldData], data_list)
|
|
611
|
+
)
|
|
612
|
+
for obj in objs:
|
|
613
|
+
session.expunge(obj)
|
|
614
|
+
return objs
|
|
615
|
+
|
|
616
|
+
@classmethod
|
|
617
|
+
def get[T: SQLModel](cls, model: type[T], id: object) -> T | None:
|
|
618
|
+
"""根据主键获取单条记录
|
|
619
|
+
|
|
620
|
+
Args:
|
|
621
|
+
model: SQLModel 模型类
|
|
622
|
+
id: 主键值
|
|
623
|
+
|
|
624
|
+
Returns:
|
|
625
|
+
模型实例,不存在时返回 None
|
|
626
|
+
"""
|
|
627
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
628
|
+
obj = session.get(model, id)
|
|
629
|
+
if obj:
|
|
630
|
+
session.expunge(obj)
|
|
631
|
+
return obj
|
|
632
|
+
|
|
633
|
+
@classmethod
|
|
634
|
+
def get_by[T: SQLModel](
|
|
635
|
+
cls, model: type[T], field_name: str, field_value: object
|
|
636
|
+
) -> T | None:
|
|
637
|
+
"""根据字段值获取单条记录
|
|
638
|
+
|
|
639
|
+
Args:
|
|
640
|
+
model: SQLModel 模型类
|
|
641
|
+
field_name: 字段名
|
|
642
|
+
field_value: 字段值
|
|
643
|
+
|
|
644
|
+
Returns:
|
|
645
|
+
模型实例,不存在时返回 None
|
|
646
|
+
"""
|
|
647
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
648
|
+
crud = _get_crud(model)
|
|
649
|
+
obj = crud.get_by_field(session, field_name, field_value)
|
|
650
|
+
if obj:
|
|
651
|
+
session.expunge(obj)
|
|
652
|
+
return obj
|
|
653
|
+
|
|
654
|
+
@classmethod
|
|
655
|
+
def list[T: SQLModel](
|
|
656
|
+
cls,
|
|
657
|
+
model: type[T],
|
|
658
|
+
*,
|
|
659
|
+
skip: int = 0,
|
|
660
|
+
limit: int = 100,
|
|
661
|
+
order_by: str | None = None,
|
|
662
|
+
desc: bool = False,
|
|
663
|
+
) -> builtins.list[T]:
|
|
664
|
+
"""获取多条记录(分页 + 排序)
|
|
665
|
+
|
|
666
|
+
Args:
|
|
667
|
+
model: SQLModel 模型类
|
|
668
|
+
skip: 跳过记录数
|
|
669
|
+
limit: 返回记录数上限
|
|
670
|
+
order_by: 排序字段名
|
|
671
|
+
desc: 是否降序排列
|
|
672
|
+
|
|
673
|
+
Returns:
|
|
674
|
+
模型实例列表
|
|
675
|
+
"""
|
|
676
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
677
|
+
crud = _get_crud(model)
|
|
678
|
+
results = crud.get_multi(
|
|
679
|
+
session, skip=skip, limit=limit, order_by=order_by, desc=desc
|
|
680
|
+
)
|
|
681
|
+
for obj in results:
|
|
682
|
+
session.expunge(obj)
|
|
683
|
+
return results
|
|
684
|
+
|
|
685
|
+
@classmethod
|
|
686
|
+
def update[T: SQLModel](cls, model: type[T], id: object, data: FieldData) -> T:
|
|
687
|
+
"""更新单条记录
|
|
688
|
+
|
|
689
|
+
Args:
|
|
690
|
+
model: SQLModel 模型类
|
|
691
|
+
id: 主键值
|
|
692
|
+
data: 需要更新的字段字典
|
|
693
|
+
|
|
694
|
+
Returns:
|
|
695
|
+
更新后的模型实例
|
|
696
|
+
"""
|
|
697
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
698
|
+
crud = _get_crud(model)
|
|
699
|
+
obj = crud.get_or_raise(session, id)
|
|
700
|
+
crud.update(session, obj, data)
|
|
701
|
+
session.expunge(obj)
|
|
702
|
+
return obj
|
|
703
|
+
|
|
704
|
+
@classmethod
|
|
705
|
+
def delete[T: SQLModel](cls, model: type[T], id: object) -> bool:
|
|
706
|
+
"""删除单条记录
|
|
707
|
+
|
|
708
|
+
Args:
|
|
709
|
+
model: SQLModel 模型类
|
|
710
|
+
id: 主键值
|
|
711
|
+
|
|
712
|
+
Returns:
|
|
713
|
+
True 表示删除成功,False 表示记录不存在
|
|
714
|
+
"""
|
|
715
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
716
|
+
crud = _get_crud(model)
|
|
717
|
+
obj = crud.delete(session, id)
|
|
718
|
+
return obj is not None
|
|
719
|
+
|
|
720
|
+
@classmethod
|
|
721
|
+
def upsert[T: SQLModel](
|
|
722
|
+
cls, model: type[T], data: FieldData, conflict_fields: builtins.list[str]
|
|
723
|
+
) -> T:
|
|
724
|
+
"""插入或更新记录
|
|
725
|
+
|
|
726
|
+
根据 conflict_fields 判断记录是否已存在,存在则更新,不存在则插入。
|
|
727
|
+
|
|
728
|
+
Args:
|
|
729
|
+
model: SQLModel 模型类
|
|
730
|
+
data: 字段字典
|
|
731
|
+
conflict_fields: 用于判断冲突的字段列表
|
|
732
|
+
|
|
733
|
+
Returns:
|
|
734
|
+
创建或更新后的模型实例
|
|
735
|
+
"""
|
|
736
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
737
|
+
crud = _get_crud(model)
|
|
738
|
+
obj = crud.upsert(session, data, conflict_fields)
|
|
739
|
+
session.expunge(obj)
|
|
740
|
+
return obj
|
|
741
|
+
|
|
742
|
+
@classmethod
|
|
743
|
+
def count(cls, model: type[SQLModel]) -> int:
|
|
744
|
+
"""获取记录总数
|
|
745
|
+
|
|
746
|
+
Args:
|
|
747
|
+
model: SQLModel 模型类
|
|
748
|
+
|
|
749
|
+
Returns:
|
|
750
|
+
记录总数
|
|
751
|
+
"""
|
|
752
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
753
|
+
crud = _get_crud(model)
|
|
754
|
+
return crud.count(session)
|
|
755
|
+
|
|
756
|
+
# ==================== 原生 SQL 操作 ====================
|
|
757
|
+
|
|
758
|
+
@classmethod
|
|
759
|
+
def query(
|
|
760
|
+
cls, sql: str, params: FieldData | None = None
|
|
761
|
+
) -> builtins.list[dict[str, object]]:
|
|
762
|
+
"""执行原生查询 SQL,返回字典列表
|
|
763
|
+
|
|
764
|
+
Args:
|
|
765
|
+
sql: SQL 查询语句(使用命名参数 :param)
|
|
766
|
+
params: 参数字典。值为 list / tuple / set / frozenset 的参数按 ``IN`` 展开,
|
|
767
|
+
可直接书写 ``WHERE id IN :ids``(三库通用)
|
|
768
|
+
|
|
769
|
+
Returns:
|
|
770
|
+
查询结果列表,每行为一个字典
|
|
771
|
+
|
|
772
|
+
Note:
|
|
773
|
+
``IN`` **不保证返回顺序**,需要顺序请自行按 id 重排;参数列表过大时
|
|
774
|
+
(如 PG 单语句参数上限 65535)应分批查询。
|
|
775
|
+
"""
|
|
776
|
+
statement, bound = prepare_statement(sql, params)
|
|
777
|
+
with session_scope(cls.DB_TYPE, autocommit=False) as session:
|
|
778
|
+
result = session.execute(statement, bound or {})
|
|
779
|
+
rows = result.fetchall()
|
|
780
|
+
columns = result.keys()
|
|
781
|
+
data = [dict(zip(columns, row)) for row in rows]
|
|
782
|
+
logger.info(f"🔍 执行查询 → 返回 {len(data)} 行")
|
|
783
|
+
return data
|
|
784
|
+
|
|
785
|
+
@classmethod
|
|
786
|
+
def execute(
|
|
787
|
+
cls,
|
|
788
|
+
sql: str | TextClause,
|
|
789
|
+
params: FieldData | builtins.list[FieldData] | None = None,
|
|
790
|
+
) -> int:
|
|
791
|
+
"""执行原生更新 SQL(INSERT/UPDATE/DELETE),支持批量(executemany)
|
|
792
|
+
|
|
793
|
+
Args:
|
|
794
|
+
sql: SQL 语句(使用命名参数 ``:param``);也接受已构造好的
|
|
795
|
+
:class:`~sqlalchemy.TextClause`(如 ``build_raw_*`` 的返回值)
|
|
796
|
+
params: 两种形态:
|
|
797
|
+
|
|
798
|
+
- **None / 单个参数字典**:执行一次;值为 ``list`` / ``tuple`` /
|
|
799
|
+
``set`` / ``frozenset`` 的参数按 ``IN`` 展开
|
|
800
|
+
(如 ``DELETE FROM t WHERE id IN :ids``,三库通用);
|
|
801
|
+
- **参数字典的列表**:批量执行(executemany,同一语句 + N 行参数,
|
|
802
|
+
一次往返)。⚠ 与 ``IN`` 展开**互斥**(行值须为标量),
|
|
803
|
+
各行字典的**键集必须完全一致**,**空列表**不触库直接返回 0。
|
|
804
|
+
|
|
805
|
+
Returns:
|
|
806
|
+
受影响的行数(批量形态为各行累加;部分驱动对 executemany 不上报
|
|
807
|
+
精确行数时可能为 ``-1``,请以数据为准)
|
|
808
|
+
|
|
809
|
+
Raises:
|
|
810
|
+
ValueError: 批量形态的行参数键集不一致,或行值中含序列类型
|
|
811
|
+
(批量与 ``IN`` 展开互斥)
|
|
812
|
+
"""
|
|
813
|
+
if isinstance(params, builtins.list):
|
|
814
|
+
if not isinstance(sql, str):
|
|
815
|
+
raise ValueError("批量执行(executemany)要求传入 SQL 文本")
|
|
816
|
+
return cls._execute_batch(sql, params)
|
|
817
|
+
if isinstance(sql, TextClause):
|
|
818
|
+
statement, bound = sql, params
|
|
819
|
+
else:
|
|
820
|
+
statement, bound = prepare_statement(sql, params)
|
|
821
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
822
|
+
result = session.execute(statement, bound or {})
|
|
823
|
+
affected = getattr(result, "rowcount", 0) or 0
|
|
824
|
+
logger.info(f"✅ 执行更新 → 影响 {affected} 行")
|
|
825
|
+
return affected
|
|
826
|
+
|
|
827
|
+
@classmethod
|
|
828
|
+
def _execute_batch(cls, sql: str, rows: builtins.list[FieldData]) -> int:
|
|
829
|
+
"""批量执行(executemany):先本地预校验,再一次往返执行 N 行参数
|
|
830
|
+
|
|
831
|
+
私有方法(不属于公共面):仅 ``execute`` 的列表形态会进入。
|
|
832
|
+
|
|
833
|
+
Args:
|
|
834
|
+
sql: SQL 语句(使用命名参数 ``:param``;**不传** ``params`` 构造语句,
|
|
835
|
+
即不做 ``IN`` 展开——批量与展开参数互斥)
|
|
836
|
+
rows: 参数字典列表(非空;键集一致;值须为标量)
|
|
837
|
+
|
|
838
|
+
Returns:
|
|
839
|
+
受影响的行数(各行累加;驱动不上报时为 ``-1``)
|
|
840
|
+
"""
|
|
841
|
+
if not rows:
|
|
842
|
+
# 空列表语义:不触库、不报错,直接返回 0(DBAPI 对 executemany
|
|
843
|
+
# 传空列表会报 "A value is required for bind parameter")
|
|
844
|
+
logger.info("批量执行收到空参数列表 → 不执行任何语句")
|
|
845
|
+
return 0
|
|
846
|
+
_validate_batch_rows(rows)
|
|
847
|
+
statement, _ = prepare_statement(sql)
|
|
848
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
849
|
+
result = session.execute(statement, rows)
|
|
850
|
+
affected = getattr(result, "rowcount", 0) or 0
|
|
851
|
+
logger.info(f"✅ 批量执行 → {len(rows)} 行参数,影响 {affected} 行")
|
|
852
|
+
return affected
|
|
853
|
+
|
|
854
|
+
# ==================== 原生表操作 ====================
|
|
855
|
+
|
|
856
|
+
@classmethod
|
|
857
|
+
def create_raw_table(
|
|
858
|
+
cls, table_name: str, columns: dict[str, str], if_not_exists: bool = True
|
|
859
|
+
) -> None:
|
|
860
|
+
"""根据「列名 → 列定义」字典创建普通表
|
|
861
|
+
|
|
862
|
+
Args:
|
|
863
|
+
table_name: 表名
|
|
864
|
+
columns: 列定义字典,如 {"id": "BIGSERIAL PRIMARY KEY", "name": "TEXT"}
|
|
865
|
+
if_not_exists: 是否附加 IF NOT EXISTS(默认 True)
|
|
866
|
+
|
|
867
|
+
⚠ 列定义须按**目标数据库方言**书写,本方法只做字符串拼接与执行,
|
|
868
|
+
不做方言翻译:
|
|
869
|
+
PostgreSQL: {"id": "BIGSERIAL PRIMARY KEY", "name": "TEXT"}
|
|
870
|
+
MySQL: {"id": "INT AUTO_INCREMENT PRIMARY KEY", "name": "VARCHAR(100)"}
|
|
871
|
+
SQLite: {"id": "INTEGER PRIMARY KEY", "name": "TEXT"}
|
|
872
|
+
"""
|
|
873
|
+
column_defs = ", ".join(
|
|
874
|
+
f"{name} {definition}" for name, definition in columns.items()
|
|
875
|
+
)
|
|
876
|
+
if_not_exists_sql = "IF NOT EXISTS " if if_not_exists else ""
|
|
877
|
+
sql = f"CREATE TABLE {if_not_exists_sql}{table_name} ({column_defs})"
|
|
878
|
+
with get_engine(cls.DB_TYPE).connect() as conn:
|
|
879
|
+
conn.execute(text(sql))
|
|
880
|
+
conn.commit()
|
|
881
|
+
logger.info(f"✅ 创建表 {table_name}")
|
|
882
|
+
|
|
883
|
+
@classmethod
|
|
884
|
+
def build_raw_insert(
|
|
885
|
+
cls,
|
|
886
|
+
table_name: str,
|
|
887
|
+
data: dict[str, object],
|
|
888
|
+
*,
|
|
889
|
+
ignore_conflict: bool = False,
|
|
890
|
+
) -> tuple[TextClause, dict[str, object]]:
|
|
891
|
+
"""构造 INSERT 语句(**只拼装、不执行、不管事务**)
|
|
892
|
+
|
|
893
|
+
Args:
|
|
894
|
+
table_name: 表名(仅接受合法标识符)
|
|
895
|
+
data: 列名 → 值 字典(``dict`` / 序列值会按目标列类型编码为 JSON 文本)
|
|
896
|
+
ignore_conflict: True 时忽略唯一冲突——PG / SQLite 生成
|
|
897
|
+
``ON CONFLICT DO NOTHING``,MySQL 生成 ``INSERT IGNORE``。
|
|
898
|
+
⚠ MySQL 的 IGNORE 忽略范围更宽(含数据截断告警),三库不严格等价。
|
|
899
|
+
|
|
900
|
+
Returns:
|
|
901
|
+
``(语句, 参数)``,供自有事务内执行:``session.execute(*build_raw_insert(...))``
|
|
902
|
+
|
|
903
|
+
Raises:
|
|
904
|
+
ValueError: 表名/列名非法、``data`` 为空、序列值但目标列不是 JSON 类型
|
|
905
|
+
|
|
906
|
+
Note:
|
|
907
|
+
启用审计填充时自动补齐缺失的审计字段(未启用时行为与旧版一致)。
|
|
908
|
+
"""
|
|
909
|
+
_check_identifier(table_name)
|
|
910
|
+
for name in data:
|
|
911
|
+
_check_identifier(name)
|
|
912
|
+
|
|
913
|
+
payload = dict(data) # 副本:不污染调用方 dict
|
|
914
|
+
fill_insert_for(cls.DB_TYPE, table_name, payload)
|
|
915
|
+
_adapt_write_values(cls.DB_TYPE, table_name, payload)
|
|
916
|
+
if not payload:
|
|
917
|
+
raise ValueError("build_raw_insert 的 data 不能为空")
|
|
918
|
+
|
|
919
|
+
columns = ", ".join(payload.keys())
|
|
920
|
+
placeholders = ", ".join(f":{name}" for name in payload)
|
|
921
|
+
if ignore_conflict and cls.DB_TYPE == MYSQL:
|
|
922
|
+
sql = f"INSERT IGNORE INTO {table_name} ({columns}) VALUES ({placeholders})"
|
|
923
|
+
else:
|
|
924
|
+
sql = f"INSERT INTO {table_name} ({columns}) VALUES ({placeholders})"
|
|
925
|
+
if ignore_conflict:
|
|
926
|
+
sql = f"{sql} ON CONFLICT DO NOTHING"
|
|
927
|
+
|
|
928
|
+
stmt, bound = prepare_statement(sql, payload)
|
|
929
|
+
return stmt, cast(dict[str, object], bound)
|
|
930
|
+
|
|
931
|
+
@classmethod
|
|
932
|
+
def build_raw_update(
|
|
933
|
+
cls,
|
|
934
|
+
table_name: str,
|
|
935
|
+
data: dict[str, object],
|
|
936
|
+
where: str,
|
|
937
|
+
params: dict[str, object] | None = None,
|
|
938
|
+
) -> tuple[TextClause, dict[str, object]]:
|
|
939
|
+
"""构造 UPDATE 语句(**只拼装、不执行、不管事务**)
|
|
940
|
+
|
|
941
|
+
Args:
|
|
942
|
+
table_name: 表名(仅接受合法标识符)
|
|
943
|
+
data: 列名 → 新值(业务字段;``updated_*`` 由填充器补)
|
|
944
|
+
where: WHERE 子句(不含 ``WHERE`` 关键字)
|
|
945
|
+
params: where 的绑定参数(键名不得与 ``data`` 重复;值为序列时按 ``IN`` 展开)
|
|
946
|
+
|
|
947
|
+
Returns:
|
|
948
|
+
``(语句, 参数)``:``session.execute(*build_raw_update(...))``
|
|
949
|
+
|
|
950
|
+
Raises:
|
|
951
|
+
ValueError: ``data`` 为空 / ``where`` 为空 / 标识符非法 / 绑定名冲突
|
|
952
|
+
|
|
953
|
+
Note:
|
|
954
|
+
只刷新审计字段请用 :meth:`build_raw_touch`。
|
|
955
|
+
"""
|
|
956
|
+
if not data:
|
|
957
|
+
raise ValueError(
|
|
958
|
+
"build_raw_update 的 data 不能为空;如需只刷新审计字段请用 raw_touch()"
|
|
959
|
+
)
|
|
960
|
+
if not where or not where.strip():
|
|
961
|
+
raise ValueError("build_raw_update 必须提供非空 where 子句")
|
|
962
|
+
_check_identifier(table_name)
|
|
963
|
+
for name in data:
|
|
964
|
+
_check_identifier(name)
|
|
965
|
+
|
|
966
|
+
payload = dict(data) # 副本:不污染调用方 dict
|
|
967
|
+
fill_update_for(cls.DB_TYPE, table_name, payload)
|
|
968
|
+
_adapt_write_values(cls.DB_TYPE, table_name, payload)
|
|
969
|
+
assignments = ", ".join(f"{name} = :{name}" for name in payload)
|
|
970
|
+
|
|
971
|
+
bound = dict(params or {})
|
|
972
|
+
conflict = set(payload) & set(bound)
|
|
973
|
+
if conflict:
|
|
974
|
+
raise ValueError(
|
|
975
|
+
f"data 与 params 的绑定名冲突: {sorted(conflict)};请改用其它参数名"
|
|
976
|
+
)
|
|
977
|
+
bound.update(payload)
|
|
978
|
+
sql = f"UPDATE {table_name} SET {assignments} WHERE {where}"
|
|
979
|
+
stmt, prepared = prepare_statement(sql, bound)
|
|
980
|
+
return stmt, cast(dict[str, object], prepared)
|
|
981
|
+
|
|
982
|
+
@classmethod
|
|
983
|
+
def build_raw_touch(
|
|
984
|
+
cls, table_name: str, where: str, params: dict[str, object] | None = None
|
|
985
|
+
) -> tuple[TextClause, dict[str, object]]:
|
|
986
|
+
"""构造「只刷新更新时间 / 更新人」的 UPDATE(**只拼装、不执行**)
|
|
987
|
+
|
|
988
|
+
Args:
|
|
989
|
+
table_name: 表名(仅接受合法标识符)
|
|
990
|
+
where: WHERE 子句(不含 ``WHERE`` 关键字)
|
|
991
|
+
params: where 的绑定参数
|
|
992
|
+
|
|
993
|
+
Returns:
|
|
994
|
+
``(语句, 参数)``
|
|
995
|
+
|
|
996
|
+
Raises:
|
|
997
|
+
DBError: 审计填充未启用,或表没有任何 ``updated_at`` 相关列
|
|
998
|
+
ValueError: ``where`` 为空 / 标识符非法 / 绑定名冲突
|
|
999
|
+
|
|
1000
|
+
Note:
|
|
1001
|
+
SET 列取 ``updated_at`` 槽位候选(含内置别名 ``update_time``)与表列的交集;
|
|
1002
|
+
两套列同时存在时都写。值来自 ``AuditConfig`` 的时钟与用户钩子。
|
|
1003
|
+
"""
|
|
1004
|
+
if not where or not where.strip():
|
|
1005
|
+
raise ValueError("build_raw_touch 必须提供非空 where 子句")
|
|
1006
|
+
_check_identifier(table_name)
|
|
1007
|
+
if not AuditConfig.is_enabled():
|
|
1008
|
+
raise DBError(
|
|
1009
|
+
"build_raw_touch 需要审计填充:请先 AuditConfig.enable(...),"
|
|
1010
|
+
"或改用 raw_update 显式给字段"
|
|
1011
|
+
)
|
|
1012
|
+
if not touch_columns(cls.DB_TYPE, table_name):
|
|
1013
|
+
expected = " / ".join(candidate_columns(UPDATED_AT))
|
|
1014
|
+
raise DBError(
|
|
1015
|
+
f"表 {table_name} 没有 {expected} 中的任何一列,无法 touch;"
|
|
1016
|
+
f"请改用 raw_update 显式给字段"
|
|
1017
|
+
)
|
|
1018
|
+
|
|
1019
|
+
payload: dict[str, object] = {}
|
|
1020
|
+
fill_update(payload, table_columns(cls.DB_TYPE, table_name))
|
|
1021
|
+
assignments = ", ".join(f"{name} = :{name}" for name in payload)
|
|
1022
|
+
|
|
1023
|
+
bound = dict(params or {})
|
|
1024
|
+
conflict = set(payload) & set(bound)
|
|
1025
|
+
if conflict:
|
|
1026
|
+
raise ValueError(
|
|
1027
|
+
f"touch 字段与 params 的绑定名冲突: {sorted(conflict)};"
|
|
1028
|
+
f"请改用其它参数名"
|
|
1029
|
+
)
|
|
1030
|
+
bound.update(payload)
|
|
1031
|
+
sql = f"UPDATE {table_name} SET {assignments} WHERE {where}"
|
|
1032
|
+
stmt, prepared = prepare_statement(sql, bound)
|
|
1033
|
+
return stmt, cast(dict[str, object], prepared)
|
|
1034
|
+
|
|
1035
|
+
@classmethod
|
|
1036
|
+
def build_raw_delete(
|
|
1037
|
+
cls, table_name: str, where: str, params: dict[str, object] | None = None
|
|
1038
|
+
) -> tuple[TextClause, dict[str, object]]:
|
|
1039
|
+
"""构造 DELETE 语句(**只拼装、不执行、不管事务**)
|
|
1040
|
+
|
|
1041
|
+
Args:
|
|
1042
|
+
table_name: 表名(仅接受合法标识符)
|
|
1043
|
+
where: WHERE 子句(不含 ``WHERE`` 关键字;**必须非空**)
|
|
1044
|
+
params: where 的绑定参数
|
|
1045
|
+
|
|
1046
|
+
Returns:
|
|
1047
|
+
``(语句, 参数)``
|
|
1048
|
+
|
|
1049
|
+
Raises:
|
|
1050
|
+
ValueError: ``where`` 为空 / 表名非法
|
|
1051
|
+
|
|
1052
|
+
Note:
|
|
1053
|
+
复杂关联删除(``DELETE ... USING``、级联多表)请用 ``execute()`` 或
|
|
1054
|
+
``transaction()`` 内的 ``session.execute`` 手写。
|
|
1055
|
+
"""
|
|
1056
|
+
if not where or not where.strip():
|
|
1057
|
+
raise ValueError("build_raw_delete 必须提供非空 where 子句")
|
|
1058
|
+
_check_identifier(table_name)
|
|
1059
|
+
stmt, bound = prepare_statement(
|
|
1060
|
+
f"DELETE FROM {table_name} WHERE {where}", params
|
|
1061
|
+
)
|
|
1062
|
+
return stmt, cast(dict[str, object], bound or {})
|
|
1063
|
+
|
|
1064
|
+
@classmethod
|
|
1065
|
+
def raw_insert(
|
|
1066
|
+
cls, table_name: str, data: dict[str, object], *, ignore_conflict: bool = False
|
|
1067
|
+
) -> int:
|
|
1068
|
+
"""向指定表插入一行数据(键为列名)
|
|
1069
|
+
|
|
1070
|
+
Args:
|
|
1071
|
+
table_name: 表名(仅接受合法标识符)
|
|
1072
|
+
data: 列名 → 值 字典
|
|
1073
|
+
ignore_conflict: True 时忽略唯一冲突(PG / SQLite ``ON CONFLICT DO NOTHING``、
|
|
1074
|
+
MySQL ``INSERT IGNORE``;后者忽略范围更宽)
|
|
1075
|
+
|
|
1076
|
+
Returns:
|
|
1077
|
+
受影响的行数(冲突被忽略时为 0)
|
|
1078
|
+
|
|
1079
|
+
Note:
|
|
1080
|
+
- 调用 ``AuditConfig.enable()`` 后自动补齐缺失的审计字段;
|
|
1081
|
+
- 事务内使用请改用 :meth:`build_raw_insert`。
|
|
1082
|
+
|
|
1083
|
+
Raises:
|
|
1084
|
+
ValueError: 表名/列名非法、``data`` 为空、序列值但目标列不是 JSON 类型
|
|
1085
|
+
"""
|
|
1086
|
+
return cls.execute(
|
|
1087
|
+
*cls.build_raw_insert(table_name, data, ignore_conflict=ignore_conflict)
|
|
1088
|
+
)
|
|
1089
|
+
|
|
1090
|
+
@classmethod
|
|
1091
|
+
def raw_update(
|
|
1092
|
+
cls,
|
|
1093
|
+
table_name: str,
|
|
1094
|
+
data: dict[str, object],
|
|
1095
|
+
where: str,
|
|
1096
|
+
params: dict[str, object] | None = None,
|
|
1097
|
+
) -> int:
|
|
1098
|
+
"""按 where 条件更新数据(自动补 updated_*,需启用自动填充)
|
|
1099
|
+
|
|
1100
|
+
Args:
|
|
1101
|
+
table_name: 表名(仅接受合法标识符)
|
|
1102
|
+
data: 列名 → 新值(业务字段;``updated_*`` 由填充器补)
|
|
1103
|
+
where: WHERE 子句(**不含** ``WHERE`` 关键字,如 ``"id = :id"``)
|
|
1104
|
+
params: where 子句的绑定参数(键名不得与 ``data`` 的键重复)
|
|
1105
|
+
|
|
1106
|
+
Returns:
|
|
1107
|
+
受影响的行数
|
|
1108
|
+
|
|
1109
|
+
Raises:
|
|
1110
|
+
ValueError: ``data`` 为空 / ``where`` 为空 / 标识符非法 /
|
|
1111
|
+
``data`` 与 ``params`` 的绑定名冲突
|
|
1112
|
+
|
|
1113
|
+
Note:
|
|
1114
|
+
- 只刷新审计字段请用 :meth:`raw_touch`;
|
|
1115
|
+
- 事务内使用请改用 :meth:`build_raw_update`;
|
|
1116
|
+
- 无 WHERE 的全表更新属危险操作,请显式用 ``execute()`` 书写;
|
|
1117
|
+
- 未启用自动填充时,``data`` 原样写入(不加 ``updated_*``)。
|
|
1118
|
+
|
|
1119
|
+
用法::
|
|
1120
|
+
|
|
1121
|
+
PgKit.raw_update(
|
|
1122
|
+
"writing_project",
|
|
1123
|
+
{"title": "新标题"},
|
|
1124
|
+
"id = :id AND created_by = :owner",
|
|
1125
|
+
{"id": 123, "owner": "admin"},
|
|
1126
|
+
)
|
|
1127
|
+
"""
|
|
1128
|
+
return cls.execute(*cls.build_raw_update(table_name, data, where, params))
|
|
1129
|
+
|
|
1130
|
+
@classmethod
|
|
1131
|
+
def raw_touch(
|
|
1132
|
+
cls, table_name: str, where: str, params: dict[str, object] | None = None
|
|
1133
|
+
) -> int:
|
|
1134
|
+
"""只刷新更新时间 / 更新人(需先启用审计填充)
|
|
1135
|
+
|
|
1136
|
+
Args:
|
|
1137
|
+
table_name: 表名(仅接受合法标识符)
|
|
1138
|
+
where: WHERE 子句(不含 ``WHERE`` 关键字)
|
|
1139
|
+
params: where 的绑定参数
|
|
1140
|
+
|
|
1141
|
+
Returns:
|
|
1142
|
+
受影响的行数
|
|
1143
|
+
|
|
1144
|
+
Raises:
|
|
1145
|
+
DBError: 审计填充未启用,或表没有任何 ``updated_at`` 相关列
|
|
1146
|
+
ValueError: ``where`` 为空 / 标识符非法 / 绑定名冲突
|
|
1147
|
+
|
|
1148
|
+
Note:
|
|
1149
|
+
事务内使用请改用 :meth:`build_raw_touch`。
|
|
1150
|
+
|
|
1151
|
+
用法::
|
|
1152
|
+
|
|
1153
|
+
PgKit.raw_touch("chat_session", "id = :id", {"id": 1})
|
|
1154
|
+
"""
|
|
1155
|
+
return cls.execute(*cls.build_raw_touch(table_name, where, params))
|
|
1156
|
+
|
|
1157
|
+
@classmethod
|
|
1158
|
+
def raw_delete(
|
|
1159
|
+
cls, table_name: str, where: str, params: dict[str, object] | None = None
|
|
1160
|
+
) -> int:
|
|
1161
|
+
"""按 where 条件删除数据
|
|
1162
|
+
|
|
1163
|
+
Args:
|
|
1164
|
+
table_name: 表名(仅接受合法标识符)
|
|
1165
|
+
where: WHERE 子句(不含 ``WHERE`` 关键字;**必须非空**)
|
|
1166
|
+
params: where 的绑定参数
|
|
1167
|
+
|
|
1168
|
+
Returns:
|
|
1169
|
+
受影响的行数
|
|
1170
|
+
|
|
1171
|
+
Raises:
|
|
1172
|
+
ValueError: ``where`` 为空 / 表名非法
|
|
1173
|
+
|
|
1174
|
+
Note:
|
|
1175
|
+
事务内使用请改用 :meth:`build_raw_delete`;复杂关联删除
|
|
1176
|
+
(``DELETE ... USING``、级联多表)保留手写。
|
|
1177
|
+
"""
|
|
1178
|
+
return cls.execute(*cls.build_raw_delete(table_name, where, params))
|
|
1179
|
+
|
|
1180
|
+
@classmethod
|
|
1181
|
+
def raw_get_by(
|
|
1182
|
+
cls, table_name: str, column: str, value: object
|
|
1183
|
+
) -> dict[str, object] | None:
|
|
1184
|
+
"""按单列等值查询一行
|
|
1185
|
+
|
|
1186
|
+
Args:
|
|
1187
|
+
table_name: 表名
|
|
1188
|
+
column: 列名
|
|
1189
|
+
value: 查询值
|
|
1190
|
+
|
|
1191
|
+
Returns:
|
|
1192
|
+
匹配的第一行(字典);无匹配返回 None
|
|
1193
|
+
|
|
1194
|
+
Note:
|
|
1195
|
+
开启软删除查询过滤(`AuditConfig.set_soft_delete_filter(True)`)后,
|
|
1196
|
+
若表存在 deleted 列,会自动追加 ``deleted = 正常值`` 条件;
|
|
1197
|
+
需读取已删除行时用 ``with AuditConfig.include_deleted():`` 包裹。
|
|
1198
|
+
"""
|
|
1199
|
+
where = f"{column} = :value"
|
|
1200
|
+
params: dict[str, object] = {"value": value}
|
|
1201
|
+
predicate = deleted_predicate(cls.DB_TYPE, table_name)
|
|
1202
|
+
if predicate is not None:
|
|
1203
|
+
fragment, extra = predicate
|
|
1204
|
+
where = f"{where} AND {fragment}"
|
|
1205
|
+
params.update(extra)
|
|
1206
|
+
|
|
1207
|
+
rows = cls.query(
|
|
1208
|
+
f"SELECT * FROM {table_name} WHERE {where} LIMIT 1", params
|
|
1209
|
+
)
|
|
1210
|
+
return rows[0] if rows else None
|
|
1211
|
+
|
|
1212
|
+
# ==================== 事务管理 ====================
|
|
1213
|
+
|
|
1214
|
+
@classmethod
|
|
1215
|
+
@contextmanager
|
|
1216
|
+
def transaction(cls) -> Generator[Session, None, None]:
|
|
1217
|
+
"""事务上下文管理器
|
|
1218
|
+
|
|
1219
|
+
正常退出时自动提交,异常时自动回滚。
|
|
1220
|
+
适用于多个操作需要原子性的场景。
|
|
1221
|
+
|
|
1222
|
+
Yields:
|
|
1223
|
+
SQLModel Session 实例
|
|
1224
|
+
|
|
1225
|
+
用法::
|
|
1226
|
+
|
|
1227
|
+
with PgKit.transaction() as session:
|
|
1228
|
+
crud = CRUDBase(UserModel)
|
|
1229
|
+
user = crud.create(session, {"name": "test"})
|
|
1230
|
+
"""
|
|
1231
|
+
with session_scope(cls.DB_TYPE) as session:
|
|
1232
|
+
yield session
|
|
1233
|
+
|
|
1234
|
+
# ==================== 表操作 ====================
|
|
1235
|
+
|
|
1236
|
+
@classmethod
|
|
1237
|
+
def list_tables(cls) -> builtins.list[str]:
|
|
1238
|
+
"""列出数据库中的所有表"""
|
|
1239
|
+
return list_tables(cls.DB_TYPE)
|
|
1240
|
+
|
|
1241
|
+
@classmethod
|
|
1242
|
+
def table_exists(cls, table_name: str) -> bool:
|
|
1243
|
+
"""检查表是否存在"""
|
|
1244
|
+
return table_exists(table_name, cls.DB_TYPE)
|
|
1245
|
+
|
|
1246
|
+
@classmethod
|
|
1247
|
+
def create_tables(cls, models: builtins.list[type[SQLModel]]) -> None:
|
|
1248
|
+
"""创建数据库表
|
|
1249
|
+
|
|
1250
|
+
Args:
|
|
1251
|
+
models: 需要创建表的 SQLModel 模型类列表
|
|
1252
|
+
"""
|
|
1253
|
+
create_tables(models, cls.DB_TYPE)
|
|
1254
|
+
|
|
1255
|
+
@classmethod
|
|
1256
|
+
@abstractmethod
|
|
1257
|
+
def get_table_info(cls, table_name: str) -> builtins.list[dict[str, object]]:
|
|
1258
|
+
"""获取表的列信息
|
|
1259
|
+
|
|
1260
|
+
Args:
|
|
1261
|
+
table_name: 表名
|
|
1262
|
+
|
|
1263
|
+
Returns:
|
|
1264
|
+
列信息字典列表(column_name, data_type, is_nullable 等)
|
|
1265
|
+
"""
|