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.
Method Summary |
TDbTransaction
|
Starts a transaction.
|
protected
void
|
Closes the currently active DB connection.
|
TDbCommand
|
Creates a command for execution.
|
boolean
|
|
mixed
|
Obtains a specific DB connection attribute information.
|
boolean
|
|
array
|
|
string
|
|
string
|
|
TDbColumnCaseMode
|
|
string
|
|
string
|
|
TDbTransaction
|
|
string
|
|
string
|
Returns the ID of the last inserted row or sequence value.
|
TDbNullConversionMode
|
|
string
|
|
PDO
|
|
boolean
|
|
boolean
|
|
string
|
|
string
|
|
int
|
|
string
|
|
protected
void
|
Opens DB connection if it is currently not
|
string
|
Quotes a string for use in a query.
|
void
|
Open or close the DB connection.
|
void
|
Sets an attribute on the database connection.
|
void
|
|
void
|
|
void
|
|
protected
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
|
void
|
Close the connection when serializing.
|
Method Details |
beginTransaction
Starts a transaction.
Output |
TDbTransaction
| the transaction initiated |
Exception |
throws | TDbException if the connection is not active |
|
close
Closes the currently active DB connection.
It does nothing if the connection is already closed.
|
createCommand
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
|
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
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
|
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
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
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
|
setConnectionCharset
protected void setConnectionCharset |
() |
|
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
|
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
Close the connection when serializing.
|