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.