Skip to content

Modelos de base de datos ​

Marca una interfaz con @model("table_name") para asociarla con una tabla relacional. Exporta el modelo desde su módulo e impórtalo donde lo necesites; la importación habilita operaciones como User.findMany(filter) en el nombre de tipo del modelo.

ObjectId de MongoDB ​

Importa ObjectId desde tyrus:db para los identificadores de MongoDB. Su representación en Tyrus y JSON es una cadena hexadecimal de 24 caracteres; los campos Model declarados como ObjectId u ObjectId[] se almacenan como BSON ObjectId (o arrays de ellos), mientras que los campos normales string siguen siendo cadenas BSON. Los filtros sobre _id, un campo @id u otro campo ObjectId convierten los valores a BSON ObjectId; los filtros ObjectId[] admiten eq, ne e in. Los valores no válidos devuelven ERR_DB_INVALID_OBJECT_ID. MongoDB almacena el campo @id del Model como _id.

MongoDB genera _id cuando un documento insertado lo omite e incluye _id en los resultados de findOne y findMany. No hace falta declarar un campo @id para MongoDB; _id se sintetiza en el tipo del Model devuelto y se puede usar en filtros. Si la interfaz declara un campo lógico con @id, su tipo debe ser compatible con ObjectId; los resultados contienen ese campo y _id, ambos asignados al mismo identificador del documento.

@model habilita los campos automáticos createdAt y updatedAt de forma predeterminada. Son propiedades sintéticas del modelo de tipo Instant, así que no las declares en la interfaz ni importes Instant solo por estos campos generados. Un campo declarado explícitamente, como deletedAt: Instant?, sí requiere importar Instant desde tyrus:temporal. Usa { timestamps: false } en las opciones de @model para desactivar los timestamps automáticos. { snakeCase: true } cambia solo los nombres físicos de las columnas de esos timestamps a created_at y updated_at; no renombra la tabla ni los demás campos. Usa @column("physical_name") para asignar nombres físicos a campos comunes. Como snakeCase solo transforma las columnas de timestamps automáticos, combinarlo con { timestamps: false } es inválido. Las inserciones ORM inicializan ambos campos y las actualizaciones ORM establecen updatedAt en la misma mutación. MongoDB almacena estos valores como BSON Date; SQLite los almacena como texto UTC, PostgreSQL como TIMESTAMPTZ y MySQL como DATETIME(3). Los valores con precisión inferior a microsegundos en PostgreSQL o milisegundos en MySQL se rechazan en vez de redondearse. SQL directo y las escrituras de otros clientes no reciben el comportamiento de timestamps del ORM.

tyrus
// The default PostgreSQL identity ID is added to the Model automatically.
import { Instant } from "tyrus:temporal";

@model("users")
export interface User {
    @email()
    @unique
    email: string;

    @default("Anonymous")
    displayName: string;

    @column("team_id")
    @foreignKey("teams", "id")
    teamId: i64?;

    deletedAt: Instant?;
}

Generación de IDs ​

El backend de database.backend selecciona la estrategia predeterminada. SQLite y MongoDB no necesitan un campo de ID en el Model. MySQL usa auto_increment de forma predeterminada y PostgreSQL usa identity; estos valores predeterminados tampoco requieren declarar un campo de ID. Tyrus agrega el ID generado a los resultados de lectura del Model. Declara id con @id solo para elegir una estrategia MySQL o PostgreSQL no predeterminada.

For SQLite, MongoDB, and the default MySQL and PostgreSQL strategies, declare the Model without an ID field:

tyrus
@model("users")
export interface User {
    name: string;
}
BackendDefault strategySource ModelGenerated ID in Model results
SQLiteINTEGER PRIMARY KEY / rowidNo ID fieldSynthetic readonly id: i64
MongoDBServer-generated _idNo _id fieldSynthetic readonly _id: ObjectId
MySQLauto_incrementNo ID fieldSynthetic readonly id: i64
PostgreSQLidentityNo ID fieldSynthetic readonly id: i64

Only declare an ID field when selecting a non-default MySQL or PostgreSQL strategy. Each declaration below uses the same simple User Model; import Uuid or Uuid7 from tyrus:db as shown.

MySQL uuid uses Uuid:

tyrus
import { Uuid } from "tyrus:db";

@model("users")
export interface User {
    @id({ strategy: "uuid" })
    id: Uuid;
    name: string;
}

MySQL uuid_short uses u64:

tyrus
@model("users")
export interface User {
    @id({ strategy: "uuid_short" })
    id: u64;
    name: string;
}

PostgreSQL uuid uses Uuid:

tyrus
import { Uuid } from "tyrus:db";

@model("users")
export interface User {
    @id({ strategy: "uuid" })
    id: Uuid;
    name: string;
}

PostgreSQL uuid7 uses Uuid7:

tyrus
import { Uuid7 } from "tyrus:db";

@model("users")
export interface User {
    @id({ strategy: "uuid7" })
    id: Uuid7;
    name: string;
}

