Skip to content

tyrus:db ​

tyrus:db ofrece operaciones SQL relacionales para SQLite, PostgreSQL y MySQL con validación offline del schema. Todas las operaciones SQL y ORM/ODM son asíncronas: usa await y trata su Promise<Result<..., DbError>>. Configura database en tyrus.json y proporciona un snapshot local del schema antes de compilar. La introspección del schema, la comprobación de diferencias y la comparación de solo lectura entre Models y snapshot admiten los tres backends SQL. SQLite admite migraciones incrementales seguras, incluidas reconstrucciones revisables de tablas. PostgreSQL y MySQL generan schemas iniciales y migraciones incrementales seguras para nuevas tablas de Model, columnas aditivas, valores predeterminados literales, constraints únicas y claves foráneas opcionales cuando el schema activo y el snapshot confirman la compatibilidad; las transformaciones destructivas y los cambios ambiguos requieren migraciones SQL escritas manualmente. Consulta Comandos de schema de la base.

API disponible ​

  • db.query<T> ejecuta un SELECT validado y devuelve Promise<Result<T[], DbError>>; las mutaciones SQL usan la misma función y devuelven Promise<Result<void, DbError>>.
  • Model.insertOne(data) inserta un registro del modelo y devuelve Promise<Result<T, DbError>>.
  • Model.insertMany(rows) inserta un lote limitado y devuelve Promise<Result<T[], DbError>>.
  • Model.findMany(filter)
  • Model.findOne(filter) devuelve un registro coincidente o un valor de ausencia tipado mediante un filtro tipado y parametrizado.
  • Model.updateOne(filter, changes) actualiza un registro identificado por un campo único.
  • Model.updateMany(filter, changes) actualiza todos los registros que coinciden con un filtro no vacío.
  • Model.deleteOne(filter) elimina un registro identificado por un campo único.
  • Model.deleteMany(filter) elimina todos los registros que coinciden con un filtro no vacío.
  • Model.count(filter) devuelve la cantidad de registros coincidentes como Promise<Result<u64, DbError>> y acepta {} para contar todos los registros.
  • Page<T> documenta el tipo de resultado de paginación, que debe importarse explícitamente.
  • ObjectId, Uuid y Uuid7 son tipos públicos de campo Model para estrategias de ID de MongoDB y relacionales.
  • Modelos de base de datos declaran y validan mapeos explícitos de tablas y columnas relacionales.
  • Migraciones explica cómo generar, revisar y aplicar migraciones de schema y seeds.
  • Transacciones de base de datos documentan transacciones explícitas para db.query en backends SQL.
  • Joins SQL describen los joins internos y externos y los campos opcionales que requieren en el resultado.
  • Agregaciones describen las proyecciones agregadas, los tipos de resultado y el comportamiento sin coincidencias.
  • DbError contiene un código de error estable y un mensaje legible.
  • Seguridad SQL describe la vinculación de parámetros, el SQL solo literal y el subconjunto de consultas admitido.
  • API Flow conecta una ruta de User con su controller, service, repository y operaciones de base de datos en un ejemplo SQLite completo.

Base de datos integrada y backends de servidor ​

Tyrus admite SQLite, PostgreSQL y MySQL para operaciones SQL y ORM en runtime mediante la misma API de modelos. MongoDB admite count, findOne, findMany con paginación numerada y por cursor, y las seis mutaciones de Model; los includes de relaciones y las consultas SQL no están disponibles para MongoDB. La paginación de MongoDB ordena por _id, y el recuento y la lectura de elementos son operaciones separadas, por lo que las escrituras concurrentes pueden afectar la consistencia entre ellas. El motor SQLite se incluye en las aplicaciones nativas de Tyrus, por lo que los desarrolladores y los usuarios de la aplicación no necesitan instalar SQLite por separado ni ejecutar un servidor de base de datos. La aplicación lee y escribe un archivo SQLite independiente; por eso, el directorio debe permitir la escritura y el archivo debe incluirse en el plan de copias de seguridad. Descripción general de SQLite

