Versions
Look up a class, method, property or event

CDbConnection

Package system.db
Inheritance class CDbConnection » CApplicationComponent » CComponent
Implements IApplicationComponent
Since 1.0
Source Code framework/db/CDbConnection.php
CDbConnection represents a connection to a database.

CDbConnection works together with CDbCommand, CDbDataReader and CDbTransaction to provide data access to various DBMS in a common set of APIs. They are a thin wrapper of the PDO PHP extension.

To establish a connection, set active to true after specifying connectionString, username and password.

The following example shows how to create a CDbConnection instance and establish the actual connection:
$connection=new CDbConnection($dsn,$username,$password);
$connection->active=true;


After the DB connection is established, one can execute an SQL statement like the following:
$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) ...


One can do prepared SQL execution and bind parameters to the prepared SQL:
$command=$connection->createCommand($sqlStatement);
$command->bindParam($name1,$value1);
$command->bindParam($name2,$value2);
$command->execute();


To use transaction, do like the following:
$transaction=$connection->beginTransaction();
try
{
   $connection->createCommand($sql1)->execute();
   $connection->createCommand($sql2)->execute();
   //.... other SQL executions
   $transaction->commit();
}
catch(Exception $e)
{
   $transaction->rollback();
}


CDbConnection also provides a set of methods to support setting and querying of certain DBMS attributes, such as nullConversion.

Since CDbConnection implements the interface IApplicationComponent, it can be used as an application component and be configured in application configuration, like the following,
array(
    'components'=>array(
        'db'=>array(
            'class'=>'CDbConnection',
            'connectionString'=>'sqlite:path/to/dbfile',
        ),
    ),
)

