Конфигурация

Конфигурация подключения к базе данных в Bitrix Framework хранится в файле /bitrix/.settings.php в секции connections.

'connections' => [
            'value' => [
                // Основное соединение с базой данных
                'default' => [
                    'className' => \Bitrix\Main\DB\MysqliConnection::class, // Используем драйвер MySQLi для соединения
                    'host' => 'localhost', // Хост базы данных
                    'database' => 'bx', // Имя базы данных
                    'login' => 'db_user', // Имя пользователя БД
                    'password' => '***', // Пароль пользователя 
                    'options' => 2, // Дополнительные опции соединения (2 — отложенное соединение)
                ],
            ],
            'readonly' => true, // Запрещает изменение настроек во время выполнения скрипта
        ],

Установите параметр readonly => true для секции connections, чтобы предотвратить изменение настроек подключения во время работы.

Классы для работы с базой данных

Параметр className определяет класс для работы с базой данных.

Основные СУБД:

MySQL — \Bitrix\Main\DB\MysqliConnection, требует расширение mysqli,
PostgreSQL — \Bitrix\Main\DB\PgsqlConnection, требует расширение pgsql .

Дополнительные СУБД:

MS SQL — \Bitrix\Main\DB\MssqlConnection, требует расширение sqlsrv,
Oracle — \Bitrix\Main\DB\OracleConnection, требует расширение oci8.

Key-value хранилища:

Memcache — \Bitrix\Main\Data\MemcacheConnection, требует расширение memcache,
Memcached — \Bitrix\Main\Data\MemcachedConnection, требует расширение memcached,
Redis — \Bitrix\Main\Data\RedisConnection, требует расширение redis,
HandlerSocket — \Bitrix\Main\Data\HsphpReadConnection, требует библиотеку HSPHP.

Режимы подключения

Параметр options управляет режимом подключения к базе данных. Принимает числовые флаги:

1 (Connection::PERSISTENT) — постоянное соединение, не закрывается после выполнения запроса,
2 (Connection::DEFERRED) — отложенное соединение, устанавливается только при первом запросе.

Флаги можно объединять через битовые операции:

3 = 1 | 2 — PERSISTENT + DEFERRED,
0 — обычное соединение, без специальных режимов.

Добавить дополнительное соединение

Чтобы добавить дополнительное соединение с базой данных, дополните секцию connections в файле конфигурации /bitrix/.settings.php.

'connections' => [
            'value' => [
                // Основное соединение с базой данных
                'default' => [
                    'className' => \Bitrix\Main\DB\MysqliConnection::class,
                    'host' => 'localhost',
                    'database' => 'bx',
                    'login' => 'db_user',
                    'password' => '***',
                    'options' => 2,
                ],
                
                // Дополнительное соединение с Redis для кеширования
                'redis' => [
                    'className' => \Bitrix\Main\Data\RedisConnection::class, // Используем расширение Redis
                    'host' => 'redis', // Хост Redis сервера
                    'port' => 12345, // Порт для подключения к Redis
                ],
            ],
            'readonly' => true,
        ],

Чтобы получить конкретное подключение в коде, укажите его название в методе Application::getConnection.

// Получить подключение по умолчанию default
        $db = \Bitrix\Main\Application::getConnection();
        
        // Получить конкретное подключение
        $db = \Bitrix\Main\Application::getConnection('default');
        $redis = \Bitrix\Main\Application::getConnection('redis');

Подключить key-value хранилище

Memcache

Класс подключения — \Bitrix\Main\Data\MemcacheConnection.

'memcache' => [
            'className' => \Bitrix\Main\Data\MemcacheConnection::class,
            'host' => '127.0.0.1',
            'port' => 11211,
            'persistent' => true,
            'connectionTimeout' => 1,
        ],

host — хост сервера. По умолчанию имеет значение localhost.
port — порт сервера. По умолчанию имеет значение 11211.
connectionTimeout — таймаут подключения в секундах.
persistent — использовать постоянное соединение pconnect. По умолчанию true.

Чтобы подключить кластер, вместо host и port укажите параметр servers — массив серверов. Каждый элемент может содержать параметры host, port и weight. По умолчанию weight имеет значение 1.

'memcache.cluster' => [
            'className' => \Bitrix\Main\Data\MemcacheConnection::class,
            'servers' => [
                ['host' => '10.0.0.10', 'port' => 11211, 'weight' => 2],
                ['host' => '10.0.0.11', 'port' => 11211, 'weight' => 1],
            ],
            'persistent' => true,
            'connectionTimeout' => 1,
        ],

Memcached

Класс подключения — \Bitrix\Main\Data\MemcachedConnection.