Cuando database.backend es mongodb, las instrucciones SQL pasadas a db.query se rechazan durante la compilación con E3306. La configuración de MongoDB lee database.connectionEnv solo en runtime, verifica la conexión con ping y devuelve valores DbError redactados si falla la conexión. El pool aplica maxConnections, connectTimeoutMs, acquireTimeoutMs, queryTimeoutMs e idleTimeoutMs; TLS se controla mediante la URI de conexión y Tyrus no lo exige. Usa database.tls.caFile para un certificado CA privado relativo al proyecto o configura juntos database.tls.certFile y database.tls.keyFile para mTLS; al configurar estos archivos, se mantiene la verificación del certificado y del hostname. El pool de MongoDB acepta maxConnections (1–100), connectTimeoutMs, acquireTimeoutMs y queryTimeoutMs (1–120.000 ms), e idleTimeoutMs (1–86.400.000 ms). acquireTimeoutMs limita cuánto espera una operación por un cupo de conexión del runtime de Tyrus y devuelve ERR_DB_POOL_TIMEOUT si vence el plazo. maxLifetimeMs no se admite y se rechaza si se configura. Los filtros de lectura admiten igualdad, comparación, pertenencia y or; like usa un patrón que distingue mayúsculas y minúsculas, con % y _ como comodines. Los valores de filtros y mutaciones se comprueban durante la compilación frente a los tipos de los campos declarados en el Model. Los campos Model de MongoDB pueden contener objetos anidados y arrays; Tyrus convierte estos valores a BSON y limita el anidamiento a 100 niveles, devolviendo ERR_DB_VALUE_TOO_DEEP si se supera el límite. En runtime, se rechazan los documentos BSON y filtros que superen el límite de 16 MiB de MongoDB con ERR_DB_DOCUMENT_TOO_LARGE (límites de documentos de MongoDB). Tyrus no traduce SQL a consultas de documentos. Los includes de relaciones en backends distintos de SQLite se rechazan durante la compilación con E3307.

El runtime procesa como máximo 32 operaciones de base de datos en paralelo y acepta hasta 128 solicitudes adicionales en la cola. Cuando está llena, la llamada devuelve ERR_DB_BUSY para que la aplicación pueda reintentar con una espera progresiva, sin acumular trabajo pendiente sin límite.