SQLite, MySQL y PostgreSQL agregan un id: i64 sintético de solo lectura a los Models devueltos; MongoDB agrega un _id: ObjectId de solo lectura. MongoDB genera este valor al insertar. La estrategia MySQL no predeterminada uuid usa Uuid, mientras que uuid_short usa u64; UUID() genera UUIDv1 y UUID_SHORT() tiene restricciones de configuración del servidor, reinicios, tasa de llamadas y replicación. Las estrategias PostgreSQL no predeterminadas uuid y uuid7 usan Uuid y Uuid7, respectivamente. UUIDv4 requiere PostgreSQL 13 o posterior, UUIDv7 requiere PostgreSQL 18 o posterior y los defaults de expresión UUID requieren MySQL 8.0.13 o posterior. Importa estos tipos desde tyrus:db. Las migrations crean la columna de ID nativa y el default correspondiente. @column("physical_name") mapea un campo de interfaz a una columna con otro nombre; @unique, @default(value) y @foreignKey("teams", "id") declaran una constraint unique, un default compatible y una clave foránea de una columna. Cada columna de la base de datos puede mapearse a un solo campo de la interfaz. Los metadatos de Model pueden omitir paréntesis cuando no reciben un valor; los validator decorations conservan los paréntesis, como en @email().

Uuid ​

Uuid es el tipo público string para valores UUIDv4. Impórtalo desde tyrus:db cuando un Model use la estrategia MySQL uuid o PostgreSQL uuid.

Uuid7 ​

Uuid7 es el tipo público string para valores UUIDv7. Impórtalo desde tyrus:db cuando un Model use la estrategia PostgreSQL uuid7.

La nulabilidad de la columna proviene del tipo del campo del modelo: name: string se mapea a una columna NOT NULL, mientras que name: string? se mapea a una columna nullable. El ? en name?: string marca la propiedad de la interfaz como omitible; no significa que la columna de la base de datos acepte NULL. Usa string? para modelar una columna nullable. @notNull() es una validator decoration que comprueba en tiempo de ejecución que un valor opcional esté presente, no metadatos del modelo para declarar una constraint de la base de datos; por eso no hace falta para describir una columna NOT NULL en el modelo.

Cuando hay un snapshot local del schema, el compilador comprueba que existan la tabla y las columnas asignadas, que coincidan los tipos lógicos y la nulabilidad, que el campo id corresponda a la clave primaria de una columna, que las declaraciones unique coincidan con las constraints de la base de datos, que existan los defaults y que las declaraciones de clave foránea coincidan con la relación de la base de datos. db.query<User>("SELECT * FROM users", []) expande las columnas físicas asignadas con alias para los nombres de los campos de la interfaz. En las proyecciones explícitas, usa AS para que coincidan con los campos de la interfaz. Los tipos lógicos admitidos son boolean, bytes, f64, i64, string y u64; los campos f32, i32 y u32 se mapean a los tipos de base de datos más amplios correspondientes. Las columnas nullable deben usar un tipo opcional, como string?.

Los campos de relación se declaran por separado de las columnas almacenadas: @belongsTo("teamId") team: Team? carga el modelo referenciado mediante el campo escalar teamId, mientras que @hasOne("userId") profile: Profile? y @hasMany("userId") posts: Post[]? usan la clave foránea del modelo relacionado. @manyToMany("user_roles", "user_id", "role_id") roles: Role[]? declara una tabla pivote explícita y sus columnas de clave foránea de origen y destino. La tabla pivote debe existir en el snapshot del schema y contener constraints de clave foránea correspondientes a las claves primarias de ambos modelos. El campo clave de las relaciones directas debe declarar un @foreignKey correspondiente y los campos de relación deben ser opcionales porque quizá no se carguen. Los campos de relación no crean columnas; las claves escalares siguen persistidas. findMany carga las relaciones solicitadas solo cuando se enumeran en el array literal include, usando una instrucción SQL sin carga lazy ni consultas N+1. Una relación puede proyectarse a campos escalares seleccionados con { include: [{ team: ["id", "name"] }] }, y el tipo del resultado contiene solo esos campos. Los includes admiten un nivel de relación. Incluir hasMany o manyToMany requiere relationLimit de 1 a 500 para cada colección devuelta; no se admiten includes anidados.

Las operaciones del Model generan SQL parametrizado u operaciones documentales a partir de los metadatos declarados. Model.insertOne(data) inserta un registro; Model.insertMany(rows) inserta de 1 a 500 registros y exige los mismos campos en el mismo orden para cada registro. SQLite, PostgreSQL y MySQL usan el límite conservador de Tyrus de 999 valores SQL enlazados, así que una fila con seis campos permite hasta 166 registros por llamada. MongoDB envía documentos BSON, por lo que su límite de 500 documentos no depende de la cantidad de campos, sujeto al límite BSON de 16 MiB por documento. Un lote mayor se rechaza antes de la ejecución. Model.updateMany(filter, changes) y Model.deleteMany(filter) afectan todos los registros coincidentes. Cada update y delete requiere un filtro no vacío, y los updates no pueden cambiar el campo @id. Model.updateOne y Model.deleteOne requieren igualdad en un campo marcado con @id o @unique, evitando varias coincidencias. insertOne devuelve Promise<Result<T, DbError>>, insertMany devuelve Promise<Result<T[], DbError>>, updateOne y deleteOne devuelven Promise<Result<T?, DbError>>, y updateMany y deleteMany devuelven Promise<Result<u64, DbError>>, donde T es el tipo del modelo. Espera cada llamada; los errores de constraints de la base de datos siguen siendo recuperables.

