Packages:
default
System
System.Caching
System.Collections
System.Data
System.Data.ActiveRecord
System.Data.ActiveRecord.Relations
System.Data.ActiveRecord.Scaffold
System.Data.ActiveReecord.Scaffold.InputBuilder
System.Data.Commom.Sqlite
System.Data.Common
System.Data.Common.Mssql
System.Data.Common.Mysql
System.Data.Common.Oracle
System.Data.Common.Pgsql
System.Data.Common.Sqlite
System.Data.DataGateway
System.Data.SqlMap
System.Data.SqlMap.Configuration
System.Data.SqlMap.Statements
System.Exceptions
System.I18N
System.IO
System.Security
System.Util
System.Web
System.Web.Services
System.Web.UI
System.Web.UI.ActiveControls
System.Web.UI.WebControls
System.Web.UI.WebControls.assets
System.Xml


Classes:
TDataSourceConfig
TDbColumnCaseMode
TDbCommand
TDbConnection
TDbDataReader
TDbNullConversionMode
TDbTransaction
Keyword

Class TDbConnection

TComponent
   |
   --TDbConnection

TDbConnection class

TDbConnection represents a connection to a database.

TDbConnection works together with TDbCommand, TDbDataReader and TDbTransaction 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.

Since 3.1.2, the connection charset can be set (for MySQL and PostgreSQL databases only) using the Charset property. The value of this property is database dependant. e.g. for mysql, you can use 'latin1' for cp1252 West European, 'utf8' for unicode, ...

The following example shows how to create a TDbConnection instance and establish the actual connection: 

  1.  $connection=new TDbConnection($dsn,$username,$password);
    2. 

  2.  $connection->Active=true;
    3.

After the DB connection is established, one can execute an SQL statement like the following: 

  1.  $command=$connection->createCommand($sqlStatement);
    2. 

  2.  $command->execute();   // a non-query SQL statement execution
    3. 

  3.  // or execute an SQL query and fetch the result set
    4. 

  4.   $reader=$command->query();
    5. 

  5.  
    6. 

  6.  // each $row is an array representing a row of data
    7. 

  7.   foreach($reader as $row) ...
    8.

One can do prepared SQL execution and bind parameters to the prepared SQL: 

  1.  $command=$connection->createCommand($sqlStatement);
    2. 

  2.  $command->bindParameter($name1,$value1);
    3. 

  3.  $command->bindParameter($name2,$value2);
    4. 

  4.  $command->execute();
    5.

To use transaction, do like the following: 

  1.  $transaction=$connection->beginTransaction();
    2. 

  2.  try
    3. 

  3.  {
    4. 

  4.     $connection->createCommand($sql1)->execute();
    5. 

  5.     $connection->createCommand($sql2)->execute();
    6. 

  6.     //.... other SQL executions
    7. 

  7.         $transaction->commit();
    8. 

  8.  }
    9. 

  9.  catch(Exception $e)
    10. 

  10.  {
    11. 

  11.     $transaction->rollBack();
    12. 

  12.  }
    13.

TDbConnection provides a set of methods to support setting and querying of certain DBMS attributes, such as NullConversion.

Since: 3.0
Author: Qiang Xue <qiang.xue@gmail.com>
Constructor Summary
public
__construct Array
Constructor.
Method Summary
TDbTransaction
beginTransaction ()
Starts a transaction.
protected  void
close ()
Closes the currently active DB connection.
TDbCommand
createCommand ( string $sql)
Creates a command for execution.
boolean
getActive ()
mixed
getAttribute ( int $name)
Obtains a specific DB connection attribute information.
boolean
getAutoCommit ()
array
getAvailableDrivers ()
string
getCharset ()
string
getClientVersion ()
TDbColumnCaseMode
getColumnCase ()
string
getConnectionStatus ()
string
getConnectionString ()
TDbTransaction
getCurrentTransaction ()
string
getDriverName ()
string
getLastInsertID ( string $sequenceName)
Returns the ID of the last inserted row or sequence value.
TDbNullConversionMode
getNullConversion ()
string
getPassword ()
PDO
getPdoInstance ()
boolean
getPersistent ()
boolean
getPrefetch ()
string
getServerInfo ()
string
getServerVersion ()
int
getTimeout ()
string
getUsername ()
protected  void
open ()
Opens DB connection if it is currently not
string
quoteString ( string $str)
Quotes a string for use in a query.
void
setActive ( boolean $value)
Open or close the DB connection.
void
setAttribute ( int $name, mixed $value)
Sets an attribute on the database connection.
void
setAutoCommit ( boolean $value)
void
setCharset ( string $value)
void
setColumnCase ( TDbColumnCaseMode $value)
protected  void
setConnectionCharset ()
void
setConnectionString ( string $value)
void
setNullConversion ( TDbNullConversionMode $value)
void
setPassword ( string $value)
void
setPersistent ( boolean $value)
void
setUsername ( string $value)
void
__sleep ()
Close the connection when serializing.
Methods Inherited From TComponent
TComponent::addParsedObject(), TComponent::attachEventHandler(), TComponent::canGetProperty(), TComponent::canSetProperty(), TComponent::createdOnTemplate(), TComponent::detachEventHandler(), TComponent::evaluateExpression(), TComponent::evaluateStatements(), TComponent::getEventHandlers(), TComponent::getSubProperty(), TComponent::hasEvent(), TComponent::hasEventHandler(), TComponent::hasProperty(), TComponent::raiseEvent(), TComponent::setSubProperty(), TComponent::__get(), TComponent::__set()
Constructor Details