Los servidores PostgreSQL y MySQL permanecen fuera de la aplicación. Configura database.backend como postgresql o mysql y asigna a database.connectionEnv el nombre de la variable de entorno que contiene la URL de conexión; no se acepta urlEnv como alias. En runtime, Tyrus lee esa variable del entorno del proceso o del archivo configurado mediante security.envFile; la URL no se incluye en el programa generado ni se escribe en diagnósticos. El bloque opcional database.pool acepta maxConnections (1–100), connectTimeoutMs, acquireTimeoutMs y queryTimeoutMs (1–120.000 ms cada uno), e idleTimeoutMs y maxLifetimeMs (1–86.400.000 ms cada uno). Los valores predeterminados son 10 conexiones, 10.000 ms, 5.000 ms, 30.000 ms, 30.000 ms y 1.800.000 ms, respectivamente. Los timeouts de conexión, adquisición y operación devuelven ERR_DB_CONNECTION_TIMEOUT, ERR_DB_POOL_TIMEOUT y ERR_DB_QUERY_TIMEOUT, respectivamente. SQLite rechaza este bloque. MongoDB admite maxConnections, connectTimeoutMs, acquireTimeoutMs, queryTimeoutMs e idleTimeoutMs dentro de los rangos documentados; las opciones no compatibles se rechazan en vez de ignorarse. TLS de base de datos es opcional para PostgreSQL, MySQL y MongoDB. Sin archivos en database.tls, Tyrus deja el comportamiento de TLS a la URI de conexión y al driver, por lo que los servidores locales pueden usar conexiones sin cifrar y las URI de producción pueden activar TLS. Si database.tls configura una CA o identidad de cliente, Tyrus activa TLS verificado; PostgreSQL usa sslmode=verify-full y MySQL usa ssl-mode=VERIFY_IDENTITY. Un modo más débil se rechaza con ERR_DB_TLS_CONFIGURATION cuando se configuran archivos TLS. Configura database.tls.caFile con la ruta relativa al proyecto de un certificado CA privado o configura juntos database.tls.certFile y database.tls.keyFile para mTLS. MongoDB admite las mismas opciones de CA e identidad de cliente. Tyrus mantiene dentro del proyecto las rutas de los archivos TLS configurados en tyrus.json. SQLite es una base local integrada y no utiliza TLS de red.

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 admite actualmente booleanos, enteros con signo, números de punto flotante, texto, bytes y campos UUID nativos para identificadores de Model. MySQL admite SMALLINT, INT, BIGINT, números de punto flotante, texto, bytes e identificadores UUID almacenados como CHAR(36); las columnas de resultado MySQL TINYINT y BOOLEAN todavía no son compatibles. Las inclusiones de relaciones solo funcionan con SQLite; PostgreSQL y MySQL devuelven ERR_DB_FEATURE_UNSUPPORTED para ellas. MySQL admite el rango completo de campos u64 en Models, incluido uuid_short; PostgreSQL no puede vincular valores u64 superiores al rango de 64 bits con signo. Los tipos nativos fuera de estos mapeos devuelven un DbError recuperable. PostgreSQL/MySQL admiten migraciones iniciales de Model, nuevas tablas de Model, columnas aditivas, valores predeterminados literales, constraints únicas, claves foráneas opcionales bajo condiciones validadas y archivos SQL manuales identificados por backend. La generación incremental verifica el schema activo frente al snapshot y rechaza cambios destructivos, cambios de definición o casos ambiguos. El estado, la aplicación, la introspección, la comprobación de diferencias y la comparación de solo lectura entre Models y snapshot funcionan en los tres backends SQL; la generación de migraciones destructivas o in-place sigue limitada a SQLite. El build y el Language Server permanecen offline y usan el snapshot local configurado. Los errores recuperables usan Result, nunca throws.

Matriz de capacidades de los backends ​

El runtime asigna los valores de la base de datos a escalares de Tyrus, sin exponer tipos del driver. Usa i64, u64 y f64 para datos numéricos; PostgreSQL no puede vincular valores u64 superiores al rango de 64 bits con signo, mientras que MySQL admite el rango completo de u64 en proyecciones tipadas y parámetros vinculados; f64 no conserva aritmética decimal exacta. Los campos Instant de Models se almacenan como texto UTC en SQLite, TIMESTAMPTZ en PostgreSQL y DATETIME(3) en MySQL; se rechazan los valores cuya precisión supere la admitida por el backend en vez de redondearlos. MongoDB almacena Instant como BSON Date con precisión de milisegundos y conserva los valores temporales civiles como documentos BSON; un Instant con precisión inferior a un milisegundo se rechaza en vez de redondearse.

