DBUtil Class
The DBUtil class allowes you to manage and perform routine opperations on your databases.
Managing functions
DBUtil allows you to create, rename, alter and drop database fields.
create_database($database, charset = null)
The create_database method creates a database. Will throw a Database_Exception if it cannot.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$database |
required |
the database name |
$charset |
null |
the default charset |
|
Returns |
Returns the number of affected rows. |
Throws |
\Database_Exception on failure |
Example |
// Create a database named `my_database`
DBUtil::create_database('my_database');
// Catch the exception
try
{
DBUtil::create_database('my_database');
}
catch(\Database_Exception $e)
{
// Creation failed...
}
// You can also set a default charset.
// CREATE DATABASE `new_database` DEFAULT CHARACTER SET 'utf8'
DBUtil::create_database('new_database', 'utf8');
// CREATE DATABASE `new_database DEFAULT CHARACTER SET 'utf8' COLLATE 'utf8_unicode_ci'
DBUtil::create_database('new_database', 'utf8_unicode_ci');
|
If no charset is provided it will fall back to the charset of the active db group.
drop_database($database)
The drop_database method drops a database. Will throw a Database_Exception if it cannot.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$database |
required |
the database name |
|
Returns |
Returns the number of affected rows. |
Throws |
\Database_Exception on failure |
Example |
// Drop a database named `my_database`
DBUtil::drop_database('my_database');
// Catch the exception
try
{
DBUtil::drop_database('my_database');
}
catch(\Database_Exception $e)
{
// Drop failed...
}
|
drop_table($table)
The drop_table method drops a table. Will throw a Database_Exception if it cannot.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$table |
required |
the table name |
|
Returns |
Returns the number of affected rows. |
Throws |
\Database_Exception on failure |
Example |
// Drop a table named `my_table`
DBUtil::drop_table('my_table');
// Catch the exception
try
{
DBUtil::drop_table('my_table');
}
catch(\Database_Exception $e)
{
// Drop failed...
}
|
rename_table($table, $new_table_name)
The rename_table method renames a table.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$table |
required |
The old table name |
$new_table_name |
required |
The new table name |
|
Returns |
Returns the number of affected rows. |
Throws |
\Database_Exception on failure |
Example |
// Rename `my_table` to `my_new_table`
DBUtil::rename_table('my_table', 'my_new_table');
// Catch the exception
try
{
DBUtil::rename_table('my_table', 'my_new_table');
}
catch(\Database_Exception $e)
{
// Rename failed...
}
|
create_table($table, $fields, $primary_keys = array(), $if_not_exists = true, $engine = false, $charset = null)
The create_table method creates a table.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$table |
required |
the table name |
$fields |
required |
array containing fields |
$primary_keys |
array() |
array containing primary keys |
$if_not_exists |
true |
whether to use IF NOT EXISTS |
$engine |
false |
which storage engine to use (MyISAM, InnoDB, ...) |
$charset |
null |
the default charset, falls back to the active db group charset |
|
Returns |
Returns the number of affected rows. |
Throws |
\Database_Exception on failure |
Example |
\DBUtil::create_table('users', array(
'id' => array('constraint' => 11, 'type' => 'int', 'auto_increment' => true),
'name' => array('type' => 'text'),
'email' => array('constraint' => 50, 'type' => 'varchar'),
'title' => array('constraint' => 50, 'type' => 'varchar', 'default' => 'mr.'),
'password' => array('constraint' => 125, 'type' => 'varchar'),
), array('id'), false, 'InnoDB', 'utf8_unicode_ci');
|
Possible parameters |
Param |
Description |
name |
the field name |
type |
field type (varchar, enum, text, ...) |
constraint |
Length or values. |
charset |
field charset |
unsigned |
boolean, true if is unsigned, defaults to false |
default |
default value |
null |
boolean, true if nullable, defaults to false |
auto_increment |
set to true to use auto incrementing |
|
Default fields values are escaped by default. In some cases you might want not to escape this value. If so, you can use DB::escape.
\DBUtil::create_table('users', array(
'id' => array('constraint' => 11, 'type' => 'int', 'auto_increment' => true),
'name' => array('type' => 'text'),
'email' => array('constraint' => 50, 'type' => 'varchar'),
'title' => array('constraint' => 50, 'type' => 'varchar', 'default' => 'mr.'),
'created' => array('type' => 'timestamp', 'default' => \DB::expr('CURRENT_TIMESTAMP')),
'password' => array('constraint' => 125, 'type' => 'varchar'),
), array('id'));
Escaping values work the same for DBUtil::add_fields and DBUtil::modify_fields
add_fields($table, $fields)
The modify_fields method adds fields to a table.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$table |
required |
the table name |
$fields |
required |
array containing fields |
|
Returns |
Returns the number of affected rows. |
Throws |
\Database_Exception on failure |
Example |
\DBUtil::add_fields('users', array(
'surname' => array('constraint' => 100, 'type' => 'varchar'),
'twitter_name' => array('constraint' => 100, 'type' => 'varchar'),
));
|
modify_fields($table, $fields)
The modify_fields method alters fields in a table.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$table |
required |
the table name |
$fields |
required |
array containing fields |
|
Returns |
Returns the number of affected rows. |
Throws |
\Database_Exception on failure |
Example |
\DBUtil::modify_fields('users2', array(
'name' => array('constraint' => 100, 'type' => 'varchar', 'charset' => 'utf8_general_ci'),
'title' => array('constraint' => 50, 'type' => 'varchar', 'default' => 'mrs.'),
));
|
Database operations
truncate_table($table)
The truncate_table method truncates a table.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$table |
required |
the table name. |
|
Returns |
Returns the number of affected rows. |
Throws |
\Database_Exception when not supported |
Example |
\DBUtil::truncate_table('my_table');
|
analyze_table($table)
The analyze_table method analyzes a table.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$table |
required |
the table name. |
|
Returns |
True if the table is OK. False when needs attention. If not supported it logs the error message. |
Example |
if(\DBUtil::analyze_table('table_name') === false)
{
// Do something
}
|
check_table($table)
The check_table method checks a table.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$table |
required |
the table name. |
|
Returns |
True if the table is OK. False when needs attention. If not supported it logs the error message. |
Example |
if(\DBUtil::check_table('table_name') === false)
{
// Do something
}
|
optimize_table($table)
The check_table method optimizes a table.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$table |
required |
the table name. |
|
Returns |
True if the table is OK or optimized. False on failure. If not supported or failed it logs the error message. |
Example |
if(\DBUtil::optimize_table('table_name') === false)
{
// Do something
}
|
repair_table($table)
The check_table method repairs a table.
Static |
Yes |
Parameters |
Param |
Default |
Description |
$table |
required |
the table name. |
|
Returns |
True if the table is OK or repaired. false on failure. If not supported or failed it logs the error message. |
Example |
if(\DBUtil::repair_table('table_name') === false)
{
// Do something
}
|