Public Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
active boolean Returns whether the DB connection is established. CDbConnection
attributes array Returns the attributes that are previously explicitly set for the DB connection. CDbConnection
autoCommit boolean Returns whether creating or updating a DB record will be automatically committed. CDbConnection
autoConnect boolean whether the database connection should be automatically established the component is being initialized. CDbConnection
behaviors array the behaviors that should be attached to this component. CApplicationComponent
charset string the charset used for database connection. CDbConnection
clientVersion string Returns the version information of the DB driver. CDbConnection
columnCase mixed Returns the case of the column names CDbConnection
commandBuilder CDbCommandBuilder Returns the SQL command builder for the current DB connection. CDbConnection
connectionStatus string Returns the status of the connection. CDbConnection
connectionString string The Data Source Name, or DSN, contains the information required to connect to the database. CDbConnection
currentTransaction CDbTransaction Returns the currently active transaction. CDbConnection
driverMap array mapping between PDO driver and schema class name. CDbConnection
driverName string Returns the name of the DB driver CDbConnection
emulatePrepare boolean whether to turn on prepare emulation. CDbConnection
enableParamLogging boolean whether to log the values that are bound to a prepare SQL statement. CDbConnection
enableProfiling boolean whether to enable profiling the SQL statements being executed. CDbConnection
initSQLs array list of SQL statements that should be executed right after the DB connection is established. CDbConnection
isInitialized boolean Checks if this application component has been initialized. CApplicationComponent
lastInsertID string Returns the ID of the last inserted row or sequence value. CDbConnection
nullConversion mixed Returns how the null and empty strings are converted. CDbConnection
password string the password for establishing DB connection. CDbConnection
pdoClass string Custom PDO wrapper class. CDbConnection
pdoInstance PDO Returns the PDO instance. CDbConnection
persistent boolean Returns whether the connection is persistent or not. CDbConnection
prefetch boolean Returns whether the connection performs data prefetching. CDbConnection
queryCacheID string the ID of the cache application component that is used for query caching. CDbConnection
queryCachingCount integer the number of SQL statements that need to be cached next. CDbConnection
queryCachingDependency CCacheDependency|ICacheDependency the dependency that will be used when saving query results into cache. CDbConnection
queryCachingDuration integer number of seconds that query results can remain valid in cache. CDbConnection
schema CDbSchema Returns the database schema for the current connection CDbConnection
schemaCacheID string the ID of the cache application component that is used to cache the table metadata. CDbConnection
schemaCachingDuration integer number of seconds that table metadata can remain valid in cache. CDbConnection
schemaCachingExclude array list of tables whose metadata should NOT be cached. CDbConnection
serverInfo string Returns the information of DBMS server. CDbConnection
serverVersion string Returns the version information of DBMS server. CDbConnection
stats array Returns the statistical results of SQL executions. CDbConnection
tablePrefix string the default prefix for table names. CDbConnection
timeout integer Returns the timeout settings for the connection. CDbConnection
username string the username for establishing DB connection. CDbConnection

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__call() Calls the named method which is not a class method. CComponent
__construct() Constructor. CDbConnection
__get() Returns a property value, an event handler list or a behavior based on its name. CComponent
__isset() Checks if a property value is null. CComponent
__set() Sets value of a component property. CComponent
__sleep() Close the connection when serializing. CDbConnection
__unset() Sets a component property to be null. CComponent
asa() Returns the named behavior object. CComponent
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
beginTransaction() Starts a transaction. CDbConnection
cache() Sets the parameters about query caching. CDbConnection
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
createCommand() Creates a command for execution. CDbConnection
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
getActive() Returns whether the DB connection is established. CDbConnection
getAttribute() Obtains a specific DB connection attribute information. CDbConnection
getAttributes() Returns the attributes that are previously explicitly set for the DB connection. CDbConnection
getAutoCommit() Returns whether creating or updating a DB record will be automatically committed. CDbConnection
getAvailableDrivers() Returns a list of available PDO drivers. CDbConnection
getClientVersion() Returns the version information of the DB driver. CDbConnection
getColumnCase() Returns the case of the column names CDbConnection
getCommandBuilder() Returns the SQL command builder for the current DB connection. CDbConnection
getConnectionStatus() Returns the status of the connection. CDbConnection
getCurrentTransaction() Returns the currently active transaction. CDbConnection
getDriverName() Returns the name of the DB driver CDbConnection
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getIsInitialized() Checks if this application component has been initialized. CApplicationComponent
getLastInsertID() Returns the ID of the last inserted row or sequence value. CDbConnection
getNullConversion() Returns how the null and empty strings are converted. CDbConnection
getPdoInstance() Returns the PDO instance. CDbConnection
getPdoType() Determines the PDO type for the specified PHP type. CDbConnection
getPersistent() Returns whether the connection is persistent or not. CDbConnection
getPrefetch() Returns whether the connection performs data prefetching. CDbConnection
getSchema() Returns the database schema for the current connection CDbConnection
getServerInfo() Returns the information of DBMS server. CDbConnection
getServerVersion() Returns the version information of DBMS server. CDbConnection
getStats() Returns the statistical results of SQL executions. CDbConnection
getTimeout() Returns the timeout settings for the connection. CDbConnection
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasProperty() Determines whether a property is defined. CComponent
init() Initializes the component. CDbConnection
quoteColumnName() Quotes a column name for use in a query. CDbConnection
quoteTableName() Quotes a table name for use in a query. CDbConnection
quoteValue() Quotes a string value for use in a query. CDbConnection
raiseEvent() Raises an event. CComponent
setActive() Open or close the DB connection. CDbConnection
setAttribute() Sets an attribute on the database connection. CDbConnection
setAttributes() Sets a set of attributes on the database connection. CDbConnection
setAutoCommit() Sets whether creating or updating a DB record will be automatically committed. CDbConnection
setColumnCase() Sets the case of the column names. CDbConnection
setNullConversion() Sets how the null and empty strings are converted. CDbConnection
setPersistent() Sets whether the connection is persistent or not. CDbConnection

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
close() Closes the currently active DB connection. CDbConnection
createPdoInstance() Creates the PDO instance. CDbConnection
initConnection() Initializes the open db connection. CDbConnection
open() Opens DB connection if it is currently not CDbConnection

Property Details

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

Returns whether the DB connection is established.

attributes property (available since v1.1.7)
public array getAttributes()
public void setAttributes(array $values)

Returns the attributes that are previously explicitly set for the DB connection.

See Also

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

Returns whether creating or updating a DB record will be automatically committed. Some DBMS (such as sqlite) may not support this feature.

autoConnect property
public boolean $autoConnect;

whether the database connection should be automatically established the component is being initialized. Defaults to true. Note, this property is only effective when the CDbConnection object is used as an application component.

charset property
public string $charset;

the charset used for database connection. The property is only used for MySQL and PostgreSQL databases. Defaults to null, meaning using default charset as specified by the database.

