?
// Start the transactions
$db->begin();
 
try {
     DB::insert('users')->values($user1)...
     DB::insert('users')->values($user2)...
     // Insert successful commit the changes
     $db->commit();
}
catch (Database_Exception $e)
{
     // Insert failed. Rolling back changes...
     $db->rollback();
 }

Parameters

string $mode = NULL - Transaction mode

Return Values

boolean

Source Code

?
public function begin($mode = NULL)
{
    // Make sure the database is connected
    $this->_connection or $this->connect();
 
    return $this->_connection->beginTransaction();
}

public commit( ) (defined in Kohana_Database_PDO) link to this

Commit the current transaction

?
// Commit the database changes
$db->commit();

Return Values

boolean

Source Code

?
public function commit()
{
    // Make sure the database is connected
    $this->_connection or $this->connect();
 
    return $this->_connection->commit();
}

public connect( ) (defined in Kohana_Database_PDO) link to this

Connect to the database. This is called automatically when the first query is executed.

?
$db->connect();

Return Values

void

Source Code

?
public function connect()
{
    if ($this->_connection)
        return;
 
    // Extract the connection parameters, adding required variabels
    extract($this->_config['connection'] + array(
        'dsn'        => '',
        'username'   => NULL,
        'password'   => NULL,
        'persistent' => FALSE,
    ));
 
    // Clear the connection parameters for security
    unset($this->_config['connection']);
 
    // Force PDO to use exceptions for all errors
    $options[PDO::ATTR_ERRMODE] = PDO::ERRMODE_EXCEPTION;
 
    if ( ! empty($persistent))
    {
        // Make the connection persistent
        $options[PDO::ATTR_PERSISTENT] = TRUE;
    }
 
    try
    {
        // Create a new PDO connection
        $this->_connection = new PDO($dsn, $username, $password, $options);
    }
    catch (PDOException $e)
    {
        throw new Database_Exception(':error',
            array(':error' => $e->getMessage()),
            $e->getCode());
    }
 
    if ( ! empty($this->_config['charset']))
    {
        // Set the character set
        $this->set_charset($this->_config['charset']);
    }
}

public create_aggregate( string $name , callback $step , callback $final [, integer $arguments = integer -1 ] ) (defined in Kohana_Database_PDO) link to this

Create or redefine a SQL aggregate function.

Works only with SQLite

Parameters

string $name required - Name of the SQL function to be created or redefined
callback $step required - Called for each row of a result set
callback $final required - Called after all rows of a result set have been processed
integer $arguments = integer -1 - Number of arguments that the SQL function takes

Return Values

boolean

Source Code

?
public function create_aggregate($name, $step, $final, $arguments = -1)
{
    $this->_connection or $this->connect();
 
    return $this->_connection->sqliteCreateAggregate(
        $name, $step, $final, $arguments
    );
}

public create_function( string $name , callback $callback [, integer $arguments = integer -1 ] ) (defined in Kohana_Database_PDO) link to this

Create or redefine a SQL function.

Works only with SQLite

Parameters

string $name required - Name of the SQL function to be created or redefined
callback $callback required - Callback which implements the SQL function
integer $arguments = integer -1 - Number of arguments that the SQL function takes

Return Values

boolean

Source Code

?
public function create_function($name, $callback, $arguments = -1)
{
    $this->_connection or $this->connect();
 
    return $this->_connection->sqliteCreateFunction(
        $name, $callback, $arguments
    );
}

public disconnect( ) (defined in Kohana_Database_PDO) link to this

Disconnect from the database. This is called automatically by Database::__destruct. Clears the database instance from Database::$instances.

?
$db->disconnect();

Return Values

boolean

Source Code

?
public function disconnect()
{
    // Destroy the PDO object
    $this->_connection = NULL;
 
    return parent::disconnect();
}

public escape( string $value ) (defined in Kohana_Database_PDO) link to this

Sanitize a string by escaping characters that could cause an SQL injection attack.

?
$value = $db->escape('any string');

Parameters

string $value required - Value to quote

Return Values

string

Source Code

?
public function escape($value)
{
    // Make sure the database is connected
    $this->_connection or $this->connect();
 
    return $this->_connection->quote($value);
}

