- Home
- About
- Testimonials
- Demos
- Download
- Documentation
- Blogs
- Forum
- Support

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:

     $connection=new TDbConnection($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->bindParameter($name1,$value1);
     $command->bindParameter($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();
     }

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
throws | TDbException 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 | $sql | SQL statement associated with the new command.
Output
TDbCommand | the DB command
Exception
throws | TDbException 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 | $name | the 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 | $sequenceName | name 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
throws | TDbException if connection fails

## quoteString

public string quoteString | (string $str )

Quotes a string for use in a query.

Input
string | $str | string to be quoted
Output
string | the properly quoted string
Exception

## setActive

public void setActive | (boolean $value )

Open or close the DB connection.

Input
boolean | $value | whether to open or close DB connection
Output
Exception
throws | TDbException if connection fails

## setAttribute

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

Sets an attribute on the database connection.

Input
int | $name | the attribute to be set
mixed | $value | the attribute value
Output
Exception

## setAutoCommit

public void setAutoCommit | (boolean $value )

Input
boolean | $value | whether 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 | $value | the charset used for database connection
Output
Exception

## setColumnCase

public void setColumnCase | (TDbColumnCaseMode $value )

Input
TDbColumnCaseMode | $value | the case of the column names
Output
Exception

## setConnectionCharset

protected void setConnectionCharset | ()

Output
Exception

## setConnectionString

public void setConnectionString | (string $value )

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

## setNullConversion

public void setNullConversion | (TDbNullConversionMode $value )

Input
TDbNullConversionMode | $value | how the null and empty strings are converted
Output
Exception

## setPassword

public void setPassword | (string $value )

Input
string | $value | the password for establishing DB connection
Output
Exception

## setPersistent

public void setPersistent | (boolean $value )

Input
boolean | $value | whether 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 | $value | the username for establishing DB connection
Output
Exception

## __sleep

public void __sleep | ()

Close the connection when serializing.

Output
Exception