Class yii\db\Connection

继承yii\db\Connection » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/db/Connection.php

Connection 表示通过 PDO 与数据库的连接.

Connection 与 yii\db\Command, yii\db\DataReaderyii\db\Transaction 一起使用, 以一组通用的 API 提供对各种 DBMS 的数据访问. 它们是 PHP PDO 扩展 的简单封装.

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.

如果底层 DBMS 支持事务, 则可以执行以下事务性 SQL 查询:

$transaction = $connection->beginTransaction();
try {
    $connection->createCommand($sql1)->execute();
    $connection->createCommand($sql2)->execute();
    // ... 执行其它 SQL 语句 ...
    $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 array 调用 open() 建立数据库连接时, 应设置的 PDO 属性(name => value). yii\db\Connection
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$charset string 用于数据库连接的字符集. yii\db\Connection
$commandClass string 用于创建新数据库 yii\db\Command 对象的类. yii\db\Connection
$commandMap array PDO 驱动程序名称和 yii\db\Command 类之间的映射. yii\db\Connection
$driverName string 数据库驱动程序的名称. yii\db\Connection
$dsn string 数据源名称, 或 DSN, 包含连接到数据库所需的信息. yii\db\Connection
$emulatePrepare boolean 是否打开准备模拟. yii\db\Connection
$enableLogging boolean 是否启用数据库查询日志. yii\db\Connection
$enableProfiling boolean 是否启用对打开数据库连接和数据库查询的分析. yii\db\Connection
$enableQueryCache boolean 是否启用查询缓存. yii\db\Connection
$enableSavepoint boolean 是否启用 [保存点](http://en. yii\db\Connection
$enableSchemaCache boolean 是否启用模式缓存. yii\db\Connection
$enableSlaves boolean 是否通过使用 $slaves 读取数据来启用读/写分离. yii\db\Connection
$isActive boolean 数据库连接是否建立. 该属性是只读的. yii\db\Connection
$isSybase boolean 如果通过pdo_dblib连接的数据库是SyBase. yii\db\Connection
$lastInsertID string 插入的最后一行的行ID, 或从序列对象中检索到的最后一个值. 该属性是只读的. yii\db\Connection
$master yii\db\Connection 当前活动的主连接. 如果没有可用的主服务器, 则返回null. 该属性是只读的. yii\db\Connection
$masterConfig array 应与 $masters 中列出的每个主配置合并的配置. yii\db\Connection
$masterPdo PDO 当前活动的主连接的 PDO 实例. 该属性是只读的. yii\db\Connection
$masters array 主连接配置列表. yii\db\Connection
$password string 建立数据库连接的密码. yii\db\Connection
$pdo PDO 与此数据库连接关联的 PHP PDO 实例. yii\db\Connection
$pdoClass string 自定义 PDO 包装器类. yii\db\Connection
$queryBuilder yii\db\QueryBuilder 当前数据库连接的查询生成器. Note: 此属性的类型在 getter 和 setter 中有所不同. 有关详细信息, 请参阅 getQueryBuilder()setQueryBuilder(). yii\db\Connection
$queryCache yii\caching\CacheInterface|string 缓存对象或用于查询缓存的应用程序缓存组件的ID. yii\db\Connection
$queryCacheDuration integer 查询结果在高速缓存中保持有效的默认秒数. yii\db\Connection
$schema yii\db\Schema 通过此连接打开的数据库的模式信息. 该属性是只读的. yii\db\Connection
$schemaCache yii\caching\CacheInterface|string 缓存对象或用于缓存表元数据的应用程序缓存组件的ID. yii\db\Connection
$schemaCacheDuration integer 表元数据在高速缓存中保持有效的秒数. yii\db\Connection
$schemaCacheExclude array 不应该缓存其元数据的表的列表. yii\db\Connection
$schemaMap array PDO 驱动程序名称和 yii\db\Schema 类之间的映射. yii\db\Connection
$serverRetryInterval integer $masters$slaves 中列出的失效服务器的重试间隔时间(以秒为单位). yii\db\Connection
$serverStatusCache yii\caching\CacheInterface|string|false 缓存对象或应用程序缓存组件的ID, 用于存储在 $masters$slaves 中指定的 DB 服务器的健康状态. yii\db\Connection
$serverVersion string 服务器版本字符串. 该属性是只读的. yii\db\Connection
$shuffleMasters boolean 是否先洗牌 $masters. yii\db\Connection
$slave yii\db\Connection 当前活动的从属连接. 如果没有可用的从属连接, 并且$fallbackToMasterfalse, 则返回null. 该属性是只读的. yii\db\Connection
$slaveConfig array 应与 $slaves 中列出的每个从属配置合并的配置. yii\db\Connection
$slavePdo PDO 当前活动的从属连接的 PDO 实例. 如果没有可用的从属连接, 并且$fallbackToMasterfalse, 则返回null. 该属性是只读的. yii\db\Connection
$slaves array 从属连接配置列表. yii\db\Connection
$tablePrefix string 表名称的通用前缀或后缀. yii\db\Connection
$transaction yii\db\Transaction|null 当前活动的事务. 如果没有活动事务, 则为空null. 该属性是只读的. yii\db\Connection
$username string 建立数据库连接的用户名. yii\db\Connection

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 克隆后重置连接. yii\db\Connection
__construct() 构造函数. yii\base\BaseObject
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__sleep() 在序列号之前, 请关闭连接. yii\db\Connection
__unset() 将组件属性设置为null. yii\base\Component
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
beginTransaction() 开始事务. yii\db\Connection
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
cache() 将查询缓存用于可调用对象执行的查询. yii\db\Connection
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
className() 返回此类的完全限定名称. yii\base\BaseObject
close() 关闭当前活动的数据库连接. yii\db\Connection
createCommand() 创建一执行命令. yii\db\Connection
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getDriverName() 返回数据库驱动程序的名称. 如果当前的 $dsn 未被最终用户明确设置, 则基于当前 $dsn. yii\db\Connection
getIsActive() 返回一个值, 指示数据库连接是否建立. yii\db\Connection
getLastInsertID() 返回最后插入的行或序列值的ID. yii\db\Connection
getMaster() 返回当前活动的主连接. yii\db\Connection
getMasterPdo() 返回当前活动的主连接的 PDO 实例. yii\db\Connection
getQueryBuilder() 返回当前数据库连接的查询生成器. yii\db\Connection
getQueryCacheInfo() 返回当前查询缓存信息. yii\db\Connection
getSchema() 返回由此连接打开的数据库的模式信息. yii\db\Connection
getServerVersion() 返回可与 \version_compare() 进行比较的服务器版本字符串. yii\db\Connection
getSlave() 返回当前活动的从属连接. yii\db\Connection
getSlavePdo() 返回当前活动的从属连接的 PDO 实例. yii\db\Connection
getTableSchema() 获取指定表的模式信息. yii\db\Connection
getTransaction() 返回当前活动的事务. yii\db\Connection
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
init() 初始化对象. yii\base\BaseObject
noCache() 暂时禁用查询缓存. yii\db\Connection
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
open() 建立数据库连接. yii\db\Connection
quoteColumnName() 引用要在查询中使用的列名. yii\db\Connection
quoteSql() 通过引用括在双括号内的表名和列名来处理 SQL 语句. yii\db\Connection
quoteTableName() 引用要在查询中使用的表名. yii\db\Connection
quoteValue() 引用要在查询中使用的字符串值. yii\db\Connection
setDriverName() 更改当前的驱动程序名称. yii\db\Connection
setQueryBuilder() 可用于通过连接配置数组设置 yii\db\QueryBuilder 属性. yii\db\Connection
transaction() 执行事务中提供的回调. yii\db\Connection
trigger() 触发事件. yii\base\Component
useMaster() 通过使用主连接执行提供的回调. yii\db\Connection

受保护的方法

隐藏继承的方法

方法描述定义在
createPdoInstance() 创建 PDO 实例. yii\db\Connection
initConnection() 初始化数据库连接. yii\db\Connection
openFromPool() 打开到池中的服务器的连接. yii\db\Connection
openFromPoolSequentially() 打开到池中服务器的连接. yii\db\Connection

事件

隐藏继承的事件

事件类型描述定义在
EVENT_AFTER_OPEN \yii\db\yii\base\Event 数据库连接建立后触发的事件. yii\db\Connection
EVENT_BEGIN_TRANSACTION \yii\db\yii\base\Event 在顶级事务开始之前触发的事件. yii\db\Connection
EVENT_COMMIT_TRANSACTION \yii\db\yii\base\Event 在顶级事务提交之后触发的事件. yii\db\Connection
EVENT_ROLLBACK_TRANSACTION \yii\db\yii\base\Event 在顶级事务回滚之后立即触发的事件. yii\db\Connection

属性详情

$attributes public 属性

调用 open() 建立数据库连接时, 应设置的 PDO 属性(name => value). 有关可用属性的详细信息, 请参阅 PHP 手册.

public array $attributes null
$charset public 属性

用于数据库连接的字符集. 该属性仅用于 MySQL, PostgreSQL 和 CUBRID 数据库. 默认为null, 表示使用数据库配置的默认字符集.

对于 Oracle 数据库, 必须在 $dsn 中指定字符集, 例如对于 UTF-8, 通过在 DSN 字符串后附加;charset=UTF-8来指定字符集.

如果在 MySQL 中使用 GBK 或 BIG5 字符集, 则同样如此, 因此强烈建议通过 $dsn 来指定字符集, 例如: 'mysql:dbname=mydatabase;host=127.0.0.1;charset=GBK;'.

public string $charset null
$commandClass public 属性 (可用自版本: 2.0.7)
弃用 自 2.0.14. 使用 $commandMap 进行精确配置.

用于创建新数据库 yii\db\Command 对象的类. 如果要扩展 yii\db\Command 类, 则可以配置此属性以使用该类的扩展版本. 自版本 2.0.14 起, 如果将此属性设置为默认值, 则使用 $commandMap.

参见 createCommand().

public string $commandClass 'yii\db\Command'
$commandMap public 属性 (可用自版本: 2.0.14)

PDO 驱动程序名称和 yii\db\Command 类之间的映射. 数据的键时 PDO 驱动程序名称, 而值时响应的 Command 类名称或配置. 有关如何指定配置的详细信息, 请参阅 Yii::createObject(). createCommand() 主要使用此属性来创建新的数据库 yii\db\Command 对象. 除非你想使用自己的 yii\db\Command 类来支持 Yii 不支持的 DBMS, 否则通常不需要设置此属性.

public array $commandMap = ['pgsql' => 'yii\db\Command''mysqli' => 'yii\db\Command''mysql' => 'yii\db\Command''sqlite' => 'yii\db\sqlite\Command''sqlite2' => 'yii\db\sqlite\Command''sqlsrv' => 'yii\db\Command''oci' => 'yii\db\oci\Command''mssql' => 'yii\db\Command''dblib' => 'yii\db\Command''cubrid' => 'yii\db\Command']
$driverName public 属性

数据库驱动程序的名称.

public string $driverName null
$dsn public 属性

数据源名称, 或 DSN, 包含连接到数据库所需的信息. 请参考 DSN 字符串格式的 PHP 手册.

对于 SQLite, 你可以使用 路径别名 来指定数据库路径. eg. sqlite:@app/data/db.sql.

参见 $charset.

public string $dsn null
$emulatePrepare public 属性

是否打开准备模拟. 默认为false, 表示 PDO 将使用本地准备支持(如果可用). 对于某些数据库(如 MySQL), 可能需要将其设置为true, 以便 PDO 可以模拟准备支持以绕过有问题的本地准备支持. 默认值为null, 这意味着将不会更改 PDO ATTR_EMULATE_PREPARES 值.

public boolean $emulatePrepare null
$enableLogging public 属性 (可用自版本: 2.0.12)

是否启用数据库查询日志. 默认为true. 如果不需要记录信息, 则可能需要在生产环境中禁用此选项以获得性能.

参见 $enableProfiling.

public boolean $enableLogging true
$enableProfiling public 属性 (可用自版本: 2.0.12)

是否启用对打开数据库连接和数据库查询的分析. 默认为true. 如果不需要记录信息, 则可能需要在生产环境中禁用此选项以获得性能.

参见 $enableLogging.

public boolean $enableProfiling true
$enableQueryCache public 属性

是否启用查询缓存.

Note: 为了启用查询缓存, 必须启用由 $queryCache 指定的有效缓存组件, 并且 $enableQueryCache 必须设置为true. 同样, 仅缓存在 cache() 中的查询结果.

参见:

public boolean $enableQueryCache true
$enableSavepoint public 属性

是否启用 保存点.

Note: 如果底层 DBMS 不支持保存点, 则将此属性设置为true将无效.

public boolean $enableSavepoint true
$enableSchemaCache public 属性

是否启用模式缓存.

Note: 为了启用真正的模式缓存, 必须启用由 $schemaCache 指定的有效缓存组件, 并且 $enableSchemaCache 必须设置为true.

参见:

public boolean $enableSchemaCache false
$enableSlaves public 属性

是否通过使用 $slaves 读取数据来启用读/写分离.

Note: 如果 $slaves 为空, 则无论此属性使用什么值, 都不会启用读/写分离.

public boolean $enableSlaves true
$isActive public 属性

数据库连接是否建立. 该属性是只读的.

public boolean $isActive null
$isSybase public 属性 (可用自版本: 2.0.38)

如果通过pdo_dblib连接的数据库是SyBase.

public boolean $isSybase false
$lastInsertID public 属性

插入的最后一行的行ID, 或从序列对象中检索到的最后一个值. 该属性是只读的.

public string $lastInsertID null
$master public 属性

当前活动的主连接. 如果没有可用的主服务器, 则返回null. 该属性是只读的.

public yii\db\Connection $master null
$masterConfig public 属性

应与 $masters 中列出的每个主配置合并的配置. 例如,

[
    'username' => 'master',
    'password' => 'master',
    'attributes' => [
        // 使用较小的连接超时
        PDO::ATTR_TIMEOUT => 10,
    ],
]
public array $masterConfig = []
$masterPdo public 属性

当前活动的主连接的 PDO 实例. 该属性是只读的.

public PDO $masterPdo null
$masters public 属性

主连接配置列表. 每个配置都用于创建主数据库连接. 当调用 open() 时, 将选择其中一个配置并将其用于创建将由此对象使用的数据库连接.

Note: 如果此属性不为空, 则该对象的连接设置(eg. "dsn", "username")将被忽略.

参见:

public array $masters = []
$password public 属性

建立数据库连接的密码. 默认为null, 表示不使用密码.

public string $password null
$pdo public 属性

与此数据库连接关联的 PHP PDO 实例. 该属性主要由 open()close() 方法管理. 当数据库连接处于活动状态时, 此属性将表示一个 PDO 实例; 否则, 它将是null.

参见 $pdoClass.

public PDO $pdo null
$pdoClass public 属性

自定义 PDO 包装器类. 如果未设置, 则在使用 MSSQL 时将使用 PDOyii\db\mssql\PDO.

参见 $pdo.

public string $pdoClass null
$queryBuilder public 属性

当前数据库连接的查询生成器. Note: 此属性的类型在 getter 和 setter 中有所不同. 有关详细信息, 请参阅 getQueryBuilder()setQueryBuilder().

$queryCache public 属性

缓存对象或用于查询缓存的应用程序缓存组件的ID.

参见 $enableQueryCache.

$queryCacheDuration public 属性

查询结果在高速缓存中保持有效的默认秒数. 默认为3600, 即3600秒, 或一个小时. 使用0表示缓存的数据将永不过期. 在没有缓存持续时间的情况下调用 cache() 时将使用此属性的值.

参见:

$schema public 属性

通过此连接打开的数据库的模式信息. 该属性是只读的.

public yii\db\Schema $schema null
$schemaCache public 属性

缓存对象或用于缓存表元数据的应用程序缓存组件的ID.

参见 $enableSchemaCache.

$schemaCacheDuration public 属性

表元数据在高速缓存中保持有效的秒数. 使用0表示缓存的数据将永不过期.

参见 $enableSchemaCache.

$schemaCacheExclude public 属性

不应该缓存其元数据的表的列表. 默认为空数组. 表名可以包含模式前缀(如果有). 不要引用表名.

参见 $enableSchemaCache.

$schemaMap public 属性

PDO 驱动程序名称和 yii\db\Schema 类之间的映射. 数组的键是 PDO 驱动程序名称, 而值则是相应的模式类名称或配置. 有关如何指定配置的详细信息, 请参阅 Yii::createObject().

在获取数据库模式信息时, 该属性主要由 getSchema() 使用. 除非你想使用自己的 yii\db\Schema 类来支持 Yii 不支持的 DBMS, 否则通常不需要设置此属性.

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 一起使用.

$serverStatusCache public 属性

缓存对象或应用程序缓存组件的ID, 用于存储在 $masters$slaves 中指定的 DB 服务器的健康状态. 仅在启用读/写分离或 $masters 不为空时使用. 设置为false表示禁用服务器状态缓存.

参见:

$serverVersion public 属性

服务器版本字符串. 该属性是只读的.

public string $serverVersion null
$shuffleMasters public 属性 (可用自版本: 2.0.11)

是否先洗牌 $masters.

参见 $masters.

public boolean $shuffleMasters true
$slave public 属性

当前活动的从属连接. 如果没有可用的从属连接, 并且$fallbackToMasterfalse, 则返回null. 该属性是只读的.

public yii\db\Connection $slave null
$slaveConfig public 属性

应与 $slaves 中列出的每个从属配置合并的配置. 例如,

[
    'username' => 'slave',
    'password' => 'slave',
    'attributes' => [
        // 使用较小的连接超时
        PDO::ATTR_TIMEOUT => 10,
    ],
]
public array $slaveConfig = []
$slavePdo public 属性

当前活动的从属连接的 PDO 实例. 如果没有可用的从属连接, 并且$fallbackToMasterfalse, 则返回null. 该属性是只读的.

public PDO $slavePdo null
$slaves public 属性

从属连接配置列表. 每个配置都用于创建从属数据库连接. 当 $enableSlavestrue时, 将选择其中一个配置并将其用于创建仅用于执行读取查询的数据库连接.

参见:

public array $slaves = []
$tablePrefix public 属性

表名称的通用前缀或后缀. 如果表名是以{{%TableName}}给出的, 那么百分号字符%将被替换为该属性值. 例如: {{%post}}变为{{tbl_post}}.

public string $tablePrefix ''
$transaction public 属性

当前活动的事务. 如果没有活动事务, 则为空null. 该属性是只读的.

$username public 属性

建立数据库连接的用户名. 默认为null, 表示不使用用户名.

public string $username null

方法详情

__clone() public 方法

克隆后重置连接.

public void __clone ( )
__sleep() public 方法

在序列号之前, 请关闭连接.

public array __sleep ( )
beginTransaction() public 方法

开始事务.

public yii\db\Transaction beginTransaction ( $isolationLevel null )
$isolationLevel string|null

用于此事务的隔离级别. 有关详细信息, 请参阅 yii\db\Transaction::begin().

return yii\db\Transaction

事务开始.

cache() public 方法

将查询缓存用于可调用对象执行的查询.

启用查询缓存($enableQueryCachetrue, $queryCache 表示有效的缓存)时, 在可调用对象中执行的查询将被缓存, 并且如果有查询, 将从缓存中获取其结果. 例如,

// 如果可用, 将从缓存中获取客户.
// 否则, 将针对数据库进行查询并缓存以供下次使用.
$customer = $db->cache(function (Connection $db) {
    return $db->createCommand('SELECT * FROM customer WHERE id=1')->queryOne();
});

Note: 该查询缓存仅对返回结果的查询有意义. 对于使用 yii\db\Command::execute() 执行的查询, 将不使用查询缓存.

参见:

public mixed cache ( callable $callable, $duration null, $dependency null )
$callable callable

一个包含 DB 查询的 PHP 可调用对象, 它将使用查询缓存. 可调用对象的签名是function (Connection $db).

$duration integer

查询结果可以在缓存中保持有效的秒数. 如果未设置, 则将使用 $queryCacheDuration 的值. 使用0表示缓存的数据将永不过期.

$dependency yii\caching\Dependency

与缓存的查询结果关联的缓存依赖关系.

return mixed

可调用的返回结果.

throws \Exception|\Throwable

如果在查询期间有任何异常.

close() public 方法

关闭当前活动的数据库连接.

如果连接已关闭, 则不执行任何操作.

public void close ( )
createCommand() public 方法

创建一执行命令.

public yii\db\Command createCommand ( $sql null, $params = [] )
$sql string

要执行的 SQL 语句.

$params array

要绑定到 SQL 语句的参数.

return yii\db\Command

DB 命令.

createPdoInstance() protected 方法

创建 PDO 实例.

open() 调用此方法以建立数据库连接. 默认实现将创建一个 PHP PDO 实例. 如果需要为某些 DBMS 调整默认的 PDO, 则可以重写此方法.

protected PDO createPdoInstance ( )
return PDO

PDO 实例.

getDriverName() public 方法

返回数据库驱动程序的名称. 如果当前的 $dsn 未被最终用户明确设置, 则基于当前 $dsn.

public string getDriverName ( )
return string

DB 驱动程序的名称.

getIsActive() public 方法

返回一个值, 指示数据库连接是否建立.

public boolean getIsActive ( )
return boolean

数据库连接是否建立.

getLastInsertID() public 方法

返回最后插入的行或序列值的ID.

参见 https://secure.php.net/manual/en/pdo.lastinsertid.php.

public string getLastInsertID ( $sequenceName '' )
$sequenceName string

序列对象的名称(某些 DBMS 需要).

return string

插入的最后一行的行ID, 或从序列对象中检索的最后一个值.

getMaster() public 方法 (可用自版本: 2.0.11)

返回当前活动的主连接.

如果是第一次调用此方法, 它将尝试打开一个主连接.

public yii\db\Connection getMaster ( )
return yii\db\Connection

当前活动的主连接. 如果没有可用的主连接, 则返回null.

getMasterPdo() public 方法

返回当前活动的主连接的 PDO 实例.

此方法将打开主数据库连接, 然后返回 $pdo.

public PDO getMasterPdo ( )
return PDO

当前活动的主连接的 PDO 实例.

getQueryBuilder() public 方法

返回当前数据库连接的查询生成器.

public yii\db\QueryBuilder getQueryBuilder ( )
return yii\db\QueryBuilder

当前数据库连接的查询生成器.

getQueryCacheInfo() public 方法

返回当前查询缓存信息.

该方法由 yii\db\Command 内部使用.

public array getQueryCacheInfo ( $duration, $dependency )
$duration integer

首选的缓存时间. 如果为null, 则会被忽略.

$dependency yii\caching\Dependency

首选的缓存依赖. 如果为null, 则会被忽略.

return array

当前查询缓存信息; 如果未启用查询缓存, 则返回null.

getSchema() public 方法

返回由此连接打开的数据库的模式信息.

public yii\db\Schema getSchema ( )
return yii\db\Schema

此连接打开的数据库的模式信息.

throws yii\base\NotSupportedException

如果不支持当前的驱动程序类型.

getServerVersion() public 方法 (可用自版本: 2.0.14)

返回可与 \version_compare() 进行比较的服务器版本字符串.

public string getServerVersion ( )
return string

服务器版本字符串.

getSlave() public 方法

返回当前活动的从属连接.

如果是第一次调用此方法, 则当 $enableSlavestrue时, 它将尝试打开一个从属连接.

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

如果没有任何从属连接可用, 是否返回主 PDO.

return yii\db\Connection

当前活动的从属连接. 如果没有可用的从属连接且$fallbackToMasterfalse, 则返回null.

getSlavePdo() public 方法

返回当前活动的从属连接的 PDO 实例.

$enableSlavestrue时, 其中一个从属将用于读取查询. 并且此方法将返回其 PDO 实例.

public PDO getSlavePdo ( $fallbackToMaster true )
$fallbackToMaster boolean

如果没有任何从属连接可用, 是否返回主 PDO.

return PDO

当前活动的从属连接的 PDO 实例. 如果没有可用的从属连接且$fallbackToMasterfalse, 则返回null.

getTableSchema() public 方法

获取指定表的模式信息.

public yii\db\TableSchema getTableSchema ( $name, $refresh false )
$name string

表名.

$refresh boolean

是否重新加载表模式, 即使它在高速缓存中找到.

return yii\db\TableSchema

表模式信息. 如果指定的表不存在, 则为null.

getTransaction() public 方法

返回当前活动的事务.

public yii\db\Transaction|null getTransaction ( )
return yii\db\Transaction|null

当前活动的事务. 如果没有活动事务, 则为null.

initConnection() protected 方法

初始化数据库连接.

建立数据库连接后立即调用该方法. 如果 $emulatePreparetrue, 则默认实现打开PDO::ATTR_EMULATE_PREPARES. 如果数据库 $charset 不为空, 则默认设置为打开. 然后, 它将触发 EVENT_AFTER_OPEN 事件.

protected void initConnection ( )
noCache() public 方法

暂时禁用查询缓存.

在可调用对象中执行的查询将完全不使用查询缓存. 例如:

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

    // ... 使用查询缓存的查询 ...

    return $db->noCache(function (Connection $db) {
        // 该查询将不使用查询缓存
        return $db->createCommand('SELECT * FROM customer WHERE id=1')->queryOne();
    });
});