public list_columns( string $table [, string $like = NULL , boolean $add_prefix = bool TRUE ] ) (defined in Kohana_Database_PDO) link to this

Lists all of the columns in a table. Optionally, a LIKE string can be used to search for specific fields.

?
// Get all columns from the "users" table
$columns = $db->list_columns('users');
 
// Get all name-related columns
$columns = $db->list_columns('users', '%name%');
 
// Get the columns from a table that doesn't use the table prefix
$columns = $db->list_columns('users', NULL, FALSE);

Parameters

string $table required - Table to get columns from
string $like = NULL - Column to search for
boolean $add_prefix = bool TRUE - Whether to add the table prefix automatically or not

Return Values

array

Source Code

?
public function list_columns($table, $like = NULL, $add_prefix = TRUE)
{
    throw new Kohana_Exception('Database method :method is not supported by :class',
        array(':method' => __FUNCTION__, ':class' => __CLASS__));
}

public list_tables( [ string $like = NULL ] ) (defined in Kohana_Database_PDO) link to this

List all of the tables in the database. Optionally, a LIKE string can be used to search for specific tables.

?
// Get all tables in the current database
$tables = $db->list_tables();
 
// Get all user-related tables
$tables = $db->list_tables('user%');

Parameters

string $like = NULL - Table to search for

Return Values

array

Source Code

?
public function list_tables($like = NULL)
{
    throw new Kohana_Exception('Database method :method is not supported by :class',
        array(':method' => __FUNCTION__, ':class' => __CLASS__));
}

public query( integer $type , string $sql [, mixed $as_object = bool FALSE , array $params = NULL ] ) (defined in Kohana_Database_PDO) link to this

Perform an SQL query of the given type.

?
// Make a SELECT query and use objects for results
$db->query(Database::SELECT, 'SELECT * FROM groups', TRUE);
 
// Make a SELECT query and use "Model_User" for the results
$db->query(Database::SELECT, 'SELECT * FROM users LIMIT 1', 'Model_User');

Parameters

integer $type required - Database::SELECT, Database::INSERT, etc
string $sql required - SQL query
mixed $as_object = bool FALSE - Result object class string, TRUE for stdClass, FALSE for assoc array
array $params = NULL - Object construct parameters for result class

Return Values

object - Database_Result for SELECT queries
array - List (insert id, row count) for INSERT queries
integer - Number of affected rows for all other queries

Source Code

?
public function query($type, $sql, $as_object = FALSE, array $params = NULL)
{
    // Make sure the database is connected
    $this->_connection or $this->connect();
 
    if ( ! empty($this->_config['profiling']))
    {
        // Benchmark this query for the current instance
        $benchmark = Profiler::start("Database ({$this->_instance})", $sql);
    }
 
    try
    {
        $result = $this->_connection->query($sql);
    }
    catch (Exception $e)
    {
        if (isset($benchmark))
        {
            // This benchmark is worthless
            Profiler::delete($benchmark);
        }
 
        // Convert the exception in a database exception
        throw new Database_Exception(':error [ :query ]',
            array(
                ':error' => $e->getMessage(),
                ':query' => $sql
            ),
            $e->getCode());
    }
 
    if (isset($benchmark))
    {
        Profiler::stop($benchmark);
    }
 
    // Set the last query
    $this->last_query = $sql;
 
    if ($type === Database::SELECT)
    {
        // Convert the result into an array, as PDOStatement::rowCount is not reliable
        if ($as_object === FALSE)
        {
            $result->setFetchMode(PDO::FETCH_ASSOC);
        }
        elseif (is_string($as_object))
        {
            $result->setFetchMode(PDO::FETCH_CLASS, $as_object, $params);
        }
        else
        {
            $result->setFetchMode(PDO::FETCH_CLASS, 'stdClass');
        }
 
        $result = $result->fetchAll();
 
        // Return an iterator of results
        return new Database_Result_Cached($result, $sql, $as_object, $params);
    }
    elseif ($type === Database::INSERT)
    {
        // Return a list of insert id and rows created
        return array(
            $this->_connection->lastInsertId(),
            $result->rowCount(),
        );
    }
    else
    {
        // Return the number of rows affected
        return $result->rowCount();
    }
}

