Stores the database configuration locally and name the instance.

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

Start a SQL transaction

// 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();
 }

Commit the current transaction

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

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

$db->connect();

Create or redefine a SQL aggregate function.

Works only with SQLite

Create or redefine a SQL function.

Works only with SQLite

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

$db->disconnect();

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

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

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);

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%');

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');

Abort the current transaction

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

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

$db->set_charset('utf8');

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.

Returns the database instance name.

echo (string) $db;

Count the number of records in a table.

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

Returns a normalized array describing the SQL data type

$db->datatype('char');

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);

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.

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.

$column = $db->quote_column(DB::expr('COUNT(`column`)'));

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.

Quote a database identifier

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.

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

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

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.

Return the table prefix defined in the current configuration.

$prefix = $db->table_prefix();

Extracts the text between parentheses, if any.

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