Класс yii\db\Connection

Connection представляет собой соединение с базой данных через PDO.

Connection работает вместе с yii\db\Command, yii\db\DataReader и yii\db\Transaction, чтобы предоставить доступ к данным различных СУБД в рамках общего набора API. Они являются тонким обертыванием расширения PDO PHP.

Connection поддерживает репликацию базы данных и разделение чтений и записей. В частности, компонент Connection может быть настроен с несколькими $masters и $slaves. Он будет выполнять балансировку нагрузки и резервирование, выбирая подходящие серверы. Он также автоматически будет направлять операции чтения на серверы-слепки, а записи — на мастер-серверы.

Для создания соединения с БД установите $dsn, $username и $password, а затем вызовите open() для подключения к серверу базы данных. Текущее состояние соединения можно проверить с помощью $isActive.

Следующий пример демонстрирует создание экземпляра Connection и установление соединения с БД:

$connection = new \yii\db\Connection([
    'dsn' => $dsn,
    'username' => $username,
    'password' => $password,
]);
$connection->open();

После установления соединения с БД можно выполнять SQL-запросы, например, такие:

$command = $connection->createCommand('SELECT * FROM post');
$posts = $command->queryAll();
$command = $connection->createCommand('UPDATE post SET status=1');
$command->execute();

Также можно выполнять подготовленные SQL-запросы и привязывать параметры к подготовленному SQL. При получении параметров из пользовательского ввода следует использовать этот подход, чтобы предотвратить атаки SQL-инъекции. Пример:

$command = $connection->createCommand('SELECT * FROM post WHERE id=:id');
$command->bindValue(':id', $_GET['id']);
$post = $command->query();

Дополнительную информацию о выполнении различных запросов к БД см. в yii\db\Command.

Если основная СУБД поддерживает транзакции, вы можете выполнять транзакционные SQL-запросы, как в примере:

$transaction = $connection->beginTransaction();
try {
    $connection->createCommand($sql1)->execute();
    $connection->createCommand($sql2)->execute();
    // ... executing other SQL statements ...
    $transaction->commit();
} catch (Exception $e) {
    $transaction->rollBack();
}

Вы также можете использовать сокращение для вышеизложенного, например:

$connection->transaction(function () {
    $order = new Order($customer);
    $order->save();
    $order->addItems($items);
});

При необходимости можно передать уровень изоляции транзакции как второй параметр:

$connection->transaction(function (Connection $db) {
    //return $db->...
}, Transaction::READ_UNCOMMITTED);

Компонент Connection часто используется как компонент приложения и настраивается в конфигурации приложения следующим образом:

'components' => [
    'db' => [
        'class' => '\yii\db\Connection',
        'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
        'username' => 'root',
        'password' => '',
        'charset' => 'utf8',
    ],
],

Общедоступные свойства

Публичные методы

Защищенные методы

События

Подробное описание свойств

$attributes открытое свойство

Атрибуты PDO (имя => значение), которые должны быть установлены при вызове open() для установления подключения к БД. Подробнее об имеющихся атрибутах см. в документации PHP.

public array $attributes = null

$charset открытое свойство

Кодировка, используемая для подключения к базе данных. Свойство используется только для баз данных MySQL, PostgreSQL и CUBRID. По умолчанию равно null, что означает использование кодировки по умолчанию, настроенной в базе данных.

Для Oracle Database кодировка должна быть указана в $dsn, например, для UTF-8, добавив ;charset=UTF-8 к строке DSN.

То же самое относится к использованию кодировки GBK или BIG5 с MySQL, рекомендуется указывать кодировку через $dsn, например 'mysql:dbname=mydatabase;host=127.0.0.1;charset=GBK;'.

public string $charset = null

$commandClass открытое свойство (доступно начиная с версии 2.0.7)

Класс, используемый для создания новых объектов базы данных yii\db\Command. Если вы хотите расширить класс yii\db\Command, вы можете настроить это свойство для использования вашей расширенной версии класса.

См. также createCommand().

public string $commandClass = 'yii\db\Command'

$driverName открытое свойство

Имя драйвера БД

public string getDriverName ( )
public void setDriverName ( $driverName )

$dsn открытое свойство

Идентификатор источника данных (DSN) содержит информацию, необходимую для подключения к базе данных. Обратитесь к документации PHP для получения подробной информации о формате строки DSN.

Для SQLite можно использовать псевдоним пути для указания пути к базе данных, например sqlite:@app/data/db.sql.

См. также $charset.

public string $dsn = null

$emulatePrepare открытое свойство

Включает эмуляцию подготовки. По умолчанию false, что означает, что PDO будет использовать поддержку native prepare, если она доступна. Для некоторых баз данных (таких как MySQL) может потребоваться установить это значение в true, чтобы PDO мог эмулировать поддержку prepare, минуя ошибочную поддержку native prepare. Значение по умолчанию null, что означает, что значение PDO ATTR_EMULATE_PREPARES не будет изменено.

public boolean $emulatePrepare = null