public rollback( ) (defined in Kohana_Database_PDO) link to this

Abort the current transaction

?
// Undo the changes
$db->rollback();

Return Values

boolean

Source Code

?
public function rollback()
{
    // Make sure the database is connected
    $this->_connection or $this->connect();
 
    return $this->_connection->rollBack();
}

public set_charset( string $charset ) (defined in Kohana_Database_PDO) link to this

Set the connection character set. This is called automatically by Database::connect.

?
$db->set_charset('utf8');

Parameters

string $charset required - Character set name

Return Values

void

Source Code

?
public function set_charset($charset)
{
    // Make sure the database is connected
    $this->_connection or $this->connect();
 
    // Execute a raw SET NAMES query
    $this->_connection->exec('SET NAMES '.$this->quote($charset));
}

final public __destruct( ) (defined in Kohana_Database) link to this

Disconnect from the database when the object is destroyed.

?
// Destroy the database instance
unset(Database::instances[(string) $db], $db);

Calling unset($db) is not enough to destroy the database, as it will still be stored in Database::$instances.

Return Values

void

Source Code

?
final public function __destruct()
{
    $this->disconnect();
}

final public __toString( ) (defined in Kohana_Database) link to this

Returns the database instance name.

?
echo (string) $db;

Return Values

string

Source Code

?
final public function __toString()
{
    return $this->_instance;
}

public count_records( mixed $table ) (defined in Kohana_Database) link to this

Count the number of records in a table.

?
// Get the total number of records in the "users" table
$count = $db->count_records('users');

Parameters

mixed $table required - Table name string or array(query, alias)

Return Values

integer

Source Code

?
public function count_records($table)
{
    // Quote the table name
    $table = $this->quote_table($table);
 
    return $this->query(Database::SELECT, 'SELECT COUNT(*) AS total_row_count FROM '.$table, FALSE)
        ->get('total_row_count');
}

public datatype( string $type ) (defined in Kohana_Database) link to this

Returns a normalized array describing the SQL data type

?
$db->datatype('char');

Parameters

string $type required - SQL data type

Return Values

array

Source Code

?
public function datatype($type)
{
    static $types = array
    (
        // SQL-92
        'bit'                           => array('type' => 'string', 'exact' => TRUE),
        'bit varying'                   => array('type' => 'string'),
        'char'                          => array('type' => 'string', 'exact' => TRUE),
        'char varying'                  => array('type' => 'string'),
        'character'                     => array('type' => 'string', 'exact' => TRUE),
        'character varying'             => array('type' => 'string'),
        'date'                          => array('type' => 'string'),
        'dec'                           => array('type' => 'float', 'exact' => TRUE),
        'decimal'                       => array('type' => 'float', 'exact' => TRUE),
        'double precision'              => array('type' => 'float'),
        'float'                         => array('type' => 'float'),
        'int'                           => array('type' => 'int', 'min' => '-2147483648', 'max' => '2147483647'),
        'integer'                       => array('type' => 'int', 'min' => '-2147483648', 'max' => '2147483647'),
        'interval'                      => array('type' => 'string'),
        'national char'                 => array('type' => 'string', 'exact' => TRUE),
        'national char varying'         => array('type' => 'string'),
        'national character'            => array('type' => 'string', 'exact' => TRUE),
        'national character varying'    => array('type' => 'string'),
        'nchar'                         => array('type' => 'string', 'exact' => TRUE),
        'nchar varying'                 => array('type' => 'string'),
        'numeric'                       => array('type' => 'float', 'exact' => TRUE),
        'real'                          => array('type' => 'float'),
        'smallint'                      => array('type' => 'int', 'min' => '-32768', 'max' => '32767'),
        'time'                          => array('type' => 'string'),
        'time with time zone'           => array('type' => 'string'),
        'timestamp'                     => array('type' => 'string'),
        'timestamp with time zone'      => array('type' => 'string'),
        'varchar'                       => array('type' => 'string'),
 
        // SQL:1999
        'binary large object'               => array('type' => 'string', 'binary' => TRUE),
        'blob'                              => array('type' => 'string', 'binary' => TRUE),
        'boolean'                           => array('type' => 'bool'),
        'char large object'                 => array('type' => 'string'),
        'character large object'            => array('type' => 'string'),
        'clob'                              => array('type' => 'string'),
        'national character large object'   => array('type' => 'string'),
        'nchar large object'                => array('type' => 'string'),
        'nclob'                             => array('type' => 'string'),
        'time without time zone'            => array('type' => 'string'),
        'timestamp without time zone'       => array('type' => 'string'),
 
        // SQL:2003
        'bigint'    => array('type' => 'int', 'min' => '-9223372036854775808', 'max' => '9223372036854775807'),
 
        // SQL:2008
        'binary'            => array('type' => 'string', 'binary' => TRUE, 'exact' => TRUE),
        'binary varying'    => array('type' => 'string', 'binary' => TRUE),
        'varbinary'         => array('type' => 'string', 'binary' => TRUE),
    );
 
    if (isset($types[$type]))
        return $types[$type];
 
    return array();
}