Note that if you're using GBK or BIG5 then it's highly recommended to update to PHP 5.3.6+ and to specify charset via DSN like 'mysql:dbname=mydatabase;host=127.0.0.1;charset=GBK;'.

clientVersion property read-only
public string getClientVersion()

Returns the version information of the DB driver.

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

Returns the case of the column names

commandBuilder property read-only

Returns the SQL command builder for the current DB connection.

connectionStatus property read-only
public string getConnectionStatus()

Returns the status of the connection. Some DBMS (such as sqlite) may not support this feature.

connectionString property
public string $connectionString;

The Data Source Name, or DSN, contains the information required to connect to the database.

currentTransaction property read-only

Returns the currently active transaction.

driverMap property (available since v1.1.6)
public array $driverMap;

mapping between PDO driver and schema class name. A schema class can be specified using path alias.

driverName property read-only
public string getDriverName()

Returns the name of the DB driver

emulatePrepare property
public boolean $emulatePrepare;

whether to turn on prepare emulation. Defaults to false, meaning PDO will use the native prepare support if available. For some databases (such as MySQL), this may need to be set true so that PDO can emulate the prepare support to bypass the buggy native prepare support. Note, this property is only effective for PHP 5.1.3 or above. The default value is null, which will not change the ATTR_EMULATE_PREPARES value of PDO.

enableParamLogging property
public boolean $enableParamLogging;

whether to log the values that are bound to a prepare SQL statement. Defaults to false. During development, you may consider setting this property to true so that parameter values bound to SQL statements are logged for debugging purpose. You should be aware that logging parameter values could be expensive and have significant impact on the performance of your application.

enableProfiling property
public boolean $enableProfiling;

whether to enable profiling the SQL statements being executed. Defaults to false. This should be mainly enabled and used during development to find out the bottleneck of SQL executions.

initSQLs property (available since v1.1.1)
public array $initSQLs;

list of SQL statements that should be executed right after the DB connection is established.

lastInsertID property read-only
public string getLastInsertID(string $sequenceName='')

Returns the ID of the last inserted row or sequence value.

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

Returns how the null and empty strings are converted.

password property
public string $password;

the password for establishing DB connection. Defaults to empty string.

pdoClass property (available since v1.1.8)
public string $pdoClass;

Custom PDO wrapper class.

pdoInstance property read-only
public PDO getPdoInstance()

Returns the PDO instance.

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

Returns whether the connection is persistent or not. Some DBMS (such as sqlite) may not support this feature.

prefetch property read-only
public boolean getPrefetch()

Returns whether the connection performs data prefetching.

queryCacheID property (available since v1.1.7)
public string $queryCacheID;

the ID of the cache application component that is used for query caching. Defaults to 'cache' which refers to the primary cache application component. Set this property to false if you want to disable query caching.

queryCachingCount property (available since v1.1.7)
public integer $queryCachingCount;

the number of SQL statements that need to be cached next. If this is 0, then even if query caching is enabled, no query will be cached. Note that each time after executing a SQL statement (whether executed on DB server or fetched from query cache), this property will be reduced by 1 until 0.

queryCachingDependency property (available since v1.1.7)
public CCacheDependency|ICacheDependency $queryCachingDependency;

the dependency that will be used when saving query results into cache.

queryCachingDuration property (available since v1.1.7)
public integer $queryCachingDuration;

number of seconds that query results can remain valid in cache. Use 0 or negative value to indicate not caching query results (the default behavior).

In order to enable query caching, this property must be a positive integer and queryCacheID must point to a valid cache component ID.

The method cache() is provided as a convenient way of setting this property and queryCachingDependency on the fly.

schema property read-only

Returns the database schema for the current connection

schemaCacheID property
public string $schemaCacheID;

the ID of the cache application component that is used to cache the table metadata. Defaults to 'cache' which refers to the primary cache application component. Set this property to false if you want to disable caching table metadata.

schemaCachingDuration property
public integer $schemaCachingDuration;

number of seconds that table metadata can remain valid in cache. Use 0 or negative value to indicate not caching schema. If greater than 0 and the primary cache is enabled, the table metadata will be cached.

schemaCachingExclude property
public array $schemaCachingExclude;

list of tables whose metadata should NOT be cached. Defaults to empty array.

serverInfo property read-only
public string getServerInfo()

Returns the information of DBMS server.

