CDbConnection

$connection=new CDbConnection($dsn,$username,$password);
$connection->active=true;

$command=$connection->createCommand($sqlStatement);
$command->execute();   // a non-query SQL statement execution
// or execute an SQL query and fetch the result set
$reader=$command->query();

// each $row is an array representing a row of data
foreach($reader as $row) ...

$command=$connection->createCommand($sqlStatement);
$command->bindParam($name1,$value1);
$command->bindParam($name2,$value2);
$command->execute();

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

array(
    'components'=>array(
        'db'=>array(
            'class'=>'CDbConnection',
            'connectionString'=>'sqlite:path/to/dbfile',
        ),
    ),
)

'db'=>array(
    'class'=>'CDbConnection',
    'driverName'=>'mysql',
    'connectionString'=>'odbc:Driver={MySQL};Server=127.0.0.1;Database=test',
    'username'=>'',
    'password'=>'',
),

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

active свойство

public boolean getActive()
public void setActive(boolean $value)

Возвращает значение, указывающее, установлено ли подключение к БД.

attributes свойство (доступно начиная с v1.1.7)

public array getAttributes()
public void setAttributes(array $values)

Возвращает атрибуты, ранее явно заданные для подключения к БД.

autoCommit свойство

public boolean getAutoCommit()
public void setAutoCommit(boolean $value)

Возвращает значение, указывающее, будет ли автоматически выполняться подтверждение записи в БД при создании или обновлении. Некоторые СУБД (например, sqlite) могут не поддерживать эту функцию.

autoConnect свойство

public boolean $autoConnect;

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

charset свойство

public string $charset;

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

Обратите внимание, что если вы используете GBK или BIG5, настоятельно рекомендуется обновить PHP до версии 5.3.6+ и указать кодировку символов через DSN, например, 'mysql:dbname=mydatabase;host=127.0.0.1;charset=GBK;'.

clientVersion свойство только для чтения

public string getClientVersion()

Возвращает информацию о версии драйвера БД.

columnCase свойство

public mixed getColumnCase()
public void setColumnCase(mixed $value)

Возвращает регистр имён столбцов.

commandBuilder свойство только для чтения

public CDbCommandBuilder getCommandBuilder()

Возвращает билдер SQL-команд для текущего подключения к БД.

connectionStatus свойство только для чтения

public string getConnectionStatus()

Возвращает состояние подключения. Некоторые СУБД (например, sqlite) могут не поддерживать эту функцию.

connectionString свойство

public string $connectionString;

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

currentTransaction свойство только для чтения

public CDbTransaction getCurrentTransaction()

Возвращает текущую активную транзакцию.

driverMap свойство (доступно начиная с v1.1.6)

public array $driverMap;

сопоставление между драйвером PDO и именем класса схемы. Класс схемы можно указать с помощью псевдонима пути.

driverName свойство

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

Возвращает имя драйвера БД.

emulatePrepare свойство

public boolean $emulatePrepare;

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

enableParamLogging свойство

public boolean $enableParamLogging;

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

enableProfiling свойство

public boolean $enableProfiling;

указывает, нужно ли включить профилирование SQL-запросов, выполняемых. По умолчанию значение равно false. Это следует включать в основном во время разработки, чтобы определить узкие места в выполнении SQL-запросов.

initSQLs свойство (доступно начиная с v1.1.1)

public array $initSQLs;

список SQL-запросов, которые должны быть выполнены сразу после установления подключения к БД.

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

public string getLastInsertID(string $sequenceName='')

Возвращает идентификатор последней вставленной строки или значения последовательности.

nullConversion свойство

public mixed getNullConversion()
public void setNullConversion(mixed $value)

Возвращает способ преобразования значений NULL и пустых строк.

password свойство

public string $password;

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

pdoClass свойство (доступно начиная с v1.1.8)

public string $pdoClass;

Пользовательский класс обёртки PDO.

pdoInstance свойство только для чтения

public PDO getPdoInstance()

Возвращает экземпляр PDO.

persistent свойство

public boolean getPersistent()
public void setPersistent(boolean $value)

Возвращает значение, указывающее, является ли подключение постоянным. Некоторые СУБД (например, sqlite) могут не поддерживать эту функцию.

prefetch свойство только для чтения

public boolean getPrefetch()

Возвращает значение, указывающее, выполняет ли подключение предварительную загрузку данных.

queryCacheID свойство (доступно начиная с v1.1.7)

public string $queryCacheID;