参见:

public mixed noCache ( callable $callable )
$callable callable

一个包含 DB 查询的 PHP 可调用对象, 该查询不使用查询缓存. 可调用对象的签名是function (Connection $db).

return mixed

可调用的返回结果.

throws \Exception|\Throwable

如果在查询期间有任何异常.

open() public 方法

建立数据库连接.

如果已经建立数据库连接, 则不执行任何操作.

public void open ( )
throws yii\db\Exception

如果连接失败.

openFromPool() protected 方法

打开到池中的服务器的连接.

此方法实现了给定的服务器列表之间的负载均衡和故障转移. 连接将以随机顺序尝试. 有关故障转移行为的详细信息, 请参阅 openFromPoolSequentially().

参见 openFromPoolSequentially().

protected yii\db\Connection openFromPool ( array $pool, array $sharedConfig )
$pool array

服务器池中的连接配置列表.

$sharedConfig array

$pool中给的的配置相同.

return yii\db\Connection

打开的数据库连接. 如果没有可用的服务器, 则为null.

throws yii\base\InvalidConfigException

如果配置未指定"dsn".

openFromPoolSequentially() protected 方法 (可用自版本: 2.0.11)

打开到池中服务器的连接.

此方法在给定的服务器列表之间实现故障转移. 连接将按顺序尝试. 第一个成功的连接将返回.

