Modelos de banco de dados
Marque uma interface com @model("table_name") para associá-la a uma tabela relacional. Exporte o modelo pelo módulo e importe-o onde for necessário; a importação disponibiliza operações como User.findMany(filter) no nome do tipo do modelo.
ObjectId do MongoDB
Importe ObjectId de tyrus:db para identificadores MongoDB. Sua representação no Tyrus e em JSON é uma string hexadecimal de 24 caracteres; campos do Model declarados como ObjectId ou ObjectId[] são armazenados como BSON ObjectId (ou arrays deles), enquanto campos comuns string continuam como strings BSON. Filtros em _id, em um campo @id ou em outro campo ObjectId convertem valores para BSON ObjectId; filtros ObjectId[] aceitam eq, ne e in. Valores inválidos retornam ERR_DB_INVALID_OBJECT_ID. O MongoDB armazena o campo @id do Model como _id.
O MongoDB gera _id quando um documento inserido o omite e inclui _id nos resultados de findOne e findMany. Não é necessário declarar um campo @id no MongoDB; _id é sintetizado no tipo do Model retornado e pode ser usado em filtros. Se a interface declarar um campo lógico com @id, seu tipo deve ser compatível com ObjectId; os resultados conterão esse campo e _id, ambos mapeados para o mesmo identificador do documento.
@model habilita os campos automáticos createdAt e updatedAt por padrão. Eles são propriedades sintéticas do modelo do tipo Instant, portanto não os declare na interface nem importe Instant somente por causa desses campos gerados. Um campo declarado explicitamente, como deletedAt: Instant?, ainda exige a importação de Instant de tyrus:temporal. Use { timestamps: false } nas opções de @model para desativar os timestamps automáticos. { snakeCase: true } altera somente os nomes físicos das colunas desses timestamps para created_at e updated_at; não renomeia a tabela nem os outros campos. Use @column("physical_name") para mapear campos comuns. Como snakeCase transforma apenas as colunas de timestamps automáticos, combiná-lo com { timestamps: false } é inválido. Os inserts ORM inicializam ambos os campos, e os updates ORM definem updatedAt na mesma mutação. O MongoDB armazena esses valores como BSON Date; o SQLite os armazena como texto UTC, o PostgreSQL como TIMESTAMPTZ e o MySQL como DATETIME(3). Valores com precisão inferior a microssegundos no PostgreSQL ou a milissegundos no MySQL são rejeitados em vez de arredondados. SQL direto e gravações feitas por outros clientes não recebem o comportamento de timestamp do ORM.
// 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?;
}Geração de IDs
O backend em database.backend seleciona a estratégia padrão. SQLite e MongoDB não precisam de um campo de ID no Model. MySQL usa auto_increment por padrão, e PostgreSQL usa identity; esses padrões também não precisam de um campo de ID declarado. O Tyrus adiciona o ID gerado aos resultados de leitura do Model. Declare id com @id somente para escolher uma estratégia MySQL ou PostgreSQL não padrão.
For SQLite, MongoDB, and the default MySQL and PostgreSQL strategies, declare the Model without an ID field:
@model("users")
export interface User {
name: string;
}| Backend | Default strategy | Source Model | Generated ID in Model results |
|---|---|---|---|
| SQLite | INTEGER PRIMARY KEY / rowid | No ID field | Synthetic readonly id: i64 |
| MongoDB | Server-generated _id | No _id field | Synthetic readonly _id: ObjectId |
| MySQL | auto_increment | No ID field | Synthetic readonly id: i64 |
| PostgreSQL | identity | No ID field | Synthetic 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:
import { Uuid } from "tyrus:db";
@model("users")
export interface User {
@id({ strategy: "uuid" })
id: Uuid;
name: string;
}MySQL uuid_short uses u64:
@model("users")
export interface User {
@id({ strategy: "uuid_short" })
id: u64;
name: string;
}PostgreSQL uuid uses Uuid:
import { Uuid } from "tyrus:db";
@model("users")
export interface User {
@id({ strategy: "uuid" })
id: Uuid;
name: string;
}PostgreSQL uuid7 uses Uuid7:
import { Uuid7 } from "tyrus:db";
@model("users")
export interface User {
@id({ strategy: "uuid7" })
id: Uuid7;
name: string;
}SQLite, MySQL e PostgreSQL adicionam id: i64 sintético e somente leitura aos Models retornados; MongoDB adiciona o _id: ObjectId somente leitura. O MongoDB gera esse valor na inserção. A estratégia MySQL não padrão uuid usa Uuid, enquanto uuid_short usa u64; UUID() gera UUIDv1, e UUID_SHORT() tem restrições de configuração do servidor, reinicialização, taxa de chamadas e replicação. As estratégias PostgreSQL não padrão uuid e uuid7 usam Uuid e Uuid7, respectivamente. UUIDv4 requer PostgreSQL 13 ou posterior, UUIDv7 requer PostgreSQL 18 ou posterior, e defaults de expressão UUID exigem MySQL 8.0.13 ou posterior. Importe esses tipos de tyrus:db. As migrations criam a coluna de ID nativa e o default correspondente. @column("physical_name") mapeia um campo da interface para uma coluna com outro nome; @unique, @default(value) e @foreignKey("teams", "id") declaram uma constraint unique, um default compatível e uma chave estrangeira de uma coluna. Cada coluna do banco pode mapear para apenas um campo da interface. Metadados de Model podem omitir parênteses quando não recebem valor; validator decorations mantêm os parênteses, como em @email().
Uuid
Uuid é o tipo público string para valores UUIDv4. Importe-o de tyrus:db quando um Model usar a estratégia MySQL uuid ou PostgreSQL uuid.
Uuid7
Uuid7 é o tipo público string para valores UUIDv7. Importe-o de tyrus:db quando um Model usar a estratégia PostgreSQL uuid7.
A nulabilidade da coluna vem do tipo do campo do modelo: name: string mapeia para uma coluna NOT NULL, enquanto name: string? mapeia para uma coluna nullable. O ? em name?: string marca a propriedade da interface como omitível; não significa que a coluna do banco aceita NULL. Use string? para modelar uma coluna nullable. @notNull() é uma validator decoration que verifica em runtime se um valor opcional está presente, não um metadado do modelo para declarar uma constraint do banco; por isso, ela não é necessária para descrever uma coluna NOT NULL no modelo.
Quando há um snapshot local do schema, o compilador verifica se a tabela e as colunas mapeadas existem, se os tipos lógicos e a nulabilidade coincidem, se o campo id corresponde à chave primária de uma coluna, se as declarações unique correspondem às constraints do banco, se os defaults existem e se as declarações de chave estrangeira correspondem à relação no banco. db.query<User>("SELECT * FROM users", []) expande as colunas físicas mapeadas com aliases para os nomes dos campos da interface. Em projeções explícitas, use AS para corresponder aos campos da interface. Os tipos lógicos aceitos são boolean, bytes, f64, i64, string e u64; campos f32, i32 e u32 mapeiam para os tipos de banco mais largos correspondentes. Colunas nullable devem usar um tipo opcional, como string?.
Campos de relação são declarados separadamente das colunas armazenadas: @belongsTo("teamId") team: Team? carrega o modelo referenciado pelo campo escalar teamId, enquanto @hasOne("userId") profile: Profile? e @hasMany("userId") posts: Post[]? usam a chave estrangeira do modelo relacionado. @manyToMany("user_roles", "user_id", "role_id") roles: Role[]? declara uma tabela pivot explícita e suas colunas de chave estrangeira de origem e destino. A tabela pivot deve existir no snapshot do schema e conter constraints de chave estrangeira correspondentes às chaves primárias dos dois modelos. O campo-chave das relações diretas deve declarar um @foreignKey correspondente, e campos de relação devem ser opcionais porque podem não ser carregados. Campos de relação não criam colunas; chaves escalares continuam persistidas. findMany carrega relações solicitadas somente quando listadas no array literal include, usando uma instrução SQL sem carregamento lazy ou consultas N+1. Uma relação pode ser projetada para campos escalares selecionados com { include: [{ team: ["id", "name"] }] }, e o tipo do resultado contém somente esses campos. Includes aceitam um nível de relação. Incluir hasMany ou manyToMany exige relationLimit de 1 a 500 para cada coleção retornada; includes aninhados não são aceitos.
As operações do Model geram SQL parametrizado ou operações documentais a partir dos metadados declarados. Model.insertOne(data) insere um registro; Model.insertMany(rows) insere de 1 a 500 registros e exige os mesmos campos na mesma ordem para cada registro. SQLite, PostgreSQL e MySQL usam o limite conservador do Tyrus de 999 valores SQL vinculados, então uma linha com seis campos permite até 166 registros por chamada. MongoDB envia documentos BSON, então seu limite de 500 documentos independe do número de campos, sujeito ao limite BSON de 16 MiB por documento. Um lote maior é rejeitado antes da execução. Model.updateMany(filter, changes) e Model.deleteMany(filter) afetam todos os registros correspondentes. Cada atualização e exclusão exige um filtro não vazio, e updates não podem alterar o campo @id. Model.updateOne e Model.deleteOne exigem igualdade em um campo marcado com @id ou @unique, impedindo múltiplas correspondências. insertOne retorna Promise<Result<T, DbError>>, insertMany retorna Promise<Result<T[], DbError>>, updateOne e deleteOne retornam Promise<Result<T?, DbError>>, e updateMany e deleteMany retornam Promise<Result<u64, DbError>>, em que T é o tipo do modelo. Aguarde cada chamada; falhas de constraint do banco continuam recuperáveis.
Objetos de inserção podem omitir colunas nullable e colunas com default registrado no snapshot do banco. Também podem omitir a chave primária @id; o banco configurado a gera quando o schema da tabela define identity ou default, caso contrário a inserção retorna um DbError recuperável. O SQLite sintetiza seu id somente leitura e o gera automaticamente. Os métodos de inserção retornam o recurso ou os recursos do Model com os IDs gerados, inclusive nas estratégias UUID e uuid_short. A omissão de outro campo obrigatório sem default no banco é rejeitada durante a compilação. @default(value) valida o tipo do literal e declara o default persistente do modelo. tyrus db migrate generate <name> usa defaults do modelo ao gerar tabelas iniciais e adições incrementais suportadas; revise o SQL gerado antes de aplicá-lo.
Mutações de Model no MongoDB
O MongoDB oferece insertOne, insertMany, updateOne, updateMany, deleteOne e deleteMany pela mesma API de Model. O servidor gera _id quando o documento inserido o omite. Métodos de inserção retornam os documentos inseridos; updates e deletes de um documento retornam o documento correspondente ou ausência, e operações em vários documentos retornam a quantidade afetada. Os filtros do Model e os valores de mutação são codificados separadamente do descritor da operação, e valores de filtro _id e @id são validados e convertidos para BSON ObjectId. Valores ObjectId inválidos retornam ERR_DB_INVALID_OBJECT_ID; falhas da operação retornam ERR_DB_MUTATION_FAILED.
Os operandos dos filtros e os valores de insert ou update do MongoDB são comparados aos tipos dos campos do Model durante a compilação. Em runtime, o Tyrus valida recursivamente os tipos BSON das categorias escalares e de contêiner suportadas, incluindo campos aninhados obrigatórios, tipos dos elementos de arrays e valores nullable, e exige nos inserts os campos não opcionais sem defaults; também valida os documentos retornados e rejeita campos obrigatórios ausentes ou valores BSON incompatíveis com ERR_DB_INVALID_MODEL_VALUE. Em ObjectId[], elementos nulos só são aceitos quando o tipo do elemento é opcional. Na primeira inserção de um Model, o Tyrus cria uma collection ausente com um validator no servidor derivado dos tipos de campo do Model que são suportados. Collections existentes permanecem intactas, inclusive as criadas simultaneamente por outro cliente; a validação em runtime continua ativa nas operações do Tyrus, mas gravações externas nessas collections não são cobertas. Os campos do Model podem conter objetos aninhados e arrays; o Tyrus os serializa como documentos e arrays BSON, preserva valores nullable e rejeita aninhamento acima de 100 níveis com ERR_DB_VALUE_TOO_DEEP. Os valores aninhados são convertidos conforme o schema declarado no Model: campos Instant aninhados viram BSON Date, campos ObjectId aninhados viram BSON ObjectId, e um objeto comum com seconds e nanoseconds permanece um documento BSON. Campos Instant são armazenados como BSON Date e decodificados novamente para a representação seconds e nanoseconds; como BSON Date tem precisão de milissegundos, um Instant com precisão inferior a milissegundos retorna ERR_DB_VALUE_OUT_OF_RANGE em vez de ser arredondado. Cada documento e filtro BSON serializado tem limite de 16 MiB; exceder esse limite retorna ERR_DB_DOCUMENT_TOO_LARGE, inclusive quando um array ou valor aninhado faz o documento ultrapassar o limite.
O MongoDB não aplica os metadados relacionais @unique, @default e @foreignKey, nem o Tyrus gerencia relacionamentos de Model nesse backend. O compilador rejeita Models que usem esses recursos não suportados em vez de tratar suas garantias como ativas. Os timestamps automáticos do Model são suportados e armazenados como BSON Date. Gerencie diretamente no banco os índices MongoDB necessários para unicidade.
Todos os valores de mutação são parâmetros vinculados. Os identificadores de campos e tabelas vêm da declaração do modelo, e campos desconhecidos, alterações vazias, lotes vazios, campos inconsistentes entre registros, lotes acima do limite e filtros inseguros para uma única operação são rejeitados antes da execução. Use Model.findOne(filter) para um único resultado opcional, Model.findMany(filter) para uma lista tipada, Model.count(filter) para a quantidade de registros correspondentes e db.query<T> para consultas personalizadas. A paginação numerada e por cursor estão disponíveis somente em Model.findMany pelas opções de paginação.
