Bases de datos
Database administra conexiones SQL con nombre y proporciona la infraestructura de consultas, transacciones, esquemas, migraciones y seeders. Puedes ejecutar SQL, utilizar el constructor de consultas o trabajar con modelos del ORM. Las tres alternativas comparten el gestor y las transacciones.
Las operaciones de E/S se esperan con await. Elegir una conexión, construir una consulta o definir una tabla son operaciones síncronas; una operación terminal como get() o insert() sí ejecuta SQL.
Arquitectura
Sección titulada «Arquitectura»flowchart TD
A["config/database.py + .env"] --> B["ConnectionManager"]
C["DB / IQueryBuilder"] --> D["RawQueryBuilder"]
E["Model / Builder"] --> F["Query plans"]
D --> F
C -->|"SQL + bindings"| G["Connection"]
F --> H["SQLCompiler"]
H --> G
B --> G
G --> I{"Driver"}
I --> J["Async engine"]
I --> K["Redshift: Core + reserved worker"]
J --> L["Database server / SQLite"]
K --> L
L --> M["Dictionaries, affected rows, InsertResult or models"]| Componente | Responsabilidad |
|---|---|
BootstrapDatabase | Lee el entorno y valida la configuración tipada. |
ConnectionManager / IConnectionManager | Resuelve y reutiliza conexiones por nombre. |
DB / IQueryBuilder | Selecciona tabla, ejecuta SQL y controla transacciones sin modelos. |
RawQueryBuilder | Construye planes de consulta sobre tablas. |
Model / Builder | Añaden atributos, persistencia y relaciones. |
SQLCompiler | Traduce planes y definiciones al dialecto elegido. |
Connection / IConnection | Adquiere recursos, ejecuta, materializa resultados y administra transacciones. |
Schema, migrador y seeders | Definen estructuras, aplican cambios y cargan datos. |
Primera consulta desde un controlador
Sección titulada «Primera consulta desde un controlador»Configura una conexión y crea tus tablas mediante migraciones. Este ejemplo supone una tabla notes con columnas id y body. Registra el controlador mediante rutas HTTP:
from orionis.http import JSONResponsefrom orionis.support.facades import DB
class NoteController: async def index(self) -> JSONResponse: notes = await ( DB.table("notes") .select("id", "body") .orderBy("id") .limit(20) .get() ) return JSONResponse({"notes": notes.all()})Importa la fachada desde orionis.support.facades. La aplicación registra sus servicios durante el arranque. En servicios, comandos, jobs y componentes MCP asíncronos se utiliza la misma API; también puedes inyectar IQueryBuilder o IConnectionManager.
Tablas dentro de un esquema
Sección titulada «Tablas dentro de un esquema»Usa DB.table("esquema.tabla"), por ejemplo DB.table("sales.products"). Para elegir además una conexión registrada, escribe DB.connection("reporting").table("sales.products"). El esquema pertenece a la base de datos seleccionada; no es el nombre de la conexión.
El constructor de consultas explica cómo filtrar, ordenar y obtener resultados, con ejemplos de alias y nombres calificados. Para modelos, declara el esquema en una TableDefinition.
Ciclo de vida
Sección titulada «Ciclo de vida»- La configuración se carga y valida sin conectarse al servidor.
- El gestor crea y conserva
Connectional resolver por primera vez su nombre. - El engine se crea al necesitar E/S; construir el objeto no comprueba conectividad ni credenciales.
- Sin transacción explícita, cada operación adquiere una conexión física, abre una transacción temporal, consume sus resultados y confirma o revierte antes de liberarla.
- Dentro de una transacción explícita, las operaciones de su tarea propietaria reutilizan la misma conexión física.
disconnect()descarta el engine y conexiones inactivas; un uso posterior puede reconstruirlo. No lo llames por petición ni mientras otras tareas usan el servicio compartido.
Guías y referencia
Sección titulada «Guías y referencia»Referencia de comandos de Database: sintaxis, argumentos y opciones para migraciones de aplicación, almacenamiento interno, inspección y borrado.
- Drivers y dependencias: motores y
reactor packages. - Configuración: propiedades y variables de entorno.
- Gestión de conexiones: nombres, inyección y registro.
- Fachada DB: sus once métodos de entrada.
- SQL y resultados: bindings, retornos y errores.
- Constructor de consultas: consultas sin modelos.
- Transacciones: contextos, savepoints y concurrencia.
- Esquemas, migraciones y seeders.
- Dialectos y producción.
- API de conexiones y compilación.
Utiliza DB para trabajar sin instancias de modelo; su builder devuelve colecciones de diccionarios y no dispara eventos de modelos. Utiliza el ORM para estado de entidad, casts, scopes, eventos, relaciones y factories.