Ir al contenido

Crear esquemas y tablas

Un esquema físico describe tablas, columnas, claves e índices. Definir un modelo no crea su tabla. Schema convierte un Blueprint o TableDefinition en operaciones de la conexión; el ORM comparte esos metadatos para generar consultas. Los cambios duraderos se organizan en migraciones.

from orionis.database import Migration
from orionis.support.facades import Schema
class CreateProjects(Migration):
async def up(self) -> None:
async with Schema.create("projects") as table:
table.id()
table.string("name", 120)
table.string("slug", 160)
table.boolean("active").default(True)
table.timestamps()
table.unique("slug", name="uq_projects_slug")
table.index("active", name="ix_projects_active")
async def down(self) -> None:
await Schema.drop("projects")

Guarda la clase en un archivo de migración y ejecuta migrate desde el proyecto. create() es síncrono y devuelve TableCreation: se utiliza con async with, sin await delante de Schema.create. Las columnas se acumulan en memoria y el SQL se ejecuta al salir sin excepción. El bloque no suprime errores. timestamps() añade created_at y updated_at anulables, sin programar por sí mismo su actualización.

flowchart TD
    A[Migration.up] --> B[Schema.create]
    B --> C[Blueprint: columns and constraints]
    C --> D{Successful context exit?}
    D -->|Yes| E[TableDefinition]
    D -->|No| F[Propagate exception without creating table]
    E --> G[Selected connection]
    G --> H[SQLCompiler: types, prefix and dialect]
    H --> I[CREATE TABLE and indexes]
    I --> J[Commit migration and history]

Importa la fachada directamente desde orionis.support.facades. Para inyección utiliza ISchema, del módulo orionis.database.contracts.schema. El provider registra una implementación transitoria porque cada instancia conserva su selección de conexión. Las cinco operaciones públicas son:

connection(name: str | None=None) -> Self

Selecciona una conexión y devuelve la misma instancia. name=None selecciona explícitamente la conexión predeterminada. Solo se permite una selección por instancia; una segunda llamada lanza ValueError, incluso si repite el nombre. La fachada resuelve un servicio nuevo por acceso.

from orionis.support.facades import Schema
async def remove_reporting_table() -> bool:
schema = await Schema.connection("reporting")
return await schema.drop("old_reports")

create(name: str) -> TableCreation

Devuelve TableCreation para construir una tabla llamada name o schema.table. Nombres vacíos, schema. o con más de un punto producen ValueError cuando se procesa la definición. Un nombre no válido de factoría en Blueprint produce AttributeError.

from orionis.database import Migration
from orionis.support.facades import Schema
class CreateProjects(Migration):
async def up(self) -> None:
async with Schema.create("projects") as table:
table.id()
table.string("name", 120)
table.string("slug", 160)
table.boolean("active").default(True)
table.timestamps()
table.unique("slug", name="uq_projects_slug")
table.index("active", name="ix_projects_active")
async def down(self) -> None:
await Schema.drop("projects")

async createFromDefinition(definition: TableDefinition) -> bool

Recibe una TableDefinition reutilizable y devuelve bool después de await. Usa la conexión explícita, la contextual de migración o la predeterminada, en ese orden. Errores de tipos/DDL se propagan como QueryException o desde el compilador.

from database.schemas.projects_v1_schema import TABLE as PROJECTS_V1
from orionis.database import Migration
from orionis.support.facades import Schema
class CreateProjects(Migration):
async def up(self) -> None:
await Schema.createFromDefinition(PROJECTS_V1)
async def down(self) -> None:
await Schema.drop("projects")

async createFromModel(model: type[Model]) -> bool

Recibe una clase concreta Model, nunca instancia ni la clase base abstracta; de otro modo TypeError. Selección de conexión: explícita > conexión declarada del modelo > conexión contextual de migración > default. Devuelve bool. Utiliza los metadatos actuales: apropiado para bootstrap y testing, no para congelar historia de migraciones.

from app.models.project import Project
from orionis.support.facades import Schema
async def prepare_test_table() -> bool:
return await Schema.createFromModel(Project)

async drop(name: str) -> bool