serverVersion property read-only
public string getServerVersion()

Returns the version information of DBMS server.

stats property read-only
public array getStats()

Returns the statistical results of SQL executions. The results returned include the number of SQL statements executed and the total time spent. In order to use this method, enableProfiling has to be set true.

tablePrefix property (available since v1.1.0)
public string $tablePrefix;

the default prefix for table names. Defaults to null, meaning no table prefix. By setting this property, any token like '{{tableName}}' in CDbCommand::text will be replaced by 'prefixTableName', where 'prefix' refers to this property value.

timeout property read-only
public integer getTimeout()

Returns the timeout settings for the connection.

username property
public string $username;

the username for establishing DB connection. Defaults to empty string.

Method Details

__construct() method
public void __construct(string $dsn='', string $username='', string $password='')
$dsn string The Data Source Name, or DSN, contains the information required to connect to the database.
$username string The user name for the DSN string.
$password string The password for the DSN string.
Source Code: framework/db/CDbConnection.php#270 (show)
public function __construct($dsn='',$username='',$password='')
{
    
$this->connectionString=$dsn;
    
$this->username=$username;
    
$this->password=$password;
}

Constructor. Note, the DB connection is not established when this connection instance is created. Set active property to true to establish the connection.

__sleep() method
public array __sleep()
{return} array
Source Code: framework/db/CDbConnection.php#281 (show)
public function __sleep()
{
    
$this->close();
    return 
array_keys(get_object_vars($this));
}

Close the connection when serializing.

beginTransaction() method
public CDbTransaction beginTransaction()
{return} CDbTransaction the transaction initiated
Source Code: framework/db/CDbConnection.php#502 (show)
public function beginTransaction()
{
    
Yii::trace('Starting transaction','system.db.CDbConnection');
    
$this->setActive(true);
    
$this->_pdo->beginTransaction();
    return 
$this->_transaction=new CDbTransaction($this);
}

Starts a transaction.

cache() method (available since v1.1.7)
public CDbConnection cache(integer $duration, CCacheDependency|ICacheDependency $dependency=NULL, integer $queryCount=1)
$duration integer the number of seconds that query results may remain valid in cache. If this is 0, the caching will be disabled.
$dependency CCacheDependency|ICacheDependency the dependency that will be used when saving the query results into cache.
$queryCount integer number of SQL queries that need to be cached after calling this method. Defaults to 1, meaning that the next SQL query will be cached.
{return} CDbConnection the connection instance itself.
Source Code: framework/db/CDbConnection.php#353 (show)
public function cache($duration$dependency=null$queryCount=1)
{
    
$this->queryCachingDuration=$duration;
    
$this->queryCachingDependency=$dependency;
    
$this->queryCachingCount=$queryCount;
    return 
$this;
}

Sets the parameters about query caching. This method can be used to enable or disable query caching. By setting the $duration parameter to be 0, the query caching will be disabled. Otherwise, query results of the new SQL statements executed next will be saved in cache and remain valid for the specified duration. If the same query is executed again, the result may be fetched from cache directly without actually executing the SQL statement.

close() method
protected void close()
Source Code: framework/db/CDbConnection.php#398 (show)
protected function close()
{
    
Yii::trace('Closing DB connection','system.db.CDbConnection');
    
$this->_pdo=null;
    
$this->_active=false;
    
$this->_schema=null;
}

Closes the currently active DB connection. It does nothing if the connection is already closed.

createCommand() method
public CDbCommand createCommand(mixed $query=NULL)
$query mixed the DB query to be executed. This can be either a string representing a SQL statement, or an array representing different fragments of a SQL statement. Please refer to CDbCommand::__construct for more details about how to pass an array as the query. If this parameter is not given, you will have to call query builder methods of CDbCommand to build the DB query.
{return} CDbCommand the DB command
Source Code: framework/db/CDbConnection.php#478 (show)
public function createCommand($query=null)
{
    
$this->setActive(true);
    return new 
CDbCommand($this,$query);
}

Creates a command for execution.