如果配置了 $serverStatusCache, 则此方法将缓存有关无法访问服务器的信息, 并且在 $serverRetryInterval 中配置的时间内不会尝试连接到这些服务器. 当某些服务器不可用时, 这有助于保持应用程序的稳定. 当连接尝试由于超时而失败时, 避免与不可用服务器的连接尝试可以节省时间.

如果没有可用的服务器, 则将忽略状态缓存, 并尝试与所有服务器建立连接(自版本2.0.35开始). 当所有服务器在短时间内不可用时, 这可以避免停机. 成功尝试连接后, 服务器将再次标记为可用.

参见:

protected yii\db\Connection openFromPoolSequentially ( array $pool, array $sharedConfig )
$pool array

服务器池中的连接配置列表.

$sharedConfig array

$pool中给的的配置相同.

return yii\db\Connection

打开的数据库连接. 如果没有可用的服务器, 则为null.

throws yii\base\InvalidConfigException

如果配置未指定"dsn".

quoteColumnName() public 方法

引用要在查询中使用的列名.

如果列名包含前缀, 则前缀也将被正确引用. 如果列名已经被引用或者包含特殊字符, 包括(, [[{{, 则此方法将不起作用.

public string quoteColumnName ( $name )
$name string

列名称.

return string

正确引用的列名称.

quoteSql() public 方法

通过引用括在双括号内的表名和列名来处理 SQL 语句.

用双花括号括起来的标记被视为表名, 而用双方括号括起来的标记则是列名. 他们将被相应引用. 此外, 表名开头或结尾的百分比字符"%"将被替换为 $tablePrefix.

public string quoteSql ( $sql )
$sql string

要引用的 SQL.

return string

引用的 SQL.

quoteTableName() public 方法

引用要在查询中使用的表名.

如果表名包含模式前缀, 则前缀也将被正确引用. 如果表名已经被引用或者包含特殊字符, 包括(, [[{{, 则此方法将不起作用.

public string quoteTableName ( $name )
$name string

表名.

return string

正确引用的表名称.

quoteValue() public 方法

引用要在查询中使用的字符串值.

Note: 如果该参数不是一个字符串, 则将返回该值而不会更改.

参见 https://secure.php.net/manual/en/pdo.quote.php.

public string quoteValue ( $value )
$value string

要引用的字符串.

return string

正确引用的字符串.

setDriverName() public 方法

更改当前的驱动程序名称.

public void setDriverName ( $driverName )
$driverName string

DB 驱动程序的名称.

setQueryBuilder() public 方法 (可用自版本: 2.0.14)

可用于通过连接配置数组设置 yii\db\QueryBuilder 属性.

public void setQueryBuilder ( $value )
$value array

要配置的 yii\db\QueryBuilder 属性.

transaction() public 方法

执行事务中提供的回调.

public mixed transaction ( callable $callback, $isolationLevel null )
$callback callable

执行作业的有效 PHP 回调. 接受连接实例作为参数.

$isolationLevel string|null

用于此事务的隔离级别. 有关详细信息, 请参阅 yii\db\Transaction::begin().

return mixed

回调函数的结果.

throws \Exception|\Throwable

查询期间是否任何异常. 在这种情况下, 事务将被回滚.

useMaster() public 方法

通过使用主连接执行提供的回调.

提供此方法是为了使你可以临时强制使用主连接来执行数据库操作, 即使它们是读取查询. 例如:

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

此方法执行的可调用 PHP. 它的签名是function (Connection $db). 它的返回值将通过此方法返回.

return mixed

回调的返回值.

throws \Exception|\Throwable

如果从回调中抛出任何异常.

事件详情

EVENT_AFTER_OPEN 事件类型 \yii\db\yii\base\Event

数据库连接建立后触发的事件.

EVENT_BEGIN_TRANSACTION 事件类型 \yii\db\yii\base\Event

在顶级事务开始之前触发的事件.

EVENT_COMMIT_TRANSACTION 事件类型 \yii\db\yii\base\Event

在顶级事务提交之后触发的事件.

EVENT_ROLLBACK_TRANSACTION 事件类型 \yii\db\yii\base\Event

在顶级事务回滚之后立即触发的事件.