SqlHelper — экранирование значений и построение SQL

Пространство имен: Bitrix\Main\DB

Модуль: main — подключать отдельно не нужно

Доступно с версии: 12.0.7

Когда использовать

Класс SqlHelper экранирует значения и имена для SQL-запроса и строит SQL-выражения, которые отличаются в MySQL и PostgreSQL. Объект возвращает метод Connection::getSqlHelper, создавать его конструктором не нужно. Класс абстрактный, фактический объект — реализация для типа базы данных, например MysqliSqlHelper или PgsqlSqlHelper.

Многие методы класса подставляют аргументы в SQL как есть. Таблица параметров на странице метода отмечает такие аргументы. Значения, которые приходят извне, сначала экранируйте через forSql или convertToDbString, имена — через quote. Для подстановки значений в шаблон запроса используйте SqlExpression.

Методы класса

Таблицы ниже группируют методы по задачам.

Экранирование и параметры диалекта

Метод Описание С версии
forSql Экранирует строку для подстановки внутри одинарных кавычек
quote Берет имя таблицы или колонки в кавычки идентификатора 14.0.0
getLeftQuote Возвращает символ, которым база данных открывает имя 14.0.0
getRightQuote Возвращает символ, которым база данных закрывает имя 14.0.0
convertToDbBinary Готовит двоичные данные для подстановки в запрос
convertToFullText Готовит текст для колонки с полнотекстовым индексом
getAliasLength Возвращает наибольшую длину псевдонима колонки 14.0.0
getQueryDelimiter Возвращает разделитель запросов в тексте с несколькими запросами

SQL-функции и выражения

Метод Описание С версии
getCurrentDateTimeFunction Возвращает функцию текущих даты и времени
getCurrentDateFunction Возвращает функцию текущей даты
addSecondsToDateTime Строит выражение, которое прибавляет секунды к дате 14.0.0
addDaysToDateTime Строит выражение, которое прибавляет дни к дате
getDatetimeToDateFunction Строит выражение, которое отбрасывает время у даты
formatDate Переводит формат даты Битрикс в формат базы данных 14.0.0
getCharToDateFunction Строит выражение даты из строки YYYY-MM-DD HH:MI:SS 14.0.18
getDateToCharFunction Строит выражение, которое переводит дату в строку 14.0.18
getSubstrFunction Строит выражение подстроки
getConcatFunction Строит выражение, которое склеивает строки
getIsNullFunction Строит выражение, которое заменяет NULL
getLengthFunction Строит выражение длины значения
castToChar Строит выражение, которое приводит значение к строке 16.0.10
softCastTextToChar Возвращает выражение текстовой колонки для группировки и сортировки 16.5.7
getRandomFunction Возвращает функцию случайного числа
getSha1Function Строит выражение хеша SHA-1
getRegexpOperator Строит условие проверки по регулярному выражению
getIlikeOperator Строит условие LIKE без учета регистра
getAscendingOrder Возвращает указание сортировки по возрастанию 14.5.0
getDescendingOrder Возвращает указание сортировки по убыванию 14.5.0
getOrderByStringField Строит сортировку в порядке списка строк
getOrderByIntField Строит сортировку в порядке списка чисел
getConditionalAssignment Строит присваивание с проверкой хеша текущего значения
initRowNumber Возвращает запрос, который готовит нумерацию строк
getRowNumber Строит выражение номера строки
getMatchFunction Строит условие полнотекстового поиска
getMatchAndExpression Собирает строку поиска всех слов
getMatchOrExpression Собирает строку поиска любого слова
values Возвращает ссылку на значение колонки из добавляемой строки

Построение запросов

Метод Описание С версии
getTopSql Добавляет к запросу ограничение по числу строк и смещение 14.0.0
prepareInsert Готовит колонки и значения для INSERT
prepareUpdate Готовит присваивания для UPDATE
prepareAssignment Готовит присваивание одной колонки 14.0.0
prepareMerge Строит вставку строки с обновлением при совпадении ключа 15.5.0
prepareMergeMultiple Строит вставку нескольких строк с заменой при совпадении ключа
prepareMergeSelect Строит вставку из выборки с обновлением при совпадении ключа
prepareMergeValues Строит вставку нескольких строк с обновлением при совпадении ключа
prepareDeleteLimit Строит удаление с ограничением по числу строк
prepareCorrelatedUpdate Строит обновление со значениями из других таблиц
getInsertIgnore Строит вставку, которая пропускает строки с существующим ключом
getQueryTables Возвращает имена таблиц из текста запроса

Преобразование значений

Метод Описание С версии
convertToDb Преобразует значение в литерал SQL по типу поля ORM 14.5.2
convertFromDb Преобразует значение из базы данных по типу поля ORM 14.5.2
convertToDbInteger Приводит значение к целому числу в пределах колонки
convertFromDbInteger Приводит значение из базы данных к целому числу
convertToDbFloat Приводит значение к дробному числу для SQL
convertFromDbFloat Приводит значение из базы данных к дробному числу
convertToDbString Экранирует строку и берет ее в кавычки
convertFromDbString Приводит значение из базы данных к строке
convertToDbText Экранирует текст и берет его в кавычки
convertFromDbText Приводит значение текстовой колонки к строке
convertToDbDate Превращает объект даты в литерал SQL
convertFromDbDate Превращает дату из базы данных в объект Date
convertToDbDateTime Превращает объект даты и времени в литерал SQL
convertFromDbDateTime Превращает дату и время из базы данных в объект DateTime
getConverter Возвращает функцию преобразования значения колонки при выборке 15.0.1

Типы колонок

Метод Описание С версии
getColumnTypeByField Возвращает тип колонки для поля ORM 14.5.2
getFieldByColumnType Создает поле ORM по типу колонки 14.5.2
isBigType Проверяет, относится ли тип колонки к большим

Наследование

Реализации

Класс Тип базы данных Собственные методы
MysqliSqlHelper MySQL Нет
PgsqlSqlHelper PostgreSQL Нет

Что реализовать в наследнике

Наследник реализует абстрактные методы getAliasLength, getQueryDelimiter, forSql, getCurrentDateTimeFunction, getCurrentDateFunction, addSecondsToDateTime, getDatetimeToDateFunction, formatDate, getConcatFunction, getIsNullFunction, getLengthFunction, getCharToDateFunction, getDateToCharFunction, castToChar, softCastTextToChar, getTopSql, prepareMerge, getColumnTypeByField и getFieldByColumnType.

Еще 14 методов базовый класс объявляет обычными, но они выбрасывают NotImplementedException. Наследник переопределяет их, если код использует эти возможности. Это addDaysToDateTime, getInsertIgnore, getRegexpOperator, getIlikeOperator, values, getMatchFunction, getMatchAndExpression, getMatchOrExpression, prepareMergeMultiple, prepareMergeSelect, prepareDeleteLimit, initRowNumber, getRowNumber и prepareCorrelatedUpdate.

Смотрите также

Предыдущая
Следующая