идентификатор компонента кэширования приложения, используемого для кэширования запросов. По умолчанию 'cache', что относится к главному компоненту кэширования. Установите это свойство в false, если хотите отключить кэширование запросов.

queryCachingCount свойство (доступно начиная с v1.1.7)

public integer $queryCachingCount;

количество SQL-запросов, которые необходимо кэшировать. Если это 0, то даже при включённом кэшировании запросов ни один запрос не будет кэширован. Обратите внимание, что каждый раз после выполнения SQL-запроса (как на сервере БД, так и полученного из кэша запросов), это свойство уменьшается на 1 до 0.

queryCachingDependency свойство (доступно начиная с v1.1.7)

public CCacheDependency|ICacheDependency $queryCachingDependency;

зависимость, которая будет использоваться при сохранении результатов запросов в кэш.

queryCachingDuration свойство (доступно начиная с v1.1.7)

public integer $queryCachingDuration;

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

Для включения кэширования запросов это свойство должно быть положительным целым числом, а queryCacheID должно указывать на действительный идентификатор компонента кэширования.

Метод cache() предоставляется в качестве удобного способа задания этого свойства и queryCachingDependency на лету.

схема свойство только для чтения

public CDbSchema getSchema()

Возвращает схему базы данных для текущего подключения.

schemaCacheID свойство

public string $schemaCacheID;

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

schemaCachingDuration свойство

public integer $schemaCachingDuration;

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

schemaCachingExclude свойство

public array $schemaCachingExclude;

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

serverInfo свойство только для чтения

public string getServerInfo()

Возвращает информацию о сервере СУБД.

serverVersion свойство только для чтения

public string getServerVersion()

Возвращает информацию о версии сервера СУБД.

stats свойство только для чтения

public array getStats()

Возвращает статистические результаты выполнения SQL-запросов. Результаты включают количество выполненных SQL-запросов и общее время выполнения. Для использования этого метода необходимо установить enableProfiling в true.

tablePrefix свойство (доступно начиная с v1.1.0)

public string $tablePrefix;

Префикс по умолчанию для имён таблиц. По умолчанию null, что означает отсутствие префикса. Установив это свойство, любой токен, например '{{tableName}}' в CDbCommand::text, будет заменён на 'prefixTableName', где 'prefix' соответствует значению этого свойства.

timeout свойство только для чтения

public integer getTimeout()

Возвращает настройки таймаута для подключения.

username свойство

public string $username;

Имя пользователя для установления подключения к базе данных. По умолчанию пустая строка.

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

__construct() метод

public void __construct(string $dsn='', string $username='', string $password='')

public function __construct($dsn='',$username='',$password='')
{
    $this->connectionString=$dsn;
    $this->username=$username;
    $this->password=$password;
}

Конструктор. Обратите внимание, что подключение к базе данных не устанавливается при создании экземпляра этого подключения. Установите свойство active в true, чтобы установить подключение.

__sleep() метод

public array __sleep()

public function __sleep()
{
    $this->close();
    return array_keys(get_object_vars($this));
}

Закрывает подключение при сериализации.

beginTransaction() метод

public CDbTransaction beginTransaction()

public function beginTransaction()
{
    Yii::trace('Starting transaction','system.db.CDbConnection');
    $this->setActive(true);
    $this->_pdo->beginTransaction();
    return $this->_transaction=new CDbTransaction($this);
}

Начинает транзакцию.

cache() метод (доступно начиная с v1.1.7)

public static cache(integer $duration, CCacheDependency|ICacheDependency $dependency=NULL, integer $queryCount=1)

public function cache($duration, $dependency=null, $queryCount=1)
{
    $this->queryCachingDuration=$duration;
    $this->queryCachingDependency=$dependency;
    $this->queryCachingCount=$queryCount;
    return $this;
}

Устанавливает параметры кэширования запросов. Этот метод может использоваться для включения или отключения кэширования запросов. Установив параметр $duration в 0, кэширование запросов будет отключено. В противном случае результаты запросов новых SQL-запросов, которые будут выполнены после этого, будут сохранены в кэше и останутся действительными в течение указанного времени. Если тот же запрос выполняется снова, результат может быть получен из кэша напрямую, без фактического выполнения SQL-запроса.

close() метод

protected void close()

protected function close()
{
    Yii::trace('Closing DB connection','system.db.CDbConnection');
    $this->_pdo=null;
    $this->_active=false;
    $this->_schema=null;
}

Закрывает активное подключение к базе данных. Не делает ничего, если подключение уже закрыто.

createCommand() метод