host — хост сервера. По умолчанию имеет значение localhost.
port — порт сервера. По умолчанию имеет значение 11211.
persistent — использовать постоянный идентификатор bx_cache. По умолчанию true.
connectionTimeout — таймаут подключения в миллисекундах. По умолчанию 1000.
serializer — сериализатор Memcached::OPT_SERIALIZER. Например, \Memcached::SERIALIZER_PHP.

'memcached' => [
            'className' => \Bitrix\Main\Data\MemcachedConnection::class,
            'host' => '127.0.0.1',
            'port' => 11211,
            'persistent' => true,
            'connectionTimeout' => 1000,
            'serializer' => \Memcached::SERIALIZER_PHP,
        ],

'memcached.cluster' => [
            'className' => \Bitrix\Main\Data\MemcachedConnection::class,
            'servers' => [
                ['host' => '10.0.0.20', 'port' => 11211, 'weight' => 1],
                ['host' => '10.0.0.21', 'port' => 11211, 'weight' => 1],
            ],
            'persistent' => true,
            'connectionTimeout' => 1000,
            'serializer' => \Memcached::SERIALIZER_PHP,
        ],

Redis

Класс подключения — \Bitrix\Main\Data\RedisConnection.

host — хост сервера. По умолчанию имеет значение localhost.
port — порт сервера. По умолчанию имеет значение 6379.
password — пароль для аутентификации. Доступен с версии main 25.800.0.
persistent — использовать постоянное соединение pconnect для одиночного сервера или подключение persistent в кластере.
timeout — таймаут подключения в секундах.
readTimeout — таймаут чтения в секундах.
serializer — сериализатор, опция Redis::OPT_SERIALIZER. Значение задается константой класса Redis. По умолчанию SERIALIZER_PHP или SERIALIZER_IGBINARY, если доступен.
compression — тип компрессии, опция Redis::OPT_COMPRESSION. Значение задается константой класса Redis, например, COMPRESSION_LZ4, COMPRESSION_ZSTD.
compression_level — уровень компрессии, опция Redis::OPT_COMPRESSION_LEVEL. Целое число, для разных типов компрессии определены свои константы.
failover — политика failover для кластера, опция RedisCluster::OPT_SLAVE_FAILOVER. Применяется, если указано несколько серверов. Значение задается константой класса RedisCluster.

'redis' => [
            'className' => \Bitrix\Main\Data\RedisConnection::class,
            'host' => '127.0.0.1',
            'port' => 6379,
            'password' => 'secret',
            'persistent' => true,
            'timeout' => 1.5,
            'readTimeout' => 1.0,
            'serializer' => \Redis::SERIALIZER_IGBINARY,
            'compression' => \Redis::COMPRESSION_LZ4,
            'compression_level' => \Redis::COMPRESSION_ZSTD_MAX,
        ],

Про варианты значений для параметров serializer, persistent, failover, timeout, read_timeout можно прочитать в официальной документации расширения redis.

Чтобы подключить кластер, вместо host и port укажите параметр servers — массив серверов. Каждый элемент может содержать параметры host и port.

'redis.cluster' => [
            'className' => \Bitrix\Main\Data\RedisConnection::class,
            'servers' => [
                ['host' => '10.0.0.30', 'port' => 6379],
                ['host' => '10.0.0.31', 'port' => 6379],
                ['host' => '10.0.0.32', 'port' => 6379],
            ],
            'failover' => \RedisCluster::FAILOVER_DISTRIBUTE,
            'persistent' => true,
            'timeout' => 1.5,
            'readTimeout' => 1.0,
        ],

HandlerSocket

HandlerSocket — это плагин для MySQL, который работает без SQL-запросов. Он снижает нагрузку на сервер и ускоряет обработку данных.

Добавьте указание на HandlerSocket в основное соединение:

'default' => [
            'className' => \Bitrix\Main\DB\MysqliConnection::class,
            'handlersocket' => [
                'read' => 'handlersocket', // Использовать HandlerSocket для чтения
            ],
        ],

Добавьте отдельное соединение для HandlerSocket с указанием хоста и порта:

'handlersocket' => [
            'className' => \Bitrix\Main\Data\HsphpReadConnection::class,
            'host' => 'localhost',  // Хост сервера HandlerSocket
            'port' => 9998,        // Порт для чтения, обычно 9998
        ],

О том, как HandlerSocket ускоряет работу с БД, читайте в статье HandlerSocket.

Консольные команды

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

Конфигурация

Классы для работы с базой данныхКлассы для работы с базой данных

Режимы подключенияРежимы подключения

Добавить дополнительное соединениеДобавить дополнительное соединение

Подключить key-value хранилищеПодключить key-value хранилище

MemcacheMemcache

MemcachedMemcached

RedisRedis

HandlerSocketHandlerSocket