SQL 查询构建器
Tip
Когда нужно читать эту статью: при необходимости цепочечного SQL-запроса или при использовании пользовательского хранилища. Если не нужно, пропустите, это не повлияет на использование других функций.
Модуль Storage в ErisPulse предоставляет универсальный SQL-построитель запросов с цепочечным вызовом, поддерживающий создание, запрос, обновление и удаление пользовательских таблиц.
Архитектура
Bases/storage.py Core/storage.py
┌─────────────────────┐ ┌──────────────────────────┐
│ BaseStorage (ABC) │◄────────────│ StorageManager │
│ BaseQueryBuilder │ │ (backend dispatch: │
│ (ABC) │ │ sqlite/mysql/postgres) │
└─────────────────────┘ │ SQLiteQueryBuilder │
│ AlterTableBuilder │
└──────────────────────────┘
BaseStorage/BaseQueryBuilder— абстрактные базовые классы, определяющие единый интерфейс; встроенные реализации SQLite / MySQL / PostgreSQL (возможно расширение пользовательских бэкендов по этому шаблону, см. Хранилище)StorageManagerпо настройкеErisPulse.storage.backendвыбирает конкретный бэкенд, по умолчанию SQLite, полностью обратно совместим
Импорт
from ErisPulse import sdk
# или
from ErisPulse.Core import storage
# ABC базовые классы (для типизации или пользовательских реализаций)
from ErisPulse.Core.Bases.storage import BaseStorage, BaseQueryBuilder
Управление таблицами
Создание таблицы
sdk.storage.CreateTable("users", {
"id": "INTEGER PRIMARY KEY AUTOINCREMENT",
"name": "TEXT NOT NULL",
"age": "INTEGER DEFAULT 0",
"email": "TEXT"
})
Проверка существования таблицы
if sdk.storage.HasTable("users"):
print("Таблица users уже существует")
Удаление таблицы
sdk.storage.DropTable("users")
Изменение структуры таблицы
# Добавление столбца
sdk.storage.AlterTable("users").AddColumn("email", "TEXT").Execute()
# Переименование таблицы
sdk.storage.AlterTable("users").RenameTo("members").Execute()
# Цепочка нескольких операций
sdk.storage.AlterTable("users") \
.AddColumn("phone", "TEXT") \
.AddColumn("address", "TEXT") \
.Execute()
Цепочечный запрос
Вставка данных
# Вставка одной строки (словарь)
sdk.storage.Table("users").Insert({"name": "Alice", "age": 30}).Execute()
# Массовая вставка (список словарей)
sdk.storage.Table("users").InsertMulti([
{"name": "Bob", "age": 25},
{"name": "Charlie", "age": 35},
{"name": "Dave", "age": 40}
]).Execute()
Запрос данных
Важно:
Select()возвращаетlist[tuple](список кортежей), а не словарь. Необходимо использовать индекс для доступа к столбцам.
# Запрос всех столбцов
rows = sdk.storage.Table("users").Select().Execute()
# rows: [(1, "Alice", 30), (2, "Bob", 25), ...]
# Запрос определённых столбцов
rows = sdk.storage.Table("users").Select("name", "age").Execute()
# rows: [("Alice", 30), ("Bob", 25), ...]
# Получение значений по индексу
for row in rows:
name = row[0] # "Alice"
age = row[1] # 30
Преобразование кортежей в словари
Рекомендуется использовать ToDict() в цепочке, результат SELECT будет автоматически возвращаться в виде словаря (имя столбца → значение):
# ToDict цепочка: результат list[dict], имена столбцов получены из метаданных запроса (SELECT * также поддерживается)
rows = sdk.storage.Table("users").Select("name", "age").ToDict().Execute()
# rows: [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}, ...]
for row in rows:
print(row["name"], row["age"])
# ExecuteOne также работает
row = sdk.storage.Table("users").Select("name", "age") \
.Where("id = ?", 1) \
.ToDict() \
.ExecuteOne()
# row: {"name": "Alice", "age": 30} или None
ToDict()— это маркер цепочки (возвращает self): цепочка, где не вызванToDict(), сохраняет поведениеlist[tuple], полностью обратно совместима;copy()сохраняет этот флаг.
Ручной способ zip (эквивалентен ToDict, подходит для случаев, где нельзя изменить цепочку):
columns = ["id", "name", "age"]
rows = sdk.storage.Table("users").Select(*columns).Execute()
# Способ 1: цикл с zip
for row in rows:
record = dict(zip(columns, row))
print(record["name"], record["age"])
# Способ 2: однократное преобразование в список словарей
records = [dict(zip(columns, row)) for row in rows]
Получение одной записи
row = sdk.storage.Table("users").Select("name", "age") \
.Where("id = ?", 1) \
.ExecuteOne()
# row — кортеж или None
if row is not None:
name = row[0] # "Alice"
age = row[1] # 30
Условия фильтрации
Where(condition, *params)поддерживает передачу нескольких параметров, соответствующих нескольким знакам?.
# Одно условие (один знак ?, один параметр)
rows = sdk.storage.Table("users").Select("name") \
.Where("age > ?", 18) \
.Execute()
# Один Where с несколькими знаками `?`
rows = sdk.storage.Table("users").Select("name") \
.Where("age > ? AND age < ?", 20, 40) \
.Execute()
# Несколько вызовов Where (AND соединение)
rows = sdk.storage.Table("users").Select("name") \
.Where("age > ?", 20) \
.Where("age < ?", 40) \
.Execute()
Сортировка, пагинация
# Сортировка по возрастанию
rows = sdk.storage.Table("users").Select("name", "age") \
.OrderBy("name") \
.Execute()
# Сортировка по убыванию
rows = sdk.storage.Table("users").Select("name") \
.OrderBy("age", desc=True) \
.Execute()
# Пагинация
rows = sdk.storage.Table("users").Select("name") \
.OrderBy("id") \
.Limit(10) \
.Offset(20) \
.Execute()
Обновление данных
# Обновление по условию
sdk.storage.Table("users") \
.Update({"age": 31}) \
.Where("name = ?", "Alice") \
.Execute()
# Полное обновление
sdk.storage.Table("users") \
.Update({"status": "active"}) \
.Execute()
Удаление данных
# Удаление по условию
sdk.storage.Table("users") \
.Delete() \
.Where("name = ?", "Bob") \
.Execute()
# Полное удаление
sdk.storage.Table("users").Delete().Execute()
Подсчёт и проверка существования
# Подсчёт
count = sdk.storage.Table("users").Count()
count = sdk.storage.Table("users").Where("age > ?", 18).Count()
# Проверка существования
exists = sdk.storage.Table("users").Where("name = ?", "Alice").Exists()
Восстановление условий запроса
Используйте copy() для глубокого копирования построитель, чтобы восстановить базовые условия:
base = sdk.storage.Table("users").Where("age > ?", 20)
# Запрос с теми же условиями
rows = base.copy().Select("name").OrderBy("name").Limit(5).Execute()
# Подсчёт с теми же условиями
count = base.copy().Count()
# Проверка существования с теми же условиями
exists = base.copy().Where("name = ?", "Alice").Exists()
Сброс построителя
builder = sdk.storage.Table("users").Select("name").Where("age > ?", 18)
builder.clear()
# Перестроение запроса
builder.Select("name", "age").Where("name = ?", "Alice")
rows = builder.Execute()
Использование в транзакциях
Цепочечные операции полностью поддерживают транзакции:
# Подтверждение транзакции
with sdk.storage.transaction():
sdk.storage.Table("users").Insert({"name": "Eve", "age": 22}).Execute()
sdk.storage.Table("users").Update({"age": 23}).Where("name = ?", "Eve").Execute()
# Пример отката
try:
with sdk.storage.transaction():
sdk.storage.Table("users").Delete().Where("name = ?", "Alice").Execute()
raise Exception("force rollback")
except Exception:
pass
# Запись Alice всё ещё существует
Асинхронный API
Начиная с версии 2.8.0, хранилище использует асинхронный API как основной интерфейс, все методы имеют соответствующие асинхронные версии с префиксом a, рекомендуется использовать в асинхронных обработчиках (чтобы избежать кратковременного блокирования цикла событий):
# Асинхронная транзакция
async with sdk.storage.atransaction():
await sdk.storage.aset("key1", "value1")
await sdk.storage.aset("key2", {"nested": True})
# Асинхронный цепочечный запрос
rows = await sdk.storage.Table("users").Select("name", "age").ToDict().aExecute()
row = await sdk.storage.Table("users").Select("*").Where("id = ?", 1).aExecuteOne()
total = await sdk.storage.Table("users").Where("age > ?", 18).aCount()
exists = await sdk.storage.Table("users").Where("name = ?", "Alice").aExists()
# Асинхронный KV
await sdk.storage.aset("app.name", "MyApp")
value = await sdk.storage.aget("app.name")
keys = await sdk.storage.aget_all_keys()
| Синхронный (совместимый) | Асинхронный |
|---|---|
get / set / delete |
aget / aset / adelete |
get_all_keys / clear |
aget_all_keys / aclear |
get_multi / set_multi / delete_multi |
aget_multi / aset_multi / adelete_multi |
transaction() |
atransaction() |
CreateTable / DropTable / HasTable |
aCreateTable / aDropTable / aHasTable |
Execute / ExecuteOne / Count / Exists |
aExecute / aExecuteOne / aCount / aExists |
Описание возвращаемых значений
| Операция | Тип возвращаемого значения | Описание |
|---|---|---|
Select().Execute() |
list[tuple] |
Список кортежей, упорядоченных по столбцам |
Select().ExecuteOne() |
tuple | None |
Одна строка как кортеж или None |
Insert().Execute() |
int |
Количество затронутых строк |
InsertMulti().Execute() |
int |
Количество вставленных строк |
Update().Execute() |
int |
Количество затронутых строк |
Delete().Execute() |
int |
Количество удалённых строк |
Count() |
int |
Количество соответствующих строк |
Exists() |
bool |
Существует ли запись |
Примеры обработки возвращаемых значений
# Select возвращает кортежи, значения по индексу
rows = sdk.storage.Table("users").Select("name", "age").Execute()
first_name = rows[0][0] # Первый столбец первой строки name
first_age = rows[0][1] # Второй столбец первой строки age
# Рекомендуется: использовать список имён столбцов и zip для преобразования в словарь, код более читаем
cols = ["name", "age"]
rows = sdk.storage.Table("users").Select(*cols).Execute()
for row in rows:
d = dict(zip(cols, row))
print(d["name"], d["age"])
# ExecuteOne возвращает одну строку как кортеж или None
row = sdk.storage.Table("users").Select("name").Where("id = ?", 1).ExecuteOne()
name = row[0] if row else None
# Insert/Update/Delete возвращают количество затронутых строк
affected = sdk.storage.Table("users").Delete().Where("age < ?", 18).Execute()
print(f"Удалено {affected} записей")
Параметризованный запрос
Все параметры WHERE используют знак ? как плейсхолдер, параметры передаются как последующие аргументы в Where() (а не как кортеж или список):
# Правильно ✓ — несколько параметров передаются по отдельности
sdk.storage.Table("users").Where("age > ? AND name = ?", 18, "Alice").Execute()
# Правильно ✓ — несколько вызовов Where
sdk.storage.Table("users").Where("age > ?", 18).Where("name = ?", "Alice").Execute()
# Неправильно ✗ — не передавайте кортеж
sdk.storage.Table("users").Where("age > ? AND name = ?", (18, "Alice")).Execute()
# Это приведёт к передаче всего кортежа как значения первого плейсхолдера
# Неправильно ✗ — существует риск SQL-инъекции
sdk.storage.Table("users").Where(f"name = '{user_input}'").Execute()
Правила передачи параметров Where
# Where(condition: str, *params: Any)
# params — переменное количество аргументов, передаются по отдельности
# Один параметр
.Where("name = ?", "Alice")
# Несколько параметров
.Where("age > ? AND age < ?", 18, 60)
# Запрос LIKE
.Where("name LIKE ?", "A%")
# Запрос IN (необходимо вручную составить плейсхолдеры)
.Where("name IN (?, ?, ?)", "Alice", "Bob", "Charlie")
Пользовательский хранилище
Начиная с версии 2.8.0, абстрактный уровень использует асинхронные методы как основной контракт: наследуйте BaseStorage и реализуйте асинхронные абстрактные методы, синхронные get/set/Execute и т.д. предоставляются автоматически базовым классом:
from ErisPulse.Core.Bases.storage import BaseStorage, BaseQueryBuilder
class MyQueryBuilder(BaseQueryBuilder):
async def aExecute(self):
# Реализация конкретной логики выполнения
...
async def aExecuteOne(self):
...
async def aCount(self):
...
async def aExists(self):
...
class MyStorage(BaseStorage):
async def aget(self, key, default=None):
...
async def aset(self, key, value):
...
# Реализация других асинхронных абстрактных методов и hook транзакций ...
def Table(self, table_name):
return MyQueryBuilder(self, table_name)
Tip
Если не хотите реализовывать маршрутизацию транзакций (ключевой параметр conn), оставьте атрибут класса _SUPPORTS_CONN_ROUTING = False (по умолчанию), функционал транзакций всё ещё доступен (ограничена изоляция). Для чисто SQL-бэкендов можно напрямую наследовать Core/Bases/sql_base.py SQLStorageBase + SQLQueryBuilder, достаточно предоставить управление соединением и диалект выполнения, подробнее см. Хранилище.
Связанные документы
- Хранилище — выбор и настройка бэкендов sqlite / mysql / postgres
- API основных модулей — полный API модуля Storage
- API базового хранилища — абстрактные интерфейсы BaseStorage/BaseQueryBuilder
- Построитель сообщений — примеры цепочечного вызова MessageBuilder