createPdoInstance() method
protected PDO createPdoInstance()
{return} PDO the pdo instance
Source Code: framework/db/CDbConnection.php#413 (show)
protected function createPdoInstance()
{
    
$pdoClass=$this->pdoClass;
    if((
$pos=strpos($this->connectionString,':'))!==false)
    {
        
$driver=strtolower(substr($this->connectionString,0,$pos));
        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;
}

Creates the PDO instance. When some functionalities are missing in the pdo driver, we may use an adapter class to provide them.

getActive() method
public boolean getActive()
{return} boolean whether the DB connection is established
Source Code: framework/db/CDbConnection.php#315 (show)
public function getActive()
{
    return 
$this->_active;
}

Returns whether the DB connection is established.

getAttribute() method
public mixed getAttribute(integer $name)
$name integer the attribute to be queried
{return} mixed the corresponding attribute information
Source Code: framework/db/CDbConnection.php#761 (show)
public function getAttribute($name)
{
    
$this->setActive(true);
    return 
$this->_pdo->getAttribute($name);
}

Obtains a specific DB connection attribute information.

getAttributes() method (available since v1.1.7)
public array getAttributes()
{return} array attributes (name=>value) that are previously explicitly set for the DB connection.
Source Code: framework/db/CDbConnection.php#787 (show)
public function getAttributes()
{
    return 
$this->_attributes;
}

Returns the attributes that are previously explicitly set for the DB connection.

See Also

getAutoCommit() method
public boolean getAutoCommit()
{return} boolean whether creating or updating a DB record will be automatically committed.
Source Code: framework/db/CDbConnection.php#654 (show)
public function getAutoCommit()
{
    return 
$this->getAttribute(PDO::ATTR_AUTOCOMMIT);
}

Returns whether creating or updating a DB record will be automatically committed. Some DBMS (such as sqlite) may not support this feature.

getAvailableDrivers() method
public static array getAvailableDrivers()
{return} array list of available PDO drivers
Source Code: framework/db/CDbConnection.php#292 (show)
public static function getAvailableDrivers()
{
    return 
PDO::getAvailableDrivers();
}

Returns a list of available PDO drivers.

getClientVersion() method
public string getClientVersion()
{return} string the version information of the DB driver
Source Code: framework/db/CDbConnection.php#704 (show)
public function getClientVersion()
{
    return 
$this->getAttribute(PDO::ATTR_CLIENT_VERSION);
}

Returns the version information of the DB driver.

getColumnCase() method
public mixed getColumnCase()
{return} mixed the case of the column names
Source Code: framework/db/CDbConnection.php#614 (show)
public function getColumnCase()
{
    return 
$this->getAttribute(PDO::ATTR_CASE);
}

Returns the case of the column names

getCommandBuilder() method
public CDbCommandBuilder getCommandBuilder()
{return} CDbCommandBuilder the command builder
Source Code: framework/db/CDbConnection.php#534 (show)
public function getCommandBuilder()
{
    return 
$this->getSchema()->getCommandBuilder();
}

Returns the SQL command builder for the current DB connection.

getConnectionStatus() method
public string getConnectionStatus()
{return} string the status of the connection
Source Code: framework/db/CDbConnection.php#714 (show)
public function getConnectionStatus()
{
    return 
$this->getAttribute(PDO::ATTR_CONNECTION_STATUS);
}

Returns the status of the connection. Some DBMS (such as sqlite) may not support this feature.

getCurrentTransaction() method
public CDbTransaction getCurrentTransaction()
{return} CDbTransaction the currently active transaction. Null if no active transaction.
Source Code: framework/db/CDbConnection.php#488 (show)
public function getCurrentTransaction()
{
    if(
$this->_transaction!==null)
    {
        if(
$this->_transaction->getActive())
            return 
$this->_transaction;
    }
    return 
null;
}

Returns the currently active transaction.

getDriverName() method
public string getDriverName()
{return} string name of the DB driver
Source Code: framework/db/CDbConnection.php#693 (show)
public function getDriverName()
{
    if((
$pos=strpos($this->connectionString':'))!==false)
        return 
strtolower(substr($this->connectionString0$pos));
    
// return $this->getAttribute(PDO::ATTR_DRIVER_NAME);
}

Returns the name of the DB driver

getLastInsertID() method
public string getLastInsertID(string $sequenceName='')
$sequenceName string name of the sequence object (required by some DBMS)
{return} string the row ID of the last row inserted, or the last value retrieved from the sequence object
Source Code: framework/db/CDbConnection.php#545 (show)
public function getLastInsertID($sequenceName='')
{
    
$this->setActive(true);
    return 
$this->_pdo->lastInsertId($sequenceName);
}

Returns the ID of the last inserted row or sequence value.

getNullConversion() method
public mixed getNullConversion()
{return} mixed how the null and empty strings are converted
Source Code: framework/db/CDbConnection.php#634 (show)
public function getNullConversion()
{
    return 
$this->getAttribute(PDO::ATTR_ORACLE_NULLS);
}

Returns how the null and empty strings are converted.

getPdoInstance() method
public PDO getPdoInstance()
{return} PDO the PDO instance, null if the connection is not established yet
Source Code: framework/db/CDbConnection.php#465 (show)
public function getPdoInstance()
{
    return 
$this->_pdo;
}

Returns the PDO instance.

getPdoType() method
public integer getPdoType(string $type)
$type string The PHP type (obtained by gettype() call).
{return} integer the corresponding PDO type
Source Code: framework/db/CDbConnection.php#596 (show)
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;
}

