Уровень модели данных (ORM)
Tip
Когда читать эту статью: Когда вам нужны модели данных, автоматическое создание таблиц или сопоставление отношений. Если не нужно, пропустите, это не повлияет на использование других функций.
Note
ORM является асинхронным по умолчанию: Все методы CRUD (create / get / save / delete / create_table / операции QuerySet) являются async def, и их можно вызывать с помощью await в цикле событий — базовый драйвер — aiosqlite / aiomysql / asyncpg (в зависимости от хранилища), синхронный блокирующий код отсутствует. Синхронные get/set для хранилища ключ-значение — это совместимый слой, не имеющий отношения к ORM.
Начиная с версии 2.9.0, фреймворк включает декларативный уровень моделей данных: унаследовавшись от Model и объявив поля с помощью Field, вы получаете возможность автоматического создания таблиц и CRUD-операций. Модели строятся на базе встроенного хранилища — SQLite / MySQL / PostgreSQL определяются параметром ErisPulse.storage.backend, переключение хранилища не требует изменения кода моделей.
Декларация моделей
from ErisPulse.Core.Bases import Model, Field
class User(Model):
id: int = Field(primary_key=True, autoincrement=True)
name: str = Field(max_length=64)
age: int = Field(default=0, ge=0, le=150)
role: str = Field(default="user", choices=["user", "admin"])
tags: list = Field(default_factory=list) # JSON-столбец, автоматическая сериализация при чтении/записи
bio: str = Field(default="", description={"i18n": "user.bio", "default": "Биография"})
- Имя таблицы по умолчанию — snake_case от имени класса (
UserProfile → user_profile), можно переопределить с помощью__tablename__ = "xxx" - Параметры ограничений
Fieldидентичны параметрам декларативного класса конфигурации (choices/ge/le/max_length,descriptionподдерживает словарь i18n); движок проверки и конфигурации совпадает
Параметры поля
| Параметр | Описание |
|---|---|
default |
Значение по умолчанию (обязательно, если не указано и не автоинкремент → NOT NULL) |
default_factory |
Фабрика для изменяемых значений по умолчанию (например, list) |
primary_key |
Первичный ключ (если несколько — составной ключ, объединяется в PRIMARY KEY (a, b) на уровне таблицы) |
autoincrement |
Автоинкрементный первичный ключ (является первичным ключом, значение автоматически возвращается после create; используется только для одного столбца, исключает составной ключ) |
max_length |
Максимальная длина строки (генерирует VARCHAR(n), проверка при записи) |
nullable |
Разрешить NULL (по умолчанию False) |
index |
Создать обычный индекс |
unique |
Уникальное ограничение |
choices / ge / le |
Перечисление / диапазон значений (проверка при записи) |
description |
Описание (словарь i18n, формат аналогичен классу конфигурации) |
column_type |
Переопределить определение типа SQL-столбца |
foreign_key |
Ограничение внешнего ключа на уровне столбца (в формате "таблица.столбец", генерирует REFERENCES) |
on_delete |
Действие при удалении: CASCADE / SET NULL / RESTRICT / NO ACTION / SET DEFAULT |
auto_now_add |
Автоматически записывать текущую метку времени (в секундах с начала эпохи) при вставке |
auto_now |
Автоматически записывать текущую метку времени при вставке и при вызове save() (не срабатывает при пакетном обновлении QuerySet.update) |
Составной ключ и совместная уникальность
Несколько полей с primary_key=True образуют составной ключ, get / save / delete определяются по всем столбцам первичного ключа;
__unique_together__ объявляет группу совместной уникальности (может быть несколько групп):
class Membership(Model):
__tablename__ = "memberships"
__unique_together__ = (("user_id", "group_id"),)
user_id: int = Field(primary_key=True)
group_id: int = Field(primary_key=True)
role: str = Field(default="member")
m = await Membership.get(user_id=1, group_id=2)
autoincrementи составной ключ исключают друг друга, при совместном использовании модель не будет создана__unique_together__реализуется с помощью уникального индекса (uq_— префикс имени индекса): при создании таблицы индекс создается автоматически, для существующих таблицcreate_table()автоматически добавляет индекс, без необходимости пересоздания- Модели с составным ключом пока не поддерживают сопоставление отношений (has-many / belongs-to), при попытке доступа будет явная ошибка
Создание таблицы и CRUD
await User.create_table() #幂等(IF NOT EXISTS)
user = await User.create(name="Alice", age=20) # Вставка (автоинкрементный первичный ключ автоматически возвращается)
got = await User.get(id=user.id) # Поиск по значению
users = await User.where(User.age > 18).order_by("-age").limit(10).all()
first = await User.where(User.name == "Alice").first()
total = await User.count(User.age > 18)
user.age = 21
await user.save() # Обновление по первичному ключу (сначала проверка ограничений); если первичный ключ отсутствует, переходит в режим вставки (автоинкрементный ключ также возвращается в экземпляр)
await user.save(update_fields=["age"]) # Частичное обновление (белый список, остальные поля не записываются)
await user.delete() # Удаление по первичному ключу
user, created = await User.get_or_create({"age": 20}, name="Alice") # Если найдено — вернуть; если нет — создать
user, created = await User.update_or_create({"age": 21}, name="Alice") # Если найдено — обновить по defaults и сохранить; если нет — создать
await User.update_all(User.age > 18, role="adult") # Пакетное обновление
await User.delete_all(User.age > 100) # Пакетное удаление
Note
get_or_create / update_or_create при одновременном конкурентном доступе могут оба корутины попасть в ветку создания — уникальные ограничения (первичный ключ / unique / __unique_together__) приведут к тому, что последний получит StorageOperationError; при необходимости幂等ной семантики перехватите исключение и выполните повторный запрос.
Выражения запросов поддерживают > >= < <= == != и in_([...]), а также & (и) / | (или) для комбинации:
await User.where((User.age > 18) & User.name.in_(["Alice", "Bob"])).all()
Транзакции
ORM и хранилище фреймворка используют одну и ту же систему маршрутизации транзакций: если внутри storage.atransaction(), create / save / delete и запросы автоматически используют транзакцию, и все действия подчиняются единым commit или rollback, без независимого подтверждения.
async with storage.atransaction():
await User.create(name="Alice")
... # Если в блоке возникнет исключение, все вышеуказанные INSERT будут откатиться
Связь с декларативным классом конфигурации
Декларация модели и ConfigClass (@dataclass + field(metadata=...)) разделяют один и тот же底层 — словарь ограничений, движок проверки (validate_field_constraints), регистр типов (python_type_category); но базовые классы намеренно разделены: поля конфигурации — обычные значения (TOML-формат, однократная загрузка с горячим обновлением), поля модели — дескрипторы столбцов (доступ к классу = выражение запроса, доступ к экземпляру = значение строки). Одна и та же декларация, два разных базовых класса.
Когда использовать какой тип декларации
| Аспект | Поля конфигурации field(metadata=...) |
Поля модели Field() |
|---|---|---|
| Сценарий | Параметры модуля (малое количество, человекочитаемые, нуждаются в горячем обновлении) | Данные бизнес-объектов (много строк, программный доступ, нуждаются в запросах) |
| Формат хранения | config.toml (сохранение комментариев,往返 TOML) |
Таблицы базы данных (автоматическое создание таблиц, SQL-диалекты) |
| Формат значения | Обычные значения (прямой доступ через свойства dataclass) | Дескрипторы (доступ к классу = выражение столбца, доступ к экземпляру = значение строки) |
| Ограничения | metadata={"choices": ..., "min": ..., "max": ...} |
Field(choices=..., ge=..., le=..., max_length=...) |
| Общий底层 | Движок проверки + словарь ограничений + регистр типов (одинаковые) | Тот же |
Эмпирическое правило: "как модуль работает" — используйте класс конфигурации, "какие данные создал пользователь" — используйте модель.
Ограничения и замечания
- Хранилище определяется глобальной конфигурацией; модель может переопределить
__storage__для использования пользовательского экземпляраBaseStorage(для тестирования) - Поля
list/dict(включая параметризованные типы, напримерlist[int],dict[str, int]) хранятся в виде текста JSON, при чтении и записи автоматически сериализуются - При записи (
create/save) автоматически выполняется проверка ограничений, при ошибке выбрасываетсяValueError(локализованные сообщения) - Автоматическое миграция реализуется для сценариев добавления новых столбцов (см. ниже); изменения типа столбца и удаление столбцов требуют ручного вмешательства
- При сбое подключения к хранилищу поведение соответствует слою хранилища: фреймворк не падает, после охлаждения автоматически переподключается
Автоматическая миграция (этап 2)
create_table() при наличии таблицы автоматически сравнивает существующие столбцы с полями модели: новые поля автоматически выполняют ALTER TABLE ADD COLUMN (удаляется ограничение NOT NULL, заполняются NULL), индекс для новых полей с index=True создается одновременно. Не требуется ручной миграционный скрипт.
# После выхода v1 модели эволюционируют: добавляются поля email / bio
class User(Model):
__tablename__ = "orm_users"
id: int = Field(primary_key=True, autoincrement=True)
name: str = Field(max_length=64)
age: int = Field(default=0)
email: str = Field(default="") # Новое: при следующем create_table() автоматически добавит столбец
bio: str = Field(default="")
await User.create_table() #幂等: только миграция новых столбцов
Ограничения: Поддерживается только добавление столбцов; изменения первичного ключа, типа столбца и удаление столбцов требуют ручного вмешательства (чтобы избежать разрушительных ALTER-операций).
Внешние ключи (основа сопоставления отношений)
foreign_key="таблица.столбец" объявляет ограничение внешнего ключа на уровне столбца, DDL генерирует подфразу REFERENCES; on_delete объявляет действие при удалении (например, "CASCADE" — каскадное удаление связанных строк):
class Post(Model):
__tablename__ = "posts"
id: int = Field(primary_key=True, autoincrement=True)
author: int = Field(foreign_key="orm_users.id", on_delete="CASCADE")
content: str = Field(max_length=255)
Сопоставление отношений (relationship)
В теле класса модели объявляется relationship() в виде атрибута класса, направление определяется автоматически по месту объявления внешнего ключа:
from ErisPulse.Core.Bases import Model, Field, relationship
class User(Model):
__tablename__ = "orm_users"
id: int = Field(primary_key=True, autoincrement=True)
name: str = Field(max_length=64)
posts = relationship("Post", foreign_key="author") # Внешний ключ в другой таблице → has-many
class Post(Model):
__tablename__ = "posts"
id: int = Field(primary_key=True, autoincrement=True)
author: int = Field(foreign_key="orm_users.id")
content: str = Field(max_length=255)
writer = relationship("User", foreign_key="author") # Внешний ключ в текущей таблице → belongs-to
has-many: Атрибут экземпляра возвращает набор запросов, доступны все возможности QuerySet, create автоматически возвращает первичный ключ текущей таблицы в столбец внешнего ключа другой таблицы:
alice = await User.get(name="Alice")
posts = await alice.posts.all() # Все статьи пользователя
latest = await alice.posts.order_by("-id").first()
total = await alice.posts.count()
hot = await alice.posts.where(Post.content != "").all() # Дополнительные условия по столбцам другой таблицы
await alice.posts.delete() # Удалить только статьи пользователя
new_post = await alice.posts.create(content="hi") # author автоматически = alice.id
belongs-to: Прямой await возвращает экземпляр другой модели (если нет соответствия или внешний ключ NULL — возвращает None):
post = await Post.get(id=1)
writer = await post.writer # Экземпляр User или None
await writer.posts.count() # Двусторонняя связь
Особенности:
relatedпринимает строку с именем класса (ленивое разрешение по регистру моделей, порядок определения не имеет значения) или непосредственно модель- Запросы отношений и модели используют свои хранилища (не поддерживается JOIN между разными хранилищами — запросы отношений — это отдельные SQL-запросы)
- Запросы отношений не кэшируются, каждый вызов — это немедленный запрос; для произвольных запросов можно использовать
User.where(...)
Далее
Нужно сменить базу данных или развернуть в облаке
- Хранилище — Настройка и переключение SQLite / MySQL / PostgreSQL, код моделей не требует изменений
Не нужно структуры таблиц, только несколько ключ-значений
- Основные понятия модуля - Система хранения — Легкий способ использования хранилища ключ-значение, без объявления моделей