Elimina una tabla y devuelve bool. Admite schema.table y separa schema del nombre antes de enviarlo a la conexión. La operación subyacente usa if_exists=True; no permite seleccionar ese flag desde la fachada Schema. El contenido de la tabla se elimina.

from orionis.support.facades import Schema
async def remove_projects() -> bool:
return await Schema.drop("projects")

Genera el módulo con cualquiera de los siguientes comandos. name es obligatorio; se añade el sufijo Schema al nombre normalizado del archivo si falta. catalog/projects_v1 crea database/schemas/catalog/projects_v1_schema.py. el stub declara una constante de módulo TABLE:

Ventana de terminal
orionis make:database-schema projects_v1
python -B reactor make:database-schema projects_v1
from typing import Final
from orionis.orm.schema import TableDefinition
TABLE: Final[TableDefinition | None] = None

Reemplaza None con la definición completa antes de utilizarla:

from typing import Final
from orionis.database.schema.column import Column
from orionis.orm.schema import TableDefinition
TABLE: Final[TableDefinition] = TableDefinition(
name="projects",
columns={
"id": Column.id(),
"name": Column.string("name", 120),
},
primary_key="id",
)

Guarda el ejemplo en database/schemas/projects_v1_schema.py. TableDefinition contiene el nombre lógico, columnas y restricciones. Importa TABLE con un alias descriptivo, como PROJECTS_V1, y pásala a Schema.createFromDefinition() desde la migración anterior. Un modelo también puede asignar table_definition = PROJECTS_V1. Final expresa la intención de no reasignar la constante; no ejecuta DDL ni vuelve inmutable su contenido. Congela V1: para evolucionar el esquema crea V2 y otra migración, en lugar de cambiar el significado de una migración aplicada. Los subdirectorios se crean automáticamente; un archivo existente produce FileExistsError y no hay --force. Los nombres, rutas relativas, sufijos y rechazos siguen el generador de migraciones.

Blueprint() inicia una colección vacía. Las 40 factorías de Column aparecen automáticamente como métodos del blueprint y agregan su resultado; llamar Column.string por separado no registra esa columna en un blueprint. columns() -> tuple[ColumnDefinition, …] devuelve una instantánea de columnas. definitions() -> tuple[SchemaDefinition, …] devuelve primero columnas y después restricciones, conservando el orden de cada conjunto. SchemaDefinition es la unión de ColumnDefinition, Comment, ForeignKey, Index, PrimaryKey y Unique.

from orionis.database.schema.blueprint import Blueprint
table = Blueprint()
table.id()
table.string("name", 120)
table.unique("name")
columns = table.columns()
definitions = table.definitions()

La creación mantiene una tabla ya existente mediante checkfirst=True y devuelve True; no compara columnas ni actualiza su estructura. Para necesitar una comprobación estricta, IConnection.createTable(definition, if_not_exists=False) es el nivel que expone ese flag. El prefijo de conexión se aplica a tablas y referencias estructuradas; no lo dupliques en name. Una cadena de SQL manual no recibe ese tratamiento.

El código no expone Schema.table, alter, rename, hasTable ni dropIfExists. Las alteraciones requieren SQL explícito del motor. Consulta todos los tipos, modificadores y claves y TableDefinition para completar la declaración.

Los nombres de columna repetidos lanzan ValueError antes de ejecutar DDL. Incluye colisiones con columnas de timestamps generadas. Un primaryKey() vacío también lanza ValueError. El contexto de creación rechaza entradas superpuestas y consume cada declaración satisfactoria una sola vez.

Construcción directa del servicio y contexto

Sección titulada «Construcción directa del servicio y contexto»
Schema(conn_manager: IConnectionManager)
TableCreation(schema: Schema, name: str)

El contenedor construye Schema con IConnectionManager. TableCreation es el contexto devuelto por create: aenter entrega Blueprint y aexit crea solo al no recibir excepción, devuelve False y propaga fallos. Para seleccionar una conexión desde la fachada primero espera el servicio: schema = await Schema.connection(“reporting”); después utiliza schema.create o await schema.drop. La selección es síncrona en una instancia ISchema, pero el dispatcher de la fachada se resuelve mediante await.