Determines the PDO type for the specified PHP type.

getPersistent() method
public boolean getPersistent()
{return} boolean whether the connection is persistent or not
Source Code: framework/db/CDbConnection.php#674 (show)
public function getPersistent()
{
    return 
$this->getAttribute(PDO::ATTR_PERSISTENT);
}

Returns whether the connection is persistent or not. Some DBMS (such as sqlite) may not support this feature.

getPrefetch() method
public boolean getPrefetch()
{return} boolean whether the connection performs data prefetching
Source Code: framework/db/CDbConnection.php#723 (show)
public function getPrefetch()
{
    return 
$this->getAttribute(PDO::ATTR_PREFETCH);
}

Returns whether the connection performs data prefetching.

getSchema() method
public CDbSchema getSchema()
{return} CDbSchema the database schema for the current connection
Source Code: framework/db/CDbConnection.php#515 (show)
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)));
    }
}

Returns the database schema for the current connection

getServerInfo() method
public string getServerInfo()
{return} string the information of DBMS server
Source Code: framework/db/CDbConnection.php#732 (show)
public function getServerInfo()
{
    return 
$this->getAttribute(PDO::ATTR_SERVER_INFO);
}

Returns the information of DBMS server.

getServerVersion() method
public string getServerVersion()
{return} string the version information of DBMS server
Source Code: framework/db/CDbConnection.php#741 (show)
public function getServerVersion()
{
    return 
$this->getAttribute(PDO::ATTR_SERVER_VERSION);
}

Returns the version information of DBMS server.

getStats() method
public array getStats()
{return} array the first element indicates the number of SQL statements executed, and the second element the total time spent in SQL execution.
Source Code: framework/db/CDbConnection.php#812 (show)
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);
}

Returns the statistical results of SQL executions. The results returned include the number of SQL statements executed and the total time spent. In order to use this method, enableProfiling has to be set true.

getTimeout() method
public integer getTimeout()
{return} integer timeout settings for the connection
Source Code: framework/db/CDbConnection.php#750 (show)
public function getTimeout()
{
    return 
$this->getAttribute(PDO::ATTR_TIMEOUT);
}

Returns the timeout settings for the connection.

init() method
public void init()
Source Code: framework/db/CDbConnection.php#304 (show)
public function init()
{
    
parent::init();
    if(
$this->autoConnect)
        
$this->setActive(true);
}

Initializes the component. This method is required by IApplicationComponent and is invoked by application when the CDbConnection is used as an application component. If you override this method, make sure to call the parent implementation so that the component can be marked as initialized.

initConnection() method
protected void initConnection(PDO $pdo)
$pdo PDO the PDO instance
Source Code: framework/db/CDbConnection.php#443 (show)
protected function initConnection($pdo)
{
    
$pdo->setAttribute(PDO::ATTR_ERRMODEPDO::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);
    }
}

Initializes the open db connection. This method is invoked right after the db connection is established. The default implementation is to set the charset for MySQL and PostgreSQL database connections.

open() method
protected void open()
Source Code: framework/db/CDbConnection.php#365 (show)
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);
            }
        }
    }
}

Opens DB connection if it is currently not

quoteColumnName() method
public string quoteColumnName(string $name)
$name string column name
{return} string the properly quoted column name
Source Code: framework/db/CDbConnection.php#586 (show)
public function quoteColumnName($name)
{
    return 
$this->getSchema()->quoteColumnName($name);
}

