Ir al contenido

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.

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"]
ComponenteResponsabilidad
BootstrapDatabaseLee el entorno y valida la configuración tipada.
ConnectionManager / IConnectionManagerResuelve y reutiliza conexiones por nombre.
DB / IQueryBuilderSelecciona tabla, ejecuta SQL y controla transacciones sin modelos.
RawQueryBuilderConstruye planes de consulta sobre tablas.
Model / BuilderAñaden atributos, persistencia y relaciones.
SQLCompilerTraduce planes y definiciones al dialecto elegido.
Connection / IConnectionAdquiere recursos, ejecuta, materializa resultados y administra transacciones.
Schema, migrador y seedersDefinen estructuras, aplican cambios y cargan datos.

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 JSONResponse
from 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.

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.

  1. La configuración se carga y valida sin conectarse al servidor.
  2. El gestor crea y conserva Connection al resolver por primera vez su nombre.
  3. El engine se crea al necesitar E/S; construir el objeto no comprueba conectividad ni credenciales.
  4. 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.
  5. Dentro de una transacción explícita, las operaciones de su tarea propietaria reutilizan la misma conexión física.
  6. 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.

Referencia de comandos de Database: sintaxis, argumentos y opciones para migraciones de aplicación, almacenamiento interno, inspección y borrado.

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.