Etiqueta SQL

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

TypeORM ofrece una forma de escribir consultas SQL usando literales de plantilla con manejo automático de parámetros según tu tipo de base de datos. Esta característica ayuda a prevenir inyecciones SQL mientras hace las consultas más legibles. La etiqueta SQL se implementa como un envoltorio del método .query, proporcionando una interfaz alternativa manteniendo la misma funcionalidad subyacente.

Uso básico

La etiqueta sql está disponible en instancias de DataSource, EntityManager, Repository y QueryRunner:

const users = await dataSource.sql`SELECT * FROM users WHERE name = ${"John"}`

Manejo de parámetros

Los parámetros se escapan y formatean automáticamente según tu tipo de base de datos:

PostgreSQL, CockroachDB, Aurora PostgreSQL usan $1, $2, etc.:

// Query becomes: SELECT * FROM users WHERE name = $1
const users = await dataSource.sql`SELECT * FROM users WHERE name = ${"John"}`

MySQL, MariaDB, Aurora MySQL, SAP, SQLite usan ?:

// Query becomes: SELECT * FROM users WHERE name = ?
const users = await dataSource.sql`SELECT * FROM users WHERE name = ${"John"}`

Oracle usa :1, :2, etc.:

// Query becomes: SELECT * FROM users WHERE name = :1
const users = await dataSource.sql`SELECT * FROM users WHERE name = ${"John"}`

MSSQL usa @1, @2, etc.:

// Query becomes: SELECT * FROM users WHERE name = @1
const users = await dataSource.sql`SELECT * FROM users WHERE name = ${"John"}`

Múltiples parámetros

Puedes usar múltiples parámetros y expresiones complejas:

const name = "John"
const age = 30
const active = true
const users = await dataSource.sql`
    SELECT * FROM users
    WHERE name LIKE ${name + "%"}
    AND age > ${age}
    AND is_active = ${active}
`

Expansión de listas de parámetros

Para transformar un array de valores en una lista dinámica de parámetros, envuelve el array en una función. Esto se usa comúnmente para expresiones IN (...) en SQL, donde cada valor debe suministrarse como parámetro separado:

// Query becomes: SELECT * FROM users WHERE id IN (?, ?, ?)
const users = await dataSource.sql`
    SELECT * FROM users
    WHERE id IN (${() => [1, 2, 3]})
`

Interpolación de expresiones sin escape

Cuando necesites insertar una expresión de plantilla que no deba transformarse en parámetro, envuelve el string en una función. Útil para definir nombres de columnas, tablas o esquemas dinámicamente, o para establecer cláusulas condicionales en SQL.

¡Precaución! No se aplica escape al SQL insertado así. No es seguro usarlo con valores provenientes de entrada de usuario.

// Query becomes: SELECT * FROM dynamic_table_name
const rawData = await dataSource.sql`
    SELECT * FROM ${() => "dynamic_table_name"}
`

Características

Prevención de inyección SQL: Los parámetros se escapan correctamente
Independiente de la base de datos: El formato de parámetros se maneja según tu tipo de base de datos
Consultas legibles: Los literales de plantilla hacen las consultas más legibles que los arrays de parámetros

Comparación con el método Query

El método tradicional query requiere manejo manual de marcadores de posición:

// Traditional query method
await dataSource.query("SELECT * FROM users WHERE name = $1 AND age > $2", [
    "John",
    30,
])

// SQL tag alternative
await dataSource.sql`SELECT * FROM users WHERE name = ${"John"} AND age > ${30}`

La etiqueta SQL maneja el formato de parámetros automáticamente, reduciendo errores potenciales.

Uso básico​

Manejo de parámetros​

Múltiples parámetros​

Expansión de listas de parámetros​

Interpolación de expresiones sin escape​

Características​

Comparación con el método Query​