SQL 标签
非官方测试版翻译
本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →
TypeORM 提供了一种使用模板字面量编写 SQL 查询的方法，它会根据您的数据库类型自动处理参数。该功能有助于防止 SQL 注入，同时提升查询可读性。SQL 标签本质上是 .query 方法的封装器，在保持相同底层功能的同时提供了更便捷的接口。
基本用法
sql 标签可在 DataSource、EntityManager、Repository 和 QueryRunner 实例上使用：
const users = await dataSource.sql`SELECT * FROM users WHERE name = ${"John"}`
参数处理
系统会根据您的数据库类型自动转义和格式化参数：
- PostgreSQL、CockroachDB、Aurora PostgreSQL 使用
$1,$2等占位符：
// 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 使用
?占位符：
// Query becomes: SELECT * FROM users WHERE name = ?
const users = await dataSource.sql`SELECT * FROM users WHERE name = ${"John"}`
- Oracle 使用
:1,:2等占位符：
// Query becomes: SELECT * FROM users WHERE name = :1
const users = await dataSource.sql`SELECT * FROM users WHERE name = ${"John"}`
- MSSQL 使用
@1,@2等占位符：
// Query becomes: SELECT * FROM users WHERE name = @1
const users = await dataSource.sql`SELECT * FROM users WHERE name = ${"John"}`
多参数处理
您可以同时使用多个参数和复杂表达式：
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}
`
参数列表展开
若需将值数组转换为模板表达式中的动态参数列表，请将数组包裹在函数中。这在编写 SQL 的 IN (...) 表达式时特别有用，因为列表中的每个值都必须作为独立参数传递：
// Query becomes: SELECT * FROM users WHERE id IN (?, ?, ?)
const users = await dataSource.sql`
SELECT * FROM users
WHERE id IN (${() => [1, 2, 3]})
`
非转义表达式插值
当您需要插入_不应_转换为数据库参数的模板表达式时，请将字符串包裹在函数中。这适用于动态定义无法参数化的列名/表名/模式名，或根据条件动态设置 SQL 子句：
注意！ 此方式插入的原始 SQL 不会进行转义处理。切勿将用户输入的值用于此操作，否则存在安全风险。
// Query becomes: SELECT * FROM dynamic_table_name
const rawData = await dataSource.sql`
SELECT * FROM ${() => "dynamic_table_name"}
`
特性
-
防止 SQL 注入：参数会被正确转义
-
数据库无关性：参数格式化会根据您的数据库类型自动处理
-
提升查询可读性：模板字面量使查询比参数数组更易读
与 query 方法对比
传统 query 方法需要手动处理参数占位符：
// 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}`
SQL 标签自动处理参数格式化，能有效减少潜在错误。