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.