public CDbCommand createCommand(mixed $query=NULL)

public function createCommand($query=null)
{
    $this->setActive(true);
    return new CDbCommand($this,$query);
}

Создаёт команду для выполнения.

createPdoInstance() метод

protected PDO createPdoInstance()

protected function createPdoInstance()
{
    $pdoClass=$this->pdoClass;
    if(($driver=$this->getDriverName())!==null)
    {
        if($driver==='mssql' || $driver==='dblib')
            $pdoClass='CMssqlPdoAdapter';
        elseif($driver==='sqlsrv')
            $pdoClass='CMssqlSqlsrvPdoAdapter';
    }

    if(!class_exists($pdoClass))
        throw new CDbException(Yii::t('yii','CDbConnection is unable to find PDO class "{className}". Make sure PDO is installed correctly.',
            array('{className}'=>$pdoClass)));

    @$instance=new $pdoClass($this->connectionString,$this->username,$this->password,$this->_attributes);

    if(!$instance)
        throw new CDbException(Yii::t('yii','CDbConnection failed to open the DB connection.'));

    return $instance;
}

Создаёт экземпляр PDO. Если в драйвере PDO отсутствуют некоторые функциональности, мы можем использовать адаптерский класс для их предоставления.

getActive() метод

public boolean getActive()

public function getActive()
{
    return $this->_active;
}

Возвращает, установлено ли подключение к базе данных.

getAttribute() метод

public mixed getAttribute(integer $name)

public function getAttribute($name)
{
    $this->setActive(true);
    return $this->_pdo->getAttribute($name);
}

Получает информацию об атрибуте конкретного подключения к БД.

getAttributes() метод (доступен с v1.1.7)

public array getAttributes()

public function getAttributes()
{
    return $this->_attributes;
}

Возвращает атрибуты, которые были ранее явно заданы для подключения к БД.

getAutoCommit() метод

public boolean getAutoCommit()

public function getAutoCommit()
{
    return $this->getAttribute(PDO::ATTR_AUTOCOMMIT);
}

Возвращает значение, указывающее, будет ли автоматически выполняться коммит при создании или обновлении записи в БД. Некоторые СУБД (например, sqlite) могут не поддерживать эту функцию.

getAvailableDrivers() метод

public static array getAvailableDrivers()

public static function getAvailableDrivers()
{
    return PDO::getAvailableDrivers();
}

Возвращает список доступных драйверов PDO.

getClientVersion() метод

public string getClientVersion()

public function getClientVersion()
{
    return $this->getAttribute(PDO::ATTR_CLIENT_VERSION);
}

Возвращает информацию о версии драйвера БД.

getColumnCase() метод

public mixed getColumnCase()

public function getColumnCase()
{
    return $this->getAttribute(PDO::ATTR_CASE);
}

Возвращает регистр имён столбцов

getCommandBuilder() метод

public CDbCommandBuilder getCommandBuilder()

public function getCommandBuilder()
{
    return $this->getSchema()->getCommandBuilder();
}

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

getConnectionStatus() метод

public string getConnectionStatus()

public function getConnectionStatus()
{
    return $this->getAttribute(PDO::ATTR_CONNECTION_STATUS);
}

Возвращает состояние подключения. Некоторые СУБД (например, sqlite) могут не поддерживать эту функцию.

getCurrentTransaction() метод

public CDbTransaction getCurrentTransaction()

public function getCurrentTransaction()
{
    if($this->_transaction!==null)
    {
        if($this->_transaction->getActive())
            return $this->_transaction;
    }
    return null;
}

Возвращает текущую активную транзакцию.

getDriverName() метод

public string getDriverName()

public function getDriverName()
{
    if($this->_driverName!==null)
        return $this->_driverName;
    elseif(($pos=strpos($this->connectionString,':'))!==false)
        return $this->_driverName=strtolower(substr($this->connectionString,0,$pos));
    //return $this->getAttribute(PDO::ATTR_DRIVER_NAME);
}

Возвращает имя драйвера БД.

getLastInsertID() метод

public string getLastInsertID(string $sequenceName='')

public function getLastInsertID($sequenceName='')
{
    $this->setActive(true);
    return $this->_pdo->lastInsertId($sequenceName);
}

Возвращает ID последней вставленной строки или значение последовательности.

getNullConversion() метод

public mixed getNullConversion()

public function getNullConversion()
{
    return $this->getAttribute(PDO::ATTR_ORACLE_NULLS);
}

Возвращает способ преобразования null и пустых строк.

