ORM y consultas

El ORM de Orionis combina modelos Active Record, consultas fluidas, relaciones y factories. Los modelos describen atributos y comportamiento; Database administra conexiones, compilación SQL y transacciones. El engine no forma parte de la API del modelo.

Las declaraciones y los builders son síncronos. Las operaciones que leen o escriben datos necesitan await. Antes de consultar, inicializa la aplicación y crea las tablas mediante migraciones; definir una clase no crea su tabla.

Del modelo al registro guardado

El modelo pertenece al código de tu aplicación, normalmente app/models. Sus columnas deben coincidir con una tabla existente:

1. Define el modelo y su política fillable siguiendo modelos y atributos.
2. Escribe una migración con esas columnas y ejecuta uv run python -B reactor migrate desde la raíz del proyecto. Declarar columnas en el modelo no ejecuta este paso.
3. Usa el modelo desde un controlador, comando, job o servicio async después del arranque de la aplicación. Construye una instancia con datos confiables o validados y comprueba el booleano de await instance.save().
4. Consulta con await ClaseDelModelo.where(...).get() o await ClaseDelModelo.find(id). find() puede devolver None; resuelve ese caso antes de leer atributos.

Si solo necesitas filas y agregados, las consultas de tabla con DB.table() evitan declarar un modelo. Usa consultas de modelo cuando necesites casts, eventos, relaciones o eliminación lógica.

1. Modelos, atributos y persistencia: definir una entidad, proteger entrada y guardar cambios.
2. Consultar, actualizar y paginar: modelos frente a tablas, filtros, joins, agregados y escrituras masivas.
3. Relacionar y cargar modelos: relaciones simples, eager loading y tablas pivot.
4. Eventos, scopes y soft deletes: comportamiento de dominio, políticas de consulta y eliminación lógica.
5. Factories y pruebas: datos reproducibles, estados, secuencias y persistencia controlada.
6. Tipos y restricciones del esquema: catálogo de tipos, modificadores, claves compuestas y definiciones compartidas.

Los ejemplos que solo declaran modelos o construyen planes no acceden a una base. Los ejemplos async con facades requieren bootstrap y tablas compatibles; cada capítulo explica esas condiciones. Python 3.14 o posterior es obligatorio.

El provider database instala un gestor en ConnectionResolver; consultar sin ese puente produce OrmConfigurationException. El ORM consume la configuración database, sin un archivo de configuración separado. QueryBuilderProvider registra el gateway singleton de DB; cada llamada de consulta crea su propio builder.