tyrus:db
tyrus:db fornece operações SQL relacionais para SQLite, PostgreSQL e MySQL com validação offline do schema. Toda operação SQL e ORM/ODM é assíncrona: use await e trate o Promise<Result<..., DbError>>. Configure database em tyrus.json e forneça um snapshot local do schema antes de compilar. Introspecção de schema, verificação de divergências e comparação somente leitura entre Models e snapshot aceitam os três backends SQL. O SQLite oferece migrations incrementais seguras, incluindo reconstruções revisáveis de tabelas. PostgreSQL e MySQL geram schemas iniciais e migrations incrementais seguras para novas tabelas de Model, colunas aditivas, defaults literais, constraints únicas e chaves estrangeiras opcionais quando o schema ativo e o snapshot confirmam a compatibilidade; transformações destrutivas e mudanças ambíguas exigem migrations SQL escritas manualmente. Consulte Comandos de schema do banco.
API disponível
db.query<T>executa umSELECTvalidado e retornaPromise<Result<T[], DbError>>; mutações SQL usam a mesma função e retornamPromise<Result<void, DbError>>.Model.insertOne(data)insere um registro do modelo e retornaPromise<Result<T, DbError>>.Model.insertMany(rows)insere um lote limitado e retornaPromise<Result<T[], DbError>>.Model.findMany(filter)Model.findOne(filter)retorna um registro correspondente ou um valor de ausência tipado usando um filtro tipado e parametrizado.Model.updateOne(filter, changes)atualiza um registro identificado por um campo único.Model.updateMany(filter, changes)atualiza todos os registros que correspondem a um filtro não vazio.Model.deleteOne(filter)exclui um registro identificado por um campo único.Model.deleteMany(filter)exclui todos os registros que correspondem a um filtro não vazio.Model.count(filter)retorna a quantidade de registros correspondentes comoPromise<Result<u64, DbError>>e aceita{}para contar todos os registros.Page<T>documenta o tipo de retorno da paginação, que deve ser importado explicitamente.ObjectId,UuideUuid7são tipos públicos de campo Model para estratégias de ID do MongoDB e relacionais.- Modelos de banco de dados declaram e validam mapeamentos explícitos de tabelas e colunas relacionais.
- Migrations explica como gerar, revisar e aplicar migrations de schema e seeds.
- Transações de banco de dados documentam transações explícitas para
db.querynos backends SQL. - Joins SQL descrevem joins internos e externos e os campos opcionais exigidos no resultado.
- Agregações descreve projeções de agregação, tipos de retorno e o comportamento sem correspondências.
DbErrorcontém um código de erro estável e uma mensagem legível.- Segurança SQL descreve a vinculação de parâmetros, SQL apenas literal e o subconjunto de consultas aceito.
- API Flow conecta uma rota de User ao controller, service, repository e operações de banco em um exemplo SQLite completo.
Banco de dados embutido e backends de servidor
O Tyrus oferece suporte a SQLite, PostgreSQL e MySQL para operações SQL e ORM em runtime pela mesma API de modelos. O MongoDB oferece count, findOne, findMany com paginação numerada e por cursor e as seis mutações de Model; includes de relações e consultas SQL não estão disponíveis no MongoDB. A paginação MongoDB ordena por _id, e a contagem e a leitura dos itens são operações separadas, então gravações concorrentes podem afetar a consistência entre elas. O mecanismo SQLite é incluído nas aplicações nativas do Tyrus, então desenvolvedores e usuários da aplicação não precisam instalar o SQLite separadamente nem executar um servidor de banco de dados. A aplicação lê e grava um arquivo SQLite separado; por isso, o diretório precisa permitir gravação e o arquivo deve fazer parte da estratégia de backup da aplicação. Visão geral do SQLite
Quando database.backend é mongodb, instruções SQL passadas a db.query são rejeitadas durante a compilação com E3306. A configuração do MongoDB lê database.connectionEnv somente em runtime, verifica a conexão com ping e retorna valores DbError redigidos quando há falha de conexão. O pool aplica maxConnections, connectTimeoutMs, acquireTimeoutMs, queryTimeoutMs e idleTimeoutMs; o TLS é controlado pela URL de conexão e não é obrigatório no Tyrus. Use database.tls.caFile para um certificado CA privado relativo ao projeto ou configure database.tls.certFile e database.tls.keyFile juntos para mTLS; quando esses arquivos são configurados, a verificação do certificado e hostname permanece ativa. O pool do MongoDB aceita maxConnections (1–100), connectTimeoutMs, acquireTimeoutMs e queryTimeoutMs (1–120.000 ms), e idleTimeoutMs (1–86.400.000 ms). acquireTimeoutMs limita quanto tempo uma operação espera por uma vaga de conexão no runtime do Tyrus e retorna ERR_DB_POOL_TIMEOUT quando o prazo expira. maxLifetimeMs não é aceito e é rejeitado quando configurado. Os filtros de leitura aceitam igualdade, comparação, membership e or; like usa um padrão sensível a maiúsculas, no qual % e _ são curingas. Os valores de filtros e mutações são comparados aos tipos dos campos declarados no Model durante a compilação. Campos de Model no MongoDB podem conter objetos aninhados e arrays; o Tyrus converte esses valores para BSON e limita o aninhamento a 100 níveis, retornando ERR_DB_VALUE_TOO_DEEP quando o limite é excedido. Em runtime, documentos BSON e filtros acima do limite de 16 MiB do MongoDB são rejeitados com ERR_DB_DOCUMENT_TOO_LARGE (limites de documentos do MongoDB). O Tyrus não traduz SQL em consultas de documentos. Includes de relações em backends que não sejam SQLite são rejeitados durante a compilação com E3307.
O runtime processa no máximo 32 operações de banco em paralelo e aceita até 128 solicitações adicionais na fila. Quando ela está cheia, a chamada retorna ERR_DB_BUSY para que a aplicação possa tentar novamente com espera progressiva, sem acumular trabalho pendente sem limite.
Os servidores PostgreSQL e MySQL permanecem externos à aplicação. Configure database.backend como postgresql ou mysql e defina database.connectionEnv com o nome da variável de ambiente que contém a URL de conexão; urlEnv não é aceito como alias. Em runtime, o Tyrus lê essa variável do ambiente do processo ou do arquivo configurado por security.envFile; a URL não é embutida no programa gerado nem escrita em diagnósticos. O bloco opcional database.pool aceita maxConnections (1–100), connectTimeoutMs, acquireTimeoutMs e queryTimeoutMs (1–120.000 ms cada), e idleTimeoutMs e maxLifetimeMs (1–86.400.000 ms cada). Os padrões são 10 conexões, 10.000 ms, 5.000 ms, 30.000 ms, 30.000 ms e 1.800.000 ms, respectivamente. Os timeouts de conexão, aquisição e operação retornam ERR_DB_CONNECTION_TIMEOUT, ERR_DB_POOL_TIMEOUT e ERR_DB_QUERY_TIMEOUT, respectivamente. O SQLite rejeita esse bloco. O MongoDB aceita maxConnections, connectTimeoutMs, acquireTimeoutMs, queryTimeoutMs e idleTimeoutMs nas faixas documentadas; opções MongoDB não suportadas são rejeitadas em vez de ignoradas. TLS de banco de dados é opcional no PostgreSQL, MySQL e MongoDB. Sem arquivos em database.tls, o Tyrus deixa o comportamento de TLS a cargo da URL de conexão e do driver, permitindo servidores locais sem criptografia e URLs de produção com TLS. Se database.tls configurar uma CA ou identidade de cliente, o Tyrus ativa TLS verificado; no PostgreSQL usa sslmode=verify-full e no MySQL ssl-mode=VERIFY_IDENTITY. Um modo mais fraco é rejeitado com ERR_DB_TLS_CONFIGURATION quando arquivos TLS estão configurados. Defina database.tls.caFile com um certificado CA privado relativo ao projeto ou configure juntos database.tls.certFile e database.tls.keyFile para mTLS. O MongoDB aceita as mesmas configurações de CA e identidade de cliente. O Tyrus mantém dentro do projeto os caminhos de arquivos TLS configurados em tyrus.json. SQLite é um banco local embutido e não usa TLS de rede.
{
"database": {
"backend": "postgresql",
"connectionEnv": "DATABASE_URL",
"tls": {
"caFile": "certs/database-ca.pem",
"certFile": "certs/database-client.pem",
"keyFile": "certs/database-client-key.pem"
}
}
}PostgreSQL oferece atualmente suporte a booleanos, inteiros com sinal, números de ponto flutuante, texto, bytes e campos UUID nativos para identificadores de Model. MySQL oferece suporte a SMALLINT, INT, BIGINT, números de ponto flutuante, texto, bytes e identificadores UUID armazenados como CHAR(36); colunas de resultado MySQL TINYINT e BOOLEAN ainda não são suportadas. Includes de relações são exclusivos do SQLite; PostgreSQL e MySQL retornam ERR_DB_FEATURE_UNSUPPORTED para eles. MySQL oferece suporte ao intervalo completo de campos u64 em Models, incluindo uuid_short; PostgreSQL não pode vincular valores u64 acima do intervalo de 64 bits com sinal. Tipos nativos fora desses mapeamentos retornam um DbError recuperável. PostgreSQL/MySQL aceitam migrations iniciais de Model, novas tabelas de Model, colunas aditivas, defaults literais, constraints únicas, chaves estrangeiras opcionais sob condições validadas e arquivos SQL manuais identificados pelo backend. A geração incremental verifica o schema ativo contra o snapshot e recusa mudanças destrutivas, alterações de definição ou casos ambíguos. Status, aplicação, introspecção, verificação de divergências e comparação somente leitura entre Models e snapshot funcionam nos três backends SQL; a geração de migrations destrutivas ou in-place continua exclusiva do SQLite. O build e o Language Server permanecem offline e usam o snapshot local configurado. Falhas recuperáveis usam Result, nunca throws.
Matriz de capacidades dos backends
O runtime mapeia valores do banco para escalares do Tyrus, sem expor tipos do driver. Use i64, u64 e f64 para dados numéricos; PostgreSQL não pode vincular valores u64 acima do intervalo de 64 bits com sinal, enquanto MySQL oferece suporte ao intervalo completo de u64 em projeções tipadas e parâmetros vinculados; f64 não preserva aritmética decimal exata. Campos Instant de Models são armazenados como texto UTC no SQLite, TIMESTAMPTZ no PostgreSQL e DATETIME(3) no MySQL; valores com precisão além da suportada pelo backend são rejeitados em vez de arredondados. O MongoDB armazena Instant como BSON Date com precisão de milissegundos e preserva valores temporais civis como documentos BSON; um Instant com precisão inferior a milissegundos é rejeitado em vez de arredondado.
| Capacidade | SQLite | PostgreSQL | MySQL | MongoDB |
|---|---|---|---|---|
| Sintaxe de parâmetros vinculados | ? | ? do Tyrus, convertido para $1, $2 e assim por diante | ? | Valores de Model são parâmetros separados codificados como BSON |
| Valores binários | SQLite BLOB ↔ u8[] | PostgreSQL bytea ↔ u8[] | MySQL BLOB ↔ u8[] | BSON Binary ↔ u8[] |
| Valores estruturados | Não aceitos como parâmetros SQL | Não aceitos como parâmetros SQL | Não aceitos como parâmetros SQL | Objetos e arrays aninhados viram documentos e arrays BSON, limitados a 100 níveis e 16 MiB por documento |
| Data e hora | Instant de Model é armazenado como texto UTC | Instant de Model é armazenado como TIMESTAMPTZ com precisão de microssegundos | Instant de Model é armazenado como DATETIME(3) com precisão de milissegundos | Instant vira BSON Date com precisão de milissegundos; valores temporais civis viram documentos BSON |
| Identificadores entre aspas | Aspas duplas; a correspondência segue as regras de identificadores sem distinção entre maiúsculas e minúsculas do SQLite | Aspas duplas; nomes entre aspas preservam maiúsculas e minúsculas | Identificadores entre aspas duplas no Tyrus são convertidos para crases; o comportamento de maiúsculas e minúsculas dos nomes de tabela depende da configuração do servidor | Nomes de collections e campos vêm de metadados validados do Model |
| Inserts em lote | Até 500 linhas e 999 parâmetros vinculados | Até 500 linhas e 999 parâmetros vinculados | Até 500 linhas e 999 parâmetros vinculados | Até 500 documentos, cada um com até 16 MiB; o limite de parâmetros SQL não se aplica |
| Execução em lote | Uma instrução com várias linhas; o backend aplica a atomicidade da instrução | Uma instrução com várias linhas; o backend aplica a atomicidade da instrução | Uma instrução com várias linhas; o backend aplica a atomicidade da instrução | Uma operação em lote de documentos; progresso parcial é informado como falha recuperável da operação |
| Resultado de mutação | Inserts retornam recursos, updates e deletes de um registro retornam um recurso opcional, e updates e deletes de vários registros retornam a quantidade afetada | Inserts retornam recursos, updates e deletes de um registro retornam um recurso opcional, e updates e deletes de vários registros retornam a quantidade afetada | Inserts retornam recursos, updates e deletes de um registro retornam um recurso opcional, e updates e deletes de vários registros retornam a quantidade afetada | Inserts retornam documentos, updates e deletes de um documento retornam um documento opcional, e updates e deletes de vários documentos retornam a quantidade afetada |
| Paginação numerada e por cursor | Disponível; a ordenação usa @id, e total é lido com a página em uma transação | Disponível; a ordenação usa @id, e total é lido com a página em uma transação REPEATABLE READ | Disponível; a ordenação usa @id, e total é lido com a página em uma transação REPEATABLE READ | Disponível em _id; contagem e itens são leituras separadas e podem observar alterações concorrentes |
| API pública de transação | Handles explícitos para db.query; contexto ORM indisponível | Handles explícitos para db.query; contexto ORM indisponível | Handles explícitos para db.query; contexto ORM indisponível | Indisponível |
| Includes de relações | Aceitos, com limites explícitos para coleções | E3307 durante a compilação; a proteção do runtime retorna ERR_DB_FEATURE_UNSUPPORTED | E3307 durante a compilação; a proteção do runtime retorna ERR_DB_FEATURE_UNSUPPORTED | Indisponíveis; E3307 durante a compilação |
| Introspecção de schema e comandos de migration | Introspecção, geração, status e aplicação | Geração inicial do Model, novas tabelas, colunas aditivas seguras, defaults literais, constraints únicas, foreign keys opcionais após validação de compatibilidade, arquivos SQL manuais, introspecção, status e aplicação | Geração inicial do Model, novas tabelas, colunas aditivas seguras, defaults literais, constraints únicas, foreign keys opcionais após validação de compatibilidade, arquivos SQL manuais, introspecção, status e aplicação | Cria collections ausentes com validators derivados do Model no primeiro insert; collections existentes permanecem intactas; sem introspecção ou comandos de migration |
Os drivers SQL retornam DbError para tipos nativos de resultado fora dos mapeamentos aceitos de booleano, inteiro, ponto flutuante, texto e binário. db.query usa placeholders ? no código-fonte em todos os backends SQL; o runtime só reescreve a forma usada pelo PostgreSQL. Os backends SQL aplicam o mesmo limite conservador de 999 parâmetros por instrução e o teto de 500 linhas por lote. O MongoDB não tem caminho de consulta SQL e aplica seus próprios limites BSON, de aninhamento e de 500 documentos por lote.
