Перейти к основному содержанию

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}
`

Раскрытие списков параметров​

Чтобы преобразовать массив значений в динамический список параметров в шаблонном выражении, оберните массив в функцию. Это особенно полезно для выражений 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-тег автоматически форматирует параметры, что снижает вероятность ошибок.