getPdoInstance() метод

public PDO getPdoInstance()

public function getPdoInstance()
{
    return $this->_pdo;
}

Возвращает экземпляр PDO.

getPdoType() метод

public integer getPdoType(string $type)

public function getPdoType($type)
{
    static $map=array
    (
        'boolean'=>PDO::PARAM_BOOL,
        'integer'=>PDO::PARAM_INT,
        'string'=>PDO::PARAM_STR,
        'resource'=>PDO::PARAM_LOB,
        'NULL'=>PDO::PARAM_NULL,
    );
    return isset($map[$type]) ? $map[$type] : PDO::PARAM_STR;
}

Определяет тип PDO для указанного типа PHP.

getPersistent() метод

public boolean getPersistent()

public function getPersistent()
{
    return $this->getAttribute(PDO::ATTR_PERSISTENT);
}

Возвращает значение, указывающее, является ли подключение персистентным. Некоторые СУБД (например, sqlite) могут не поддерживать эту функцию.

getPrefetch() метод

public boolean getPrefetch()

public function getPrefetch()
{
    return $this->getAttribute(PDO::ATTR_PREFETCH);
}

Возвращает значение, указывающее, выполняет ли подключение предварительную загрузку данных.

getSchema() method

public CDbSchema getSchema()

public function getSchema()
{
    if($this->_schema!==null)
        return $this->_schema;
    else
    {
        $driver=$this->getDriverName();
        if(isset($this->driverMap[$driver]))
            return $this->_schema=Yii::createComponent($this->driverMap[$driver], $this);
        else
            throw new CDbException(Yii::t('yii','CDbConnection does not support reading schema for {driver} database.',
                array('{driver}'=>$driver)));
    }
}

Возвращает схему базы данных для текущего подключения.

getServerInfo() method

public string getServerInfo()

public function getServerInfo()
{
    return $this->getAttribute(PDO::ATTR_SERVER_INFO);
}

Возвращает информацию о сервере СУБД.

getServerVersion() method

public string getServerVersion()

public function getServerVersion()
{
    return $this->getAttribute(PDO::ATTR_SERVER_VERSION);
}

Возвращает информацию о версии сервера СУБД.

getStats() method

public array getStats()

public function getStats()
{
    $logger=Yii::getLogger();
    $timings=$logger->getProfilingResults(null,'system.db.CDbCommand.query');
    $count=count($timings);
    $time=array_sum($timings);
    $timings=$logger->getProfilingResults(null,'system.db.CDbCommand.execute');
    $count+=count($timings);
    $time+=array_sum($timings);
    return array($count,$time);
}

Возвращает статистические результаты выполнения SQL-запросов. Результаты включают количество выполненных SQL-запросов и общее затраченное время. Для использования этого метода необходимо установить enableProfiling в true.

getTimeout() method

public integer getTimeout()

public function getTimeout()
{
    return $this->getAttribute(PDO::ATTR_TIMEOUT);
}

Возвращает настройки таймаута для подключения.

init() method

public void init()

public function init()
{
    parent::init();
    if($this->autoConnect)
        $this->setActive(true);
}

Инициализирует компонент. Этот метод требуется IApplicationComponent и вызывается приложением при использовании CDbConnection в качестве компонента приложения. При переопределении этого метода обязательно вызывайте родительскую реализацию, чтобы компонент мог быть помечен как инициализированный.

initConnection() method

protected void initConnection(PDO $pdo)

protected function initConnection($pdo)
{
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    if($this->emulatePrepare!==null && constant('PDO::ATTR_EMULATE_PREPARES'))
        $pdo->setAttribute(PDO::ATTR_EMULATE_PREPARES,$this->emulatePrepare);
    if($this->charset!==null)
    {
        $driver=strtolower($pdo->getAttribute(PDO::ATTR_DRIVER_NAME));
        if(in_array($driver,array('pgsql','mysql','mysqli')))
            $pdo->exec('SET NAMES '.$pdo->quote($this->charset));
    }
    if($this->initSQLs!==null)
    {
        foreach($this->initSQLs as $sql)
            $pdo->exec($sql);
    }
}

Инициализирует открытое подключение к базе данных. Этот метод вызывается сразу после создания подключения к базе данных. По умолчанию устанавливается кодировка для подключений к базам данных MySQL, MariaDB и PostgreSQL.

open() method

protected void open()