__construct

public __construct Array

Constructor.

Note, the DB connection is not established when this connection instance is created. Set Active property to true to establish the connection. Since 3.1.2, you can set the charset for MySql connection

See: http://www.php.net/manual/en/function.PDO-construct.php
Method Details

beginTransaction

public TDbTransaction beginTransaction ()

Starts a transaction.

Output
TDbTransaction the transaction initiated
Exception
throwsTDbException if the connection is not active

close

protected void close ()

Closes the currently active DB connection.

It does nothing if the connection is already closed.

Output
Exception

createCommand

public TDbCommand createCommand (string $sql )

Creates a command for execution.

Input
string$sqlSQL statement associated with the new command.
Output
TDbCommand the DB command
Exception
throwsTDbException if the connection is not active

getActive

public boolean getActive ()

Output
boolean whether the DB connection is established
Exception

getAttribute

public mixed getAttribute (int $name )

Obtains a specific DB connection attribute information.

Input
int$namethe attribute to be queried
Output
mixed the corresponding attribute information
Exception

getAutoCommit

public boolean getAutoCommit ()

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

getAvailableDrivers

public array getAvailableDrivers ()

Output
array list of available PDO drivers
Exception

getCharset

public string getCharset ()

Output
string the charset used for database connection. Defaults to emtpy string.
Exception

getClientVersion

public string getClientVersion ()

Output
string the version information of the DB driver
Exception

getColumnCase

public TDbColumnCaseMode getColumnCase ()

Output
TDbColumnCaseMode the case of the column names
Exception

getConnectionStatus

public string getConnectionStatus ()

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

getConnectionString

public string getConnectionString ()

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

getCurrentTransaction

public TDbTransaction getCurrentTransaction ()

Output
TDbTransaction the currently active transaction. Null if no active transaction.
Exception

getDriverName

public string getDriverName ()

Output
string name of the DB driver
Exception

getLastInsertID

public string getLastInsertID (string $sequenceName )

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

Input
string$sequenceNamename of the sequence object (required by some DBMS)
Output
string the row ID of the last row inserted, or the last value retrieved from the sequence object
Exception

getNullConversion

public TDbNullConversionMode getNullConversion ()

Output
TDbNullConversionMode how the null and empty strings are converted
Exception

getPassword

public string getPassword ()

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

getPdoInstance

public PDO getPdoInstance ()

Output
PDO the PDO instance, null if the connection is not established yet
Exception

getPersistent

public boolean getPersistent ()

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

getPrefetch

public boolean getPrefetch ()

Output
boolean whether the connection performs data prefetching
Exception

getServerInfo

public string getServerInfo ()

Output
string the information of DBMS server
Exception

getServerVersion

public string getServerVersion ()

Output
string the version information of DBMS server
Exception

getTimeout

public int getTimeout ()

Output
int timeout settings for the connection
Exception

getUsername

public string getUsername ()

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

open

protected void open ()

Opens DB connection if it is currently not

Output
Exception
throwsTDbException if connection fails

quoteString

public string quoteString (string $str )

Quotes a string for use in a query.

Input
string$strstring to be quoted
Output
string the properly quoted string
Exception

setActive

public void setActive (boolean $value )

Open or close the DB connection.

Input
boolean$valuewhether to open or close DB connection
Output
Exception
throwsTDbException if connection fails

setAttribute

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

Sets an attribute on the database connection.

Input
int$namethe attribute to be set
mixed$valuethe attribute value
Output
Exception

setAutoCommit

public void setAutoCommit (boolean $value )

Input
boolean$valuewhether creating or updating a DB record will be automatically committed. Some DBMS (such as sqlite) may not support this feature.
Output
Exception

setCharset

public void setCharset (string $value )

Input
string$valuethe charset used for database connection
Output
Exception

setColumnCase

public void setColumnCase (TDbColumnCaseMode $value )

Input
TDbColumnCaseMode$valuethe case of the column names
Output
Exception

setConnectionCharset

protected void setConnectionCharset ()

Output
Exception

setConnectionString

public void setConnectionString (string $value )

Input
string$valueThe Data Source Name, or DSN, contains the information required to connect to the database.
Output
Exception

setNullConversion

public void setNullConversion (TDbNullConversionMode $value )

Input
TDbNullConversionMode$valuehow the null and empty strings are converted
Output
Exception

setPassword

public void setPassword (string $value )

Input
string$valuethe password for establishing DB connection
Output
Exception

setPersistent

public void setPersistent (boolean $value )

Input
boolean$valuewhether the connection is persistent or not Some DBMS (such as sqlite) may not support this feature.
Output
Exception

setUsername

public void setUsername (string $value )

Input
string$valuethe username for establishing DB connection
Output
Exception

__sleep

public void __sleep ()

Close the connection when serializing.

Output
Exception