$enableLogging открытое свойство (доступно начиная с версии 2.0.12)

Включает протоколирование запросов к базе данных. По умолчанию true. В среде производства может быть выгодно отключить эту опцию для повышения производительности, если информация, записываемая в лог, не нужна.

См. также $enableProfiling.

public boolean $enableLogging = true

$enableProfiling открытое свойство (доступно начиная с версии 2.0.12)

Включает профилирование запросов к базе данных. По умолчанию true. В среде производства может быть выгодно отключить эту опцию для повышения производительности, если информация, записываемая в лог, не нужна.

См. также $enableLogging.

public boolean $enableProfiling = true

$enableQueryCache открытое свойство

Включает кэширование запросов. Обратите внимание, что для включения кэширования запросов необходимо включить соответствующий компонент кэша, указанный в $queryCache, и установить $enableQueryCache в true. Также, кэшируются только результаты запросов, заключённых в cache().

См. также:

• $queryCache
• cache()
• noCache()

public boolean $enableQueryCache = true

$enableSavepoint открытое свойство

Включает использование savepoint. Обратите внимание, что если базовая СУБД не поддерживает savepoint, установка этого свойства в true не повлияет.

public boolean $enableSavepoint = true

$enableSchemaCache открытое свойство

Включает кэширование схемы. Обратите внимание, что для включения кэширования схемы необходимо включить соответствующий компонент кэша, указанный в $schemaCache, и установить $enableSchemaCache в true.

См. также:

• $schemaCacheDuration
• $schemaCacheExclude
• $schemaCache

public boolean $enableSchemaCache = false

$enableSlaves открытое свойство

Включает разделение чтения/записи с использованием $slaves для чтения данных. Обратите внимание, что если $slaves пусто, разделение чтения/записи НЕ будет включено независимо от значения этого свойства.

public boolean $enableSlaves = true

$isActive открытое только для чтения свойство

Установлено ли подключение к БД

public boolean getIsActive ( )

$lastInsertID открытое только для чтения свойство

Идентификатор строки последней вставленной строки или последнее значение, полученное из объекта последовательности

public string getLastInsertID ( $sequenceName = '' )

$master открытое только для чтения свойство

Текущее активное мастер-соединение. null возвращается, если мастер-соединение недоступно.

public yii\db\Connection getMaster ( )

$masterConfig открытое свойство

Настройка, которая должна быть объединена с каждой настройкой master, указанной в $masters. Например,

[
    'username' => 'master',
    'password' => 'master',
    'attributes' => [
        // use a smaller connection timeout
        PDO::ATTR_TIMEOUT => 10,
    ],
]

public array $masterConfig = []

$masterPdo открытое только для чтения свойство

Экземпляр PDO для текущего активного мастер-соединения.

public PDO getMasterPdo ( )

$masters открытое свойство

Список настроек мастер-соединения. Каждая настройка используется для создания мастер-соединения к БД. При вызове open() будет выбран один из этих конфигураций и использован для создания подключения к БД, которое будет использоваться этим объектом. Обратите внимание, что когда это свойство не пустое, настройки подключения (например, "dsn", "username") этого объекта будут игнорироваться.

См. также:

• $masterConfig
• $shuffleMasters

public array $masters = []

$password открытое свойство

Пароль для установления подключения к БД. По умолчанию null, что означает отсутствие пароля.

public string $password = null

$pdo открытое свойство

Экземпляр PHP PDO, связанный с этим подключением к БД. Это свойство в основном управляется методами open() и close(). Когда подключение к БД активно, это свойство будет представлять экземпляр PDO; в противном случае оно будет null.

См. также $pdoClass.

public PDO $pdo = null

$pdoClass открытое свойство

Пользовательский класс PDO. Если не задано, он будет использовать PDO или yii\db\mssql\PDO при использовании MSSQL.

См. также $pdo.

public string $pdoClass = null

$queryBuilder public только для чтения свойство

Построитель запросов для текущего подключения к БД.

public yii\db\QueryBuilder getQueryBuilder ( )

$queryCache public свойство

Объект кэша или идентификатор компонента приложения кэша, используемого для кэширования запросов.

См. также $enableQueryCache.

public yii\caching\CacheInterface|string $queryCache = 'cache'

$queryCacheDuration public свойство

Установленное значение по умолчанию в секундах, в течение которого результаты запросов могут оставаться действительными в кэше. По умолчанию равно 3600, что означает 3600 секунд, или один час. Используйте 0, чтобы указать, что кэшированные данные никогда не истекут. Значение этого свойства будет использоваться, когда вызов cache() не содержит параметра для определения времени жизни кэша.

См. также:

• $enableQueryCache
• cache()

public integer $queryCacheDuration = 3600

$schema public только для чтения свойство

Информация о схеме базы данных, открытой этим подключением.

public yii\db\Schema getSchema ( )

$schemaCache public свойство

Объект кэша или идентификатор компонента приложения кэша, используемого для кэширования метаданных таблиц.

