Connection — соединение с базой данных

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

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

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

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

Класс Connection описывает соединение с базой данных. Объект соединения возвращает Application::getConnection(), создавать его конструктором не нужно. Класс абстрактный, фактический объект — реализация для типа базы данных, например MysqliConnection или PgsqlConnection.

К соединению обращаются, когда нужен SQL-запрос напрямую, транзакция, именованная блокировка или изменение структуры таблицы. Для чтения и записи данных ORM-классов используйте методы DataManager. Значения для SQL экранируйте через объект, который возвращает getSqlHelper.

Аналог в классическом API — глобальный объект $DB класса CDatabase.

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

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

Параметры соединения

Метод Описание С версии
getHost Возвращает адрес сервера базы данных из настроек соединения
getLogin Возвращает имя пользователя базы данных из настроек соединения
getDatabase Возвращает имя базы данных из настроек соединения
isDeferred Проверяет, откладывает ли соединение подключение до первого запроса
isPersistent Проверяет, использует ли соединение постоянное подключение
isUtf8mb4 Проверяет, включена ли в настройках соединения кодировка utf8mb4 для таблицы или колонки
setNodeId Задает идентификатор узла кластера для соединения 15.0.1
getNodeId Возвращает идентификатор узла кластера 15.0.1
getType Возвращает тип базы данных 14.0.0
getVersion Возвращает версию сервера базы данных 14.0.0
getSqlHelper Возвращает объект для экранирования значений и построения SQL под тип базы данных 14.0.0

Выполнение запросов

Метод Описание С версии
query Выполняет SQL-запрос и возвращает результат 14.0.0
queryScalar Выполняет запрос и возвращает значение первой колонки первой строки 14.0.0
queryExecute Выполняет запрос без возврата результата 14.0.0
executeSqlBatch Выполняет несколько запросов из одного текста и возвращает ошибки 14.0.0
parseSqlBatch Разбивает текст с несколькими запросами на отдельные запросы
getAffectedRowsCount Возвращает число строк, которые изменил последний запрос 14.0.0
getErrorMessage Возвращает сообщение об ошибке последней операции с базой данных
getErrorCode Возвращает код ошибки последней операции с базой данных
disableQueryExecuting Отключает выполнение запросов и включает сбор их текста 14.5.1
enableQueryExecuting Снова включает выполнение запросов 14.5.1
isQueryExecutingEnabled Проверяет, выполняет ли соединение запросы
getDisabledQueryExecutingDump Возвращает собранные запросы и очищает список 14.5.1

Добавление строк

Метод Описание С версии
add Добавляет строку в таблицу и возвращает ее идентификатор 14.0.0
addMulti Добавляет несколько строк одним запросом
getInsertedId Возвращает идентификатор последней добавленной строки

Структура таблиц

Метод Описание С версии
isTableExists Проверяет, есть ли таблица в базе данных 14.0.0
getTableFields Возвращает описание колонок таблицы объектами полей ORM 14.0.0
getTableField Возвращает описание одной колонки таблицы 14.0.0
createTable Создает таблицу по описанию полей ORM
renameTable Переименовывает таблицу 14.0.4
truncateTable Удаляет все строки таблицы 15.0.4
dropTable Удаляет таблицу 14.5.1
dropColumn Удаляет колонку таблицы 14.5.1
isIndexExists Проверяет, есть ли индекс по колонкам 14.0.0
getIndexName Возвращает имя индекса по колонкам 14.0.0
createIndex Создает индекс 14.9.4
createPrimaryIndex Создает первичный ключ таблицы 14.5.1
clearCaches Очищает кеш описания колонок 14.0.0

Транзакции и блокировки

Метод Описание С версии
startTransaction Начинает транзакцию или создает точку сохранения во вложенной транзакции 14.0.0
commitTransaction Фиксирует транзакцию 14.0.0
rollbackTransaction Откатывает транзакцию 14.0.0
lock Устанавливает именованную блокировку
unlock Снимает именованную блокировку

Отслеживание запросов

Метод Описание С версии
startTracker Включает сбор сведений о запросах 14.0.0
stopTracker Выключает сбор сведений о запросах 14.0.0
getTracker Возвращает объект со сведениями о запросах 14.0.0
setTracker Задает объект для сбора сведений о запросах 14.9.4

Константы

Константа Значение Описание
PERSISTENT 1 Флаг постоянного подключения в ключе options настроек соединения
DEFERRED 2 Флаг отложенного подключения в ключе options настроек соединения
INDEX_UNIQUE 'UNIQUE' Тип уникального индекса для createIndex
INDEX_FULLTEXT 'FULLTEXT' Тип полнотекстового индекса для createIndex
INDEX_SPATIAL 'SPATIAL' Тип пространственного индекса для createIndex. В PostgreSQL метод создает обычный индекс

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

Класс Connection наследует абстрактный класс Bitrix\Main\Data\Connection.

Реализация методов базового класса

Метод Особенность реализации
connect Не подключается к базе данных, если подключение отложенное. Отложенное подключение открывается при первом запросе
disconnect Не закрывает постоянное подключение

Унаследованные методы

Методы getResource, isConnected и getConfiguration работают как в классе Bitrix\Main\Data\Connection. Метод getResource подключается к базе данных, если подключения еще нет.

Метод getMaxAllowedPacket работает как в базовом классе только в PgsqlConnection и возвращает PHP_INT_MAX. В MySQL метод читает переменную сервера max_allowed_packet и запоминает значение.

Реализации

Реализация для MySQL состоит из двух классов. Промежуточный абстрактный класс MysqlCommonConnection содержит общую логику MySQL, класс MysqliConnection наследует его и работает через расширение mysqli.

Класс Тип базы данных Собственные методы
MysqliConnection MySQL selectDatabase, а также setStorageEngine из MysqlCommonConnection
PgsqlConnection PostgreSQL getTableFullTextFields, connectionErrorHandler

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

Свой класс соединения наследует Connection и реализует абстрактные методы. Защищенные методы код приложения не вызывает, но наследник обязан их реализовать:

  • createSqlHelper — создает объект SqlHelper для своего типа базы данных,
  • connectInternal и disconnectInternal — открывают и закрывают подключение,
  • queryInternal — выполняет запрос и выбрасывает SqlQueryException при ошибке,
  • createResult — создает объект результата запроса.

Наследник также реализует публичные абстрактные методы getInsertedId, getAffectedRowsCount, isTableExists, isIndexExists, getIndexName, getTableFields, createTable, renameTable, dropTable, startTransaction, commitTransaction, rollbackTransaction, getType, getVersion и getErrorMessage.

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

Следующая