public static instance( [ string $name = NULL , array $config = NULL ] ) (defined in Kohana_Database) link to this

Get a singleton Database instance. If configuration is not specified, it will be loaded from the database configuration file using the same group as the name.

?
// Load the default database
$db = Database::instance();
 
// Create a custom configured instance
$db = Database::instance('custom', $config);

Parameters

string $name = NULL - Instance name
array $config = NULL - Configuration parameters

Return Values

Database

Source Code

?
public static function instance($name = NULL, array $config = NULL)
{
    if ($name === NULL)
    {
        // Use the default instance name
        $name = Database::$default;
    }
 
    if ( ! isset(Database::$instances[$name]))
    {
        if ($config === NULL)
        {
            // Load the configuration for this database
            $config = Kohana::$config->load('database')->$name;
        }
 
        if ( ! isset($config['type']))
        {
            throw new Kohana_Exception('Database type not defined in :name configuration',
                array(':name' => $name));
        }
 
        // Set the driver class name
        $driver = 'Database_'.ucfirst($config['type']);
 
        // Create the database connection instance
        new $driver($name, $config);
    }
 
    return Database::$instances[$name];
}

public quote( mixed $value ) (defined in Kohana_Database) link to this

Quote a value for an SQL query.

?
$db->quote(NULL);   // 'NULL'
$db->quote(10);     // 10
$db->quote('fred'); // 'fred'

Objects passed to this function will be converted to strings. Database_Expression objects will be compiled. Database_Query objects will be compiled and converted to a sub-query. All other objects will be converted using the __toString method.

Parameters

mixed $value required - Any value to quote

Return Values

string

Source Code

?
public function quote($value)
{
    if ($value === NULL)
    {
        return 'NULL';
    }
    elseif ($value === TRUE)
    {
        return "'1'";
    }
    elseif ($value === FALSE)
    {
        return "'0'";
    }
    elseif (is_object($value))
    {
        if ($value instanceof Database_Query)
        {
            // Create a sub-query
            return '('.$value->compile($this).')';
        }
        elseif ($value instanceof Database_Expression)
        {
            // Compile the expression
            return $value->compile($this);
        }
        else
        {
            // Convert the object to a string
            return $this->quote( (string) $value);
        }
    }
    elseif (is_array($value))
    {
        return '('.implode(', ', array_map(array($this, __FUNCTION__), $value)).')';
    }
    elseif (is_int($value))
    {
        return (int) $value;
    }
    elseif (is_float($value))
    {
        // Convert to non-locale aware float to prevent possible commas
        return sprintf('%F', $value);
    }
 
    return $this->escape($value);
}

public quote_column( mixed $column ) (defined in Kohana_Database) link to this

Quote a database column name and add the table prefix if needed.

?
$column = $db->quote_column($column);

You can also use SQL methods within identifiers.

?
// The value of "column" will be quoted
$column = $db->quote_column('COUNT("column")');

Parameters

mixed $column required - Column name or array(column, alias)

Return Values

string

Source Code