Quotes a column name for use in a query. If the column name contains prefix, the prefix will also be properly quoted.

quoteTableName() method
public string quoteTableName(string $name)
$name string table name
{return} string the properly quoted table name
Source Code: framework/db/CDbConnection.php#575 (show)
public function quoteTableName($name)
{
    return 
$this->getSchema()->quoteTableName($name);
}

Quotes a table name for use in a query. If the table name contains schema prefix, the prefix will also be properly quoted.

quoteValue() method
public string quoteValue(string $str)
$str string string to be quoted
{return} string the properly quoted string
Source Code: framework/db/CDbConnection.php#557 (show)
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") . "'";
}

Quotes a string value for use in a query.

setActive() method
public void setActive(boolean $value)
$value boolean whether to open or close DB connection
Source Code: framework/db/CDbConnection.php#325 (show)
public function setActive($value)
{
    if(
$value!=$this->_active)
    {
        if(
$value)
            
$this->open();
        else
            
$this->close();
    }
}

Open or close the DB connection.

setAttribute() method
public void setAttribute(integer $name, mixed $value)
$name integer the attribute to be set
$value mixed the attribute value
Source Code: framework/db/CDbConnection.php#773 (show)
public function setAttribute($name,$value)
{
    if(
$this->_pdo instanceof PDO)
        
$this->_pdo->setAttribute($name,$value);
    else
        
$this->_attributes[$name]=$value;
}

Sets an attribute on the database connection.

setAttributes() method (available since v1.1.7)
public void setAttributes(array $values)
$values array attributes (name=>value) to be set.
Source Code: framework/db/CDbConnection.php#798 (show)
public function setAttributes($values)
{
    foreach(
$values as $name=>$value)
        
$this->_attributes[$name]=$value;
}

Sets a set of attributes on the database connection.

See Also

setAutoCommit() method
public void setAutoCommit(boolean $value)
$value boolean whether creating or updating a DB record will be automatically committed.
Source Code: framework/db/CDbConnection.php#664 (show)
public function setAutoCommit($value)
{
    
$this->setAttribute(PDO::ATTR_AUTOCOMMIT,$value);
}

Sets whether creating or updating a DB record will be automatically committed. Some DBMS (such as sqlite) may not support this feature.

setColumnCase() method
public void setColumnCase(mixed $value)
$value mixed the case of the column names
Source Code: framework/db/CDbConnection.php#624 (show)
public function setColumnCase($value)
{
    
$this->setAttribute(PDO::ATTR_CASE,$value);
}

Sets the case of the column names.

setNullConversion() method
public void setNullConversion(mixed $value)
$value mixed how the null and empty strings are converted
Source Code: framework/db/CDbConnection.php#644 (show)
public function setNullConversion($value)
{
    
$this->setAttribute(PDO::ATTR_ORACLE_NULLS,$value);
}

Sets how the null and empty strings are converted.

setPersistent() method
public void setPersistent(boolean $value)
$value boolean whether the connection is persistent or not
Source Code: framework/db/CDbConnection.php#684 (show)
public function setPersistent($value)
{
    return 
$this->setAttribute(PDO::ATTR_PERSISTENT,$value);
}

Sets whether the connection is persistent or not. Some DBMS (such as sqlite) may not support this feature.

Total 1 comment

#14465 report it
Elecen at 2013/08/13 04:05pm
Changing the database at runtime

If you're using multiple databases for a single application with multiple instances then you will probably reach a point where you need to point the standard Yii::app()->db to a different database (i.e. applying migrations) This is fairly easy to accomplish and here's how I did it.

The db component configuration key points

'connectionString' => 'mysql:host=localhost;dbname=%s',
'autoConnect' => false,

Load the connection string from the console.php configuration file

$config = require(Yii::app()->getBasePath() . '/config/console.php');
$connectionString = $config['components']['db']['connectionString'];

Switching to another db

// assume a foreach loop where $dbName holds the next database name on every iteration
$db = Yii::app()->db;
$db->active = false;
$db->connectionString = sprintf($connectionString, $dbName);
$db->active = true;

In my case as mentioned I needed it for the CLI interface. I extend ConsoleCommand and override the run method where I iterate through all the schemas on the server applying my migrations and other command line commands

Hope this helps a bit

Leave a comment

Please to leave your comment.