protected function open()
{
    if($this->_pdo===null)
    {
        if(empty($this->connectionString))
            throw new CDbException('CDbConnection.connectionString cannot be empty.');
        try
        {
            Yii::trace('Opening DB connection','system.db.CDbConnection');
            $this->_pdo=$this->createPdoInstance();
            $this->initConnection($this->_pdo);
            $this->_active=true;
        }
        catch(PDOException $e)
        {
            if(YII_DEBUG)
            {
                throw new CDbException('CDbConnection failed to open the DB connection: '.
                    $e->getMessage(),(int)$e->getCode(),$e->errorInfo);
            }
            else
            {
                Yii::log($e->getMessage(),CLogger::LEVEL_ERROR,'exception.CDbException');
                throw new CDbException('CDbConnection failed to open the DB connection.',(int)$e->getCode(),$e->errorInfo);
            }
        }
    }
}

Открывает подключение к базе данных, если оно в данный момент не открыто.

quoteColumnName() method

public string quoteColumnName(string $name)

public function quoteColumnName($name)
{
    return $this->getSchema()->quoteColumnName($name);
}

Обрамляет имя столбца для использования в запросе. Если имя столбца содержит префикс, префикс также будет правильно обрамлён.

quoteTableName() method

public string quoteTableName(string $name)

public function quoteTableName($name)
{
    return $this->getSchema()->quoteTableName($name);
}

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

quoteValue() method

public string quoteValue(string $str)

public function quoteValue($str)
{
    if(is_int($str) || is_float($str))
        return $str;

    $this->setActive(true);
    if(($value=$this->_pdo->quote($str))!==false)
        return $value;
    else  // the driver doesn't support quote (e.g. oci)
        return "'" . addcslashes(str_replace("'", "''", $str), "\000\n\r\\\032") . "'";
}

Обрамляет строковое значение для использования в запросе.

quoteValueWithType() method (available since v1.1.18)

public string quoteValueWithType(mixed $value, integer $type)

public function quoteValueWithType($value, $type)
{
    $this->setActive(true);
    if(($quoted=$this->_pdo->quote($value, $type))!==false)
        return $quoted;
    else  // the driver doesn't support quote (e.g. oci)
        return "'" . addcslashes(str_replace("'", "''", $value), "\000\n\r\\\032") . "'";
}

Обрамляет значение для использования в запросе, используя заданный тип.

setActive() method

public void setActive(boolean $value)

public function setActive($value)
{
    if($value!=$this->_active)
    {
        if($value)
            $this->open();
        else
            $this->close();
    }
}

Открывает или закрывает подключение к базе данных.

setAttribute() method

public void setAttribute(integer $name, mixed $value)

public function setAttribute($name,$value)
{
    if($this->_pdo instanceof PDO)
        $this->_pdo->setAttribute($name,$value);
    else
        $this->_attributes[$name]=$value;
}

Устанавливает атрибут подключения к базе данных.

setAttributes() метод (доступен начиная с v1.1.7)

public void setAttributes(array $values)

public function setAttributes($values)
{
    foreach($values as $name=>$value)
        $this->_attributes[$name]=$value;
}

Устанавливает набор атрибутов подключения к базе данных.

setAutoCommit() метод

public void setAutoCommit(boolean $value)

public function setAutoCommit($value)
{
    $this->setAttribute(PDO::ATTR_AUTOCOMMIT,$value);
}

Устанавливает, будет ли автоматически фиксироваться созданная или обновлённая запись в БД. Некоторые СУБД (например, sqlite) могут не поддерживать эту функцию.

setColumnCase() метод

public void setColumnCase(mixed $value)

public function setColumnCase($value)
{
    $this->setAttribute(PDO::ATTR_CASE,$value);
}

Устанавливает регистр имён столбцов.

setDriverName() метод (доступен начиная с v1.1.16)

public void setDriverName(string $driverName)

public function setDriverName($driverName)
{
    $this->_driverName=strtolower($driverName);
}

Изменяет имя драйвера БД. Переопределяет значение, извлеченное из connectionString, что является поведением по умолчанию.

setNullConversion() метод

public void setNullConversion(mixed $value)

public function setNullConversion($value)
{
    $this->setAttribute(PDO::ATTR_ORACLE_NULLS,$value);
}

Устанавливает способ преобразования значений null и пустых строк.

setPersistent() метод

public void setPersistent(boolean $value)

public function setPersistent($value)
{
    return $this->setAttribute(PDO::ATTR_PERSISTENT,$value);
}

Устанавливает, является ли подключение персистентным. Некоторые СУБД (например, sqlite) могут не поддерживать эту функцию.