?
public function quote_column($column)
{
    if (is_array($column))
    {
        list($column, $alias) = $column;
    }
 
    if ($column instanceof Database_Query)
    {
        // Create a sub-query
        $column = '('.$column->compile($this).')';
    }
    elseif ($column instanceof Database_Expression)
    {
        // Compile the expression
        $column = $column->compile($this);
    }
    else
    {
        // Convert to a string
        $column = (string) $column;
 
        if ($column === '*')
        {
            return $column;
        }
        elseif (strpos($column, '"') !== FALSE)
        {
            // Quote the column in FUNC("column") identifiers
            $column = preg_replace('/"(.+?)"/e', '$this->quote_column("$1")', $column);
        }
        elseif (strpos($column, '.') !== FALSE)
        {
            $parts = explode('.', $column);
 
            if ($prefix = $this->table_prefix())
            {
                // Get the offset of the table name, 2nd-to-last part
                $offset = count($parts) - 2;
 
                // Add the table prefix to the table name
                $parts[$offset] = $prefix.$parts[$offset];
            }
 
            foreach ($parts as & $part)
            {
                if ($part !== '*')
                {
                    // Quote each of the parts
                    $part = $this->_identifier.$part.$this->_identifier;
                }
            }
 
            $column = implode('.', $parts);
        }
        else
        {
            $column = $this->_identifier.$column.$this->_identifier;
        }
    }
 
    if (isset($alias))
    {
        $column .= ' AS '.$this->_identifier.$alias.$this->_identifier;
    }
 
    return $column;
}

public quote_identifier( mixed $value ) (defined in Kohana_Database) link to this

Quote a database identifier

Parameters

mixed $value required - Any identifier

Return Values

string

Source Code

?
public function quote_identifier($value)
{
    if (is_array($value))
    {
        list($value, $alias) = $value;
    }
 
    if ($value instanceof Database_Query)
    {
        // Create a sub-query
        $value = '('.$value->compile($this).')';
    }
    elseif ($value instanceof Database_Expression)
    {
        // Compile the expression
        $value = $value->compile($this);
    }
    else
    {
        // Convert to a string
        $value = (string) $value;
 
        if (strpos($value, '.') !== FALSE)
        {
            $parts = explode('.', $value);
 
            foreach ($parts as & $part)
            {
                // Quote each of the parts
                $part = $this->_identifier.$part.$this->_identifier;
            }
 
            $value = implode('.', $parts);
        }
        else
        {
            $value = $this->_identifier.$value.$this->_identifier;
        }
    }
 
    if (isset($alias))
    {
        $value .= ' AS '.$this->_identifier.$alias.$this->_identifier;
    }
 
    return $value;
}

public quote_table( mixed $table ) (defined in Kohana_Database) link to this

Quote a database table name and adds the table prefix if needed.

?
$table = $db->quote_table($table);

Parameters

mixed $table required - Table name or array(table, alias)

Return Values

string

Source Code

?
public function quote_table($table)
{
    if (is_array($table))
    {
        list($table, $alias) = $table;
    }
 
    if ($table instanceof Database_Query)
    {
        // Create a sub-query
        $table = '('.$table->compile($this).')';
    }
    elseif ($table instanceof Database_Expression)
    {
        // Compile the expression
        $table = $table->compile($this);
    }
    else
    {
        // Convert to a string
        $table = (string) $table;
 
        if (strpos($table, '.') !== FALSE)
        {
            $parts = explode('.', $table);
 
            if ($prefix = $this->table_prefix())
            {
                // Get the offset of the table name, last part
                $offset = count($parts) - 1;
 
                // Add the table prefix to the table name
                $parts[$offset] = $prefix.$parts[$offset];
            }
 
            foreach ($parts as & $part)
            {
                // Quote each of the parts
                $part = $this->_identifier.$part.$this->_identifier;
            }
 
            $table = implode('.', $parts);
        }
        else
        {
            // Add the table prefix
            $table = $this->_identifier.$this->table_prefix().$table.$this->_identifier;
        }
    }
 
    if (isset($alias))
    {
        // Attach table prefix to alias
        $table .= ' AS '.$this->_identifier.$this->table_prefix().$alias.$this->_identifier;
    }
 
    return $table;
}