См. также $enableSchemaCache.

public yii\caching\CacheInterface|string $schemaCache = 'cache'

$schemaCacheDuration public свойство

Количество секунд, в течение которого метаданные таблиц могут оставаться действительными в кэше. Используйте 0, чтобы указать, что кэшированные данные никогда не истекут.

См. также $enableSchemaCache.

public integer $schemaCacheDuration = 3600

$schemaCacheExclude public свойство

Список таблиц, метаданные которых НЕ должны кэшироваться. По умолчанию пустой массив. Имена таблиц могут содержать префикс схемы, если он есть. Не заключайте имена таблиц в кавычки.

См. также $enableSchemaCache.

public array $schemaCacheExclude = []

$schemaMap public свойство

Сопоставление между именами драйверов PDO и классами yii\db\Schema. Ключи массива — имена драйверов PDO, а значения — соответствующее имя класса схемы или конфигурация. Обратитесь к Yii::createObject() для получения подробностей о том, как указать конфигурацию.

Это свойство в основном используется getSchema() при получении информации о схеме базы данных. Вам обычно не нужно устанавливать это свойство, если вы не хотите использовать свой собственный класс yii\db\Schema для поддержки СУБД, которая не поддерживается Yii.

public array $schemaMap = ['pgsql' => 'yii\db\pgsql\Schema', 'mysqli' => 'yii\db\mysql\Schema', 'mysql' => 'yii\db\mysql\Schema', 'sqlite' => 'yii\db\sqlite\Schema', 'sqlite2' => 'yii\db\sqlite\Schema', 'sqlsrv' => 'yii\db\mssql\Schema', 'oci' => 'yii\db\oci\Schema', 'mssql' => 'yii\db\mssql\Schema', 'dblib' => 'yii\db\mssql\Schema', 'cubrid' => 'yii\db\cubrid\Schema']

$serverRetryInterval public свойство

Интервал повтора в секундах для серверов, отмеченных как неисправные в списках $masters и $slaves. Используется совместно с $serverStatusCache.

public integer $serverRetryInterval = 600

$serverStatusCache public свойство

Объект кэша или идентификатор компонента приложения кэша, который используется для хранения состояния работоспособности серверов БД, указанных в $masters и $slaves. Используется только при включенном разделении чтение/запись или если $masters не пустое.

public yii\caching\CacheInterface|string $serverStatusCache = 'cache'

$shuffleMasters public свойство (доступно начиная с версии 2.0.11)

Следует ли перемешивать список $masters перед выбором одного сервера?

См. также $masters.

public boolean $shuffleMasters = true

$slave public только для чтения свойство

Текущее активное подключение к резервному серверу. null возвращается, если нет доступных резервных серверов и $fallbackToMaster равно false.

public yii\db\Connection getSlave ( $fallbackToMaster = true )

$slaveConfig public свойство

Конфигурация, которая должна быть объединена с каждой конфигурацией резервного сервера, перечисленной в $slaves. Например,

[
    'username' => 'slave',
    'password' => 'slave',
    'attributes' => [
        // use a smaller connection timeout
        PDO::ATTR_TIMEOUT => 10,
    ],
]

public array $slaveConfig = []

$slavePdo public только для чтения свойство

Экземпляр PDO для текущего активного подключения к резервному серверу. null возвращается, если нет доступных резервных подключений и $fallbackToMaster равно false.

public PDO getSlavePdo ( $fallbackToMaster = true )

$slaves public свойство

Список конфигураций подключений к резервным серверам. Каждая конфигурация используется для создания резервного подключения к БД. При $enableSlaves равно true, одна из этих конфигураций будет выбрана и использована для создания подключения к БД для выполнения только запросов чтения.

См. также:

• $enableSlaves
• $slaveConfig

public array $slaves = []

$tablePrefix public свойство

Общий префикс или суффикс для имён таблиц. Если имя таблицы задано как {{%TableName}}, символ процента % будет заменён значением этого свойства. Например, {{%post}} преобразуется в {{tbl_post}}.

public string $tablePrefix = ''

$transaction public только для чтения свойство

Текущая активная транзакция. Null, если нет активной транзакции.

public yii\db\Transaction getTransaction ( )

$username public свойство

Имя пользователя для установления подключения к БД. По умолчанию null, что означает отсутствие имени пользователя.

public string $username = null

Подробное описание методов

// The customer will be fetched from cache if available.
// If not, the query will be made against DB and cached for use next time.
$customer = $db->cache(function (Connection $db) {
    return $db->createCommand('SELECT * FROM customer WHERE id=1')->queryOne();
});

$db->cache(function (Connection $db) {

    // ... queries that use query cache ...

    return $db->noCache(function (Connection $db) {
        // this query will not use query cache
        return $db->createCommand('SELECT * FROM customer WHERE id=1')->queryOne();
    });
});

$result = $db->useMaster(function ($db) {
    return $db->createCommand('SELECT * FROM user LIMIT 1')->queryOne();
});

Подробное описание событий