Los objetos de inserción pueden omitir columnas nullable y columnas con un default en el snapshot de la base de datos. También pueden omitir la clave primaria @id; la base configurada la genera cuando el schema de la tabla define identity o un default, de lo contrario la inserción devuelve un DbError recuperable. SQLite sintetiza su id de solo lectura y lo genera automáticamente. Los métodos de inserción devuelven el recurso o los recursos del Model con sus IDs generados, incluidas las estrategias UUID y uuid_short. La omisión de otro campo obligatorio sin default en la base de datos se rechaza durante la compilación. @default(value) valida el tipo del literal y declara el default persistente del modelo. tyrus db migrate generate <name> usa los defaults del modelo al generar tablas iniciales y adiciones incrementales admitidas; revisa el SQL generado antes de aplicarlo.

Mutaciones de Model en MongoDB ​

MongoDB admite insertOne, insertMany, updateOne, updateMany, deleteOne y deleteMany mediante la misma API de Model. El servidor genera _id cuando el documento insertado lo omite. Los métodos de inserción devuelven los documentos insertados; los updates y deletes de un documento devuelven el documento correspondiente o ausencia, y las operaciones en varios documentos devuelven la cantidad afectada. Los filtros de Model y los valores de mutación se codifican por separado del descriptor de operación, y los valores de filtro _id y @id se validan y convierten a BSON ObjectId. Los valores ObjectId no válidos devuelven ERR_DB_INVALID_OBJECT_ID; los fallos de operación devuelven ERR_DB_MUTATION_FAILED.

Los operandos de filtros y los valores de inserción o actualización de MongoDB se comprueban durante la compilación frente a los tipos de los campos del Model. En runtime, Tyrus valida recursivamente los tipos BSON de las categorías escalares y contenedoras admitidas, incluidos los campos anidados obligatorios, los tipos de elementos de arrays y los valores nullable, y exige en las inserciones los campos no opcionales sin valores predeterminados; también valida los documentos devueltos y rechaza los campos obligatorios ausentes o los valores BSON incompatibles con ERR_DB_INVALID_MODEL_VALUE. En ObjectId[], los elementos nulos solo se aceptan cuando el tipo del elemento es opcional. En la primera inserción de un Model, Tyrus crea una collection inexistente con un validador en el servidor derivado de los tipos de campo admitidos del Model. Las collections existentes permanecen intactas, incluidas las creadas simultáneamente por otro cliente; la validación en runtime sigue activa en las operaciones de Tyrus, pero las escrituras externas en esas collections no están cubiertas. Los campos del Model pueden contener objetos anidados y arrays; Tyrus los serializa como documentos y arrays BSON, conserva los valores nullable y rechaza anidamientos superiores a 100 niveles con ERR_DB_VALUE_TOO_DEEP. Los valores anidados se convierten según el schema declarado en el Model: los campos Instant anidados se convierten en BSON Date, los campos ObjectId anidados en BSON ObjectId, y un objeto común con seconds y nanoseconds sigue siendo un documento BSON. Los campos Instant se almacenan como BSON Date y se decodifican de nuevo a la representación seconds y nanoseconds; como BSON Date tiene precisión de milisegundos, un Instant con precisión inferior a un milisegundo devuelve ERR_DB_VALUE_OUT_OF_RANGE en vez de redondearse. Cada documento y filtro BSON serializado tiene un límite de 16 MiB; superarlo devuelve ERR_DB_DOCUMENT_TOO_LARGE, incluso cuando un array o valor anidado hace que el documento supere el límite.

MongoDB no aplica los metadatos relacionales @unique, @default ni @foreignKey, ni Tyrus administra relaciones de Model en este backend. El compilador rechaza los Models que usan estas funciones no admitidas en lugar de tratar sus garantías como activas. Los timestamps automáticos del Model sí están admitidos y se almacenan como BSON Date. Administra directamente en la base de datos los índices de MongoDB necesarios para la unicidad.

Todos los valores de mutación se enlazan como parámetros. Los identificadores de campos y tablas provienen de la declaración del modelo, y los campos desconocidos, cambios vacíos, lotes vacíos, campos inconsistentes entre registros, lotes demasiado grandes y filtros inseguros para una operación de un solo registro se rechazan antes de la ejecución. Usa Model.findOne(filter) para obtener un único resultado opcional, Model.findMany(filter) para obtener una lista tipada, Model.count(filter) para obtener la cantidad de registros coincidentes y db.query<T> para consultas personalizadas. La paginación numerada y por cursor solo están disponibles en Model.findMany mediante sus opciones de paginación.