public table_prefix( ) (defined in Kohana_Database) link to this

Return the table prefix defined in the current configuration.

?
$prefix = $db->table_prefix();

Return Values

string

Source Code

?
public function table_prefix()
{
    return $this->_config['table_prefix'];
}

protected __construct( ) (defined in Kohana_Database_PDO) link to this

Stores the database configuration locally and name the instance.

This method cannot be accessed directly, you must use Database::instance.

Return Values

void

Source Code

?
protected function __construct($name, array $config)
{
    parent::__construct($name, $config);
 
    if (isset($this->_config['identifier']))
    {
        // Allow the identifier to be overloaded per-connection
        $this->_identifier = (string) $this->_config['identifier'];
    }
}

protected _parse_type( string $type ) (defined in Kohana_Database) link to this

Extracts the text between parentheses, if any.

?
// Returns: array('CHAR', '6')
list($type, $length) = $db->_parse_type('CHAR(6)');

Parameters

string $type required - $type

Return Values

array - List containing the type and length, if any

Source Code

?
protected function _parse_type($type)
{
    if (($open = strpos($type, '(')) === FALSE)
    {
        // No length specified
        return array($type, NULL);
    }
 
    // Closing parenthesis
    $close = strrpos($type, ')', $open);
 
    // Length without parentheses
    $length = substr($type, $open + 1, $close - 1 - $open);
 
    // Type without the length
    $type = substr($type, 0, $open).substr($type, $close + 1);
 
    return array($type, $length);
}

Modules

Database_PDO extends Kohana_Database_PDO extends Database extends Kohana_Database

Constants

Properties

Methods

Constantslink to this

SELECTlink to this

INSERTlink to this

UPDATElink to this

DELETElink to this

Propertieslink to this

public static string $defaultlink to this

public static array $instanceslink to this

public string $last_querylink to this

protected $_configlink to this

protected $_connectionlink to this

protected $_identifierlink to this

protected $_instancelink to this

Methodslink to this

public begin( [ string $mode = NULL ] ) (defined in Kohana_Database_PDO) link to this

Parameters

Return Values

Source Code

public commit( ) (defined in Kohana_Database_PDO) link to this

Return Values

Source Code

public connect( ) (defined in Kohana_Database_PDO) link to this

Tags

Return Values

Source Code

public create_aggregate( string $name , callback $step , callback $final [, integer $arguments = integer -1 ] ) (defined in Kohana_Database_PDO) link to this

Parameters

Tags

Return Values

Source Code

public create_function( string $name , callback $callback [, integer $arguments = integer -1 ] ) (defined in Kohana_Database_PDO) link to this

Parameters

Tags

Return Values

Source Code

public disconnect( ) (defined in Kohana_Database_PDO) link to this

Return Values

Source Code

public escape( string $value ) (defined in Kohana_Database_PDO) link to this

Parameters

Return Values

Source Code

public list_columns( string $table [, string $like = NULL , boolean $add_prefix = bool TRUE ] ) (defined in Kohana_Database_PDO) link to this

Parameters

Return Values

Source Code

public list_tables( [ string $like = NULL ] ) (defined in Kohana_Database_PDO) link to this

Parameters

Return Values

Source Code

public query( integer $type , string $sql [, mixed $as_object = bool FALSE , array $params = NULL ] ) (defined in Kohana_Database_PDO) link to this

Parameters

Return Values

Source Code

public rollback( ) (defined in Kohana_Database_PDO) link to this

Return Values

Source Code

public set_charset( string $charset ) (defined in Kohana_Database_PDO) link to this

Parameters

Tags

Return Values

Source Code

final public __destruct( ) (defined in Kohana_Database) link to this

Return Values

Source Code

final public __toString( ) (defined in Kohana_Database) link to this

Return Values

Source Code

public count_records( mixed $table ) (defined in Kohana_Database) link to this

Parameters

Return Values

Source Code

public datatype( string $type ) (defined in Kohana_Database) link to this

Parameters

Return Values

Database_PDO
extends Kohana_Database_PDO
extends Database
extends Kohana_Database

public static `string` $defaultlink to this

public static `array` $instanceslink to this

public `string` $last_querylink to this