Skip to content

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 um SELECT validado e retorna Promise<Result<T[], DbError>>; mutações SQL usam a mesma função e retornam Promise<Result<void, DbError>>.
  • Model.insertOne(data) insere um registro do modelo e retorna Promise<Result<T, DbError>>.
  • Model.insertMany(rows) insere um lote limitado e retorna Promise<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 como Promise<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, Uuid e Uuid7 sã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.query nos 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.
  • DbError conté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.

json
{
  "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.

CapacidadeSQLitePostgreSQLMySQLMongoDB
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áriosSQLite BLOB ↔ u8[]PostgreSQL bytea ↔ u8[]MySQL BLOB ↔ u8[]BSON Binary ↔ u8[]
Valores estruturadosNão aceitos como parâmetros SQLNão aceitos como parâmetros SQLNão aceitos como parâmetros SQLObjetos e arrays aninhados viram documentos e arrays BSON, limitados a 100 níveis e 16 MiB por documento
Data e horaInstant de Model é armazenado como texto UTCInstant de Model é armazenado como TIMESTAMPTZ com precisão de microssegundosInstant de Model é armazenado como DATETIME(3) com precisão de milissegundosInstant vira BSON Date com precisão de milissegundos; valores temporais civis viram documentos BSON
Identificadores entre aspasAspas duplas; a correspondência segue as regras de identificadores sem distinção entre maiúsculas e minúsculas do SQLiteAspas duplas; nomes entre aspas preservam maiúsculas e minúsculasIdentificadores 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 servidorNomes de collections e campos vêm de metadados validados do Model
Inserts em loteAté 500 linhas e 999 parâmetros vinculadosAté 500 linhas e 999 parâmetros vinculadosAté 500 linhas e 999 parâmetros vinculadosAté 500 documentos, cada um com até 16 MiB; o limite de parâmetros SQL não se aplica
Execução em loteUma instrução com várias linhas; o backend aplica a atomicidade da instruçãoUma instrução com várias linhas; o backend aplica a atomicidade da instruçãoUma instrução com várias linhas; o backend aplica a atomicidade da instruçãoUma operação em lote de documentos; progresso parcial é informado como falha recuperável da operação
Resultado de mutaçãoInserts retornam recursos, updates e deletes de um registro retornam um recurso opcional, e updates e deletes de vários registros retornam a quantidade afetadaInserts retornam recursos, updates e deletes de um registro retornam um recurso opcional, e updates e deletes de vários registros retornam a quantidade afetadaInserts retornam recursos, updates e deletes de um registro retornam um recurso opcional, e updates e deletes de vários registros retornam a quantidade afetadaInserts 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 cursorDisponível; a ordenação usa @id, e total é lido com a página em uma transaçãoDisponível; a ordenação usa @id, e total é lido com a página em uma transação REPEATABLE READDisponível; a ordenação usa @id, e total é lido com a página em uma transação REPEATABLE READDisponível em _id; contagem e itens são leituras separadas e podem observar alterações concorrentes
API pública de transaçãoHandles explícitos para db.query; contexto ORM indisponívelHandles explícitos para db.query; contexto ORM indisponívelHandles explícitos para db.query; contexto ORM indisponívelIndisponível
Includes de relaçõesAceitos, com limites explícitos para coleçõesE3307 durante a compilação; a proteção do runtime retorna ERR_DB_FEATURE_UNSUPPORTEDE3307 durante a compilação; a proteção do runtime retorna ERR_DB_FEATURE_UNSUPPORTEDIndisponíveis; E3307 durante a compilação
Introspecção de schema e comandos de migrationIntrospecção, geração, status e aplicaçãoGeraçã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çãoGeraçã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çãoCria 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.