CapacidadSQLitePostgreSQLMySQLMongoDB
Sintaxis de parámetros enlazados?? de Tyrus, convertido a $1, $2 y sucesivos?Los valores de Model son parámetros separados codificados como BSON
Valores binariosSQLite BLOB ↔ u8[]PostgreSQL bytea ↔ u8[]MySQL BLOB ↔ u8[]BSON Binary ↔ u8[]
Valores estructuradosNo se admiten como parámetros SQLNo se admiten como parámetros SQLNo se admiten como parámetros SQLLos objetos y arrays anidados se convierten en documentos y arrays BSON, con un límite de 100 niveles y 16 MiB por documento
Fecha y horaInstant de Model se almacena como texto UTCInstant de Model se almacena como TIMESTAMPTZ con precisión de microsegundosInstant de Model se almacena como DATETIME(3) con precisión de milisegundosInstant se convierte en BSON Date con precisión de milisegundos; los valores temporales civiles se convierten en documentos BSON
Identificadores entre comillasComillas dobles; la coincidencia sigue las reglas de identificadores sin distinción entre mayúsculas y minúsculas de SQLiteComillas dobles; los nombres entre comillas conservan mayúsculas y minúsculasLos identificadores entre comillas dobles de Tyrus se convierten en acentos graves; el comportamiento de mayúsculas y minúsculas de los nombres de tabla depende de la configuración del servidorLos nombres de collections y campos provienen de metadatos validados del Model
Inserciones por lotesHasta 500 filas y 999 parámetros enlazadosHasta 500 filas y 999 parámetros enlazadosHasta 500 filas y 999 parámetros enlazadosHasta 500 documentos, cada uno de hasta 16 MiB; no se aplica el límite de parámetros SQL
Resultado de mutaciónLos inserts devuelven recursos, los updates y deletes de un registro devuelven un recurso opcional, y los updates y deletes de varios registros devuelven la cantidad afectadaLos inserts devuelven recursos, los updates y deletes de un registro devuelven un recurso opcional, y los updates y deletes de varios registros devuelven la cantidad afectadaLos inserts devuelven recursos, los updates y deletes de un registro devuelven un recurso opcional, y los updates y deletes de varios registros devuelven la cantidad afectadaLos inserts devuelven documentos, los updates y deletes de un documento devuelven un documento opcional, y los updates y deletes de varios documentos devuelven la cantidad afectada
Ejecución por lotesUna instrucción con varias filas; el backend aplica la atomicidad de la instrucciónUna instrucción con varias filas; el backend aplica la atomicidad de la instrucciónUna instrucción con varias filas; el backend aplica la atomicidad de la instrucciónUna operación por lotes de documentos; el progreso parcial se informa como fallo recuperable de la operación
Paginación numerada y por cursorDisponible; el orden usa @id, y total se lee con la página en una transacciónDisponible; el orden usa @id, y total se lee con la página en una transacción REPEATABLE READDisponible; el orden usa @id, y total se lee con la página en una transacción REPEATABLE READDisponible sobre _id; el recuento y los elementos son lecturas separadas y pueden observar cambios concurrentes
API pública de transaccionesHandles explícitos para db.query; el contexto ORM no está disponibleHandles explícitos para db.query; el contexto ORM no está disponibleHandles explícitos para db.query; el contexto ORM no está disponibleNo disponible
Includes de relacionesAdmitidos, con límites explícitos para coleccionesE3307 durante la compilación; la protección del runtime devuelve ERR_DB_FEATURE_UNSUPPORTEDE3307 durante la compilación; la protección del runtime devuelve ERR_DB_FEATURE_UNSUPPORTEDNo admitidos; E3307 durante la compilación
Introspección del schema y comandos de migraciónIntrospección, generación, estado y aplicaciónGeneración inicial del Model, tablas nuevas, columnas aditivas seguras, valores predeterminados literales, constraints únicas, claves foráneas opcionales tras validar la compatibilidad, archivos SQL manuales, introspección, estado y aplicaciónGeneración inicial del Model, tablas nuevas, columnas aditivas seguras, valores predeterminados literales, constraints únicas, claves foráneas opcionales tras validar la compatibilidad, archivos SQL manuales, introspección, estado y aplicaciónCrea collections inexistentes con validadores derivados del Model en la primera inserción; las collections existentes permanecen intactas; sin introspección ni comandos de migración

Los drivers SQL devuelven DbError para tipos nativos de resultado fuera de las correspondencias admitidas de booleano, entero, punto flotante, texto y binario. db.query usa marcadores ? en el código fuente en todos los backends SQL; el runtime solo reescribe la forma de PostgreSQL. Los backends SQL aplican el mismo límite conservador de 999 parámetros por instrucción y el máximo de 500 filas por lote. MongoDB no tiene una ruta de consulta SQL y aplica sus propios límites BSON, de anidamiento y de 500 documentos por lote.