DBUtil - 类別 - FuelPHP 简体中文手册

DBUtil 类別

DBUtil 类別能让你對資料庫做管理和执行例行操作。

管理函式

DBUtil 能让你建立、更名、改變和除去資料庫欄位。

set_connection($connection)

set_connection 方法为所有方法設定預設 DBUtil 連線。

靜態是

參数

參数	預設	描述
`$connection`	必要	資料庫連線。

回傳回傳受影響的列数。

拋出 \Database_Exception 在失敗時

範例

// 为 DBUtil 設定一个替代的資料庫連線
DBUtil::set_connection('my_database_group');

// 用該連線做其他 DBUtil 呼叫。
...

// 然後設定它回到預設。
DBUtil::set_connection(null);

create_database($database, charset = null, $if_not_exists = true, $db = null)

create_database 方法建立一个資料庫，如果失敗将拋出一个 Database_Exception。

靜態是

參数

參数	預設	描述
`$database`	必要	資料庫名稱
`$charset`	null	預設字符集
`$if_not_exists`	true	是否使用 IF NOT EXISTS
`$db`	`null`	資料庫連線。

回傳回傳受影響的列数。

拋出 \Database_Exception 在失敗時

範例

// 建立名为 `my_database` 的資料庫
DBUtil::create_database('my_database');

// 捕捉例外
try
{
	DBUtil::create_database('my_database');
}
catch(\Database_Exception $e)
{
	// 建立失敗……
}

// 你也可以設定預設字符集。
// CREATE DATABASE IF NOT EXISTS `new_database` DEFAULT CHARACTER SET 'utf8'
DBUtil::create_database('new_database', 'utf8');

// CREATE DATABASE IF NOT EXISTS `new_database  DEFAULT CHARACTER SET 'utf8' COLLATE 'utf8_unicode_ci'
DBUtil::create_database('new_database', 'utf8_unicode_ci');

如果沒有提供字符集，将退回到活动 db 群組的字符集。

drop_database($database, $db = null)

drop_database 方法除去一个資料庫，如果失敗将拋出一个 Database_Exception。

靜態是

參数

參数	預設	描述
`$database`	必要	資料庫名稱
`$db`	`null`	資料庫連線。

回傳回傳受影響的列数。

拋出 \Database_Exception 在失敗時

範例

// 除去名为 `my_database` 的資料庫
DBUtil::drop_database('my_database');

// 捕捉例外
try
{
	DBUtil::drop_database('my_database');
}
catch(\Database_Exception $e)
{
	// 除去失敗……
}

table_exists($table, $db = null)

table_exists 方法確認所給的資料表是否存在。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱
`$db`	`null`	資料庫連線。

回傳回傳 true 如果資料表存在，false 如果不存在。

範例

// 確認名为 'my_table' 的資料表是否存在
if(DBUtil::table_exists('my_table'))
{
	// 資料表存在
} else
{
	// 資料表不存在，建立它！
}

drop_table($table, $db = null)

drop_table 方法除去一張資料表，如果失敗将拋出一个 Database_Exception。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱
`$db`	`null`	資料庫連線。

回傳回傳受影響的列数。

拋出 \Database_Exception 在失敗時

範例

// 除去名为 `my_table` 的資料表
DBUtil::drop_table('my_table');

// 捕捉例外
try
{
	DBUtil::drop_table('my_table');
}
catch(\Database_Exception $e)
{
	// 除去失敗……
}

rename_table($table, $new_table_name, $db = null)

rename_table 方法更名一張資料表。

靜態是

參数

參数	預設	描述
`$table`	必要	舊的資料表名稱
`$new_table_name`	必要	新的資料表名稱

回傳回傳受影響的列数。

拋出 \Database_Exception 在失敗時

範例

// 更名 `my_table` 为 `my_new_table`
DBUtil::rename_table('my_table', 'my_new_table');

// 捕捉例外
try
{
	DBUtil::rename_table('my_table', 'my_new_table');
}
catch(\Database_Exception $e)
{
	// 更名失敗……
}

create_table($table, $fields, $primary_keys = array(), $if_not_exists = true, $engine = false, $charset = null, $foreign_keys = array(), $db = null)

create_table 方法建立一張資料表。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱
`$fields`	必要	包含欄位的陣列
`$primary_keys`	array()	包含主鍵的陣列
`$if_not_exists`	true	是否使用 IF NOT EXISTS
`$engine`	false	要使用哪个儲存引擎（MyISAM、InnoDB、……）
`$charset`	`null`	預設字符集，退回到活动 db 群組字符集
`$foreign_keys`	array()	外鍵約束定義的陣列，陣列鍵 'key' 和 'reference' 是必要的，且如果缺少会拋出一个错误，所有其他的是選擇性的。
`$db`	`null`	資料庫連線。

回傳回傳受影響的列数。

拋出 \Database_Exception 在失敗時

範例

\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',
	array(
		array(
			'constraint' => 'constraintA',
			'key' => 'keyA',
			'reference' => array(
				'table' => 'table',
				'column' => 'field',
			),
			'on_update' => 'CASCADE',
			'on_delete' => 'RESTRICT'
		),
		array(
			'key' => 'keyB',
			'reference' => array(
				'table' => 'table',
				'column' => array(
					'fieldA',
					'fieldB'
				),
			),
		),
	),
);

/* 產生以下的 SQL 語句：
CREATE TABLE `users` (
	`id` int(11) NOT NULL AUTO_INCREMENT,
	`name` text NOT NULL,
	`email` varchar(50) NOT NULL,
	`title` varchar(50) DEFAULT 'mr.' NOT NULL,
	`password` varchar(125) NOT NULL,
	PRIMARY KEY `id` (`id`),
	CONSTRAINT constraintA FOREIGN KEY (keyA) REFERENCES table (field) ON UPDATE CASCADE ON DELETE RESTRICT,
	FOREIGN KEY (keyB) REFERENCES table (fieldA, fieldB)
) ENGINE = InnoDB  DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;
*/

可能的參数

參数	描述
`name`	欄位名稱
`type`	欄位型態（varchar、enum、text、……）
`constraint`	長度或值，值可以被提供在一个陣列中
`charset`	欄位字符集
`unsigned`	布林，true 如果無符號，預設为 false
`default`	預設值
`null`	布林，true 如果可为空，預設为 false
`auto_increment`	設为 true 以使用自动遞增
`comment`	添加註釋到你的欄位

預設欄位值預設情況下会被轉義，在一些情況下你可能不想轉義此值，如果是这樣，你可以使用 DB::expr。

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

轉義值也同樣運作在 DBUtil::add_fields 和 DBUtil::modify_fields

field_exists($table, $columns, $db = null)

field_exists 方法確認是否所給的欄位（們）在所給的資料表中存在。

靜態是

參数

參数	預設	描述
$table	必要	資料表名稱
$columns	必要	包含欄位的陣列
`$db`	`null`	資料庫連線。

回傳回傳 true 如果欄位／行存在，否則 false

範例


if(DBUtil::field_exists('my_table', array('my_field_or_column')))
{
	// 欄位存在
}
else
{
	// 欄位在資料表不可用
}

add_fields($table, $fields, $db = null)

add_fields 方法添加欄位到資料表。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱
`$fields`	必要	包含欄位的陣列
`$db`	`null`	資料庫連線。

回傳回傳受影響的列数。

拋出 \Database_Exception 在失敗時

範例

\DBUtil::add_fields('users', array(
	'surname' => array('constraint' => 100, 'type' => 'varchar'),
	'twitter_name' => array('constraint' => 100, 'type' => 'varchar'),
));

drop_fields($table, $fields, $db = null)

drop_fields 方法從資料表除去欄位。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱的字串
`$fields`	必要	字串或包含欄位的陣列
`$db`	`null`	資料庫連線。

回傳回傳受影響的列数。

拋出 \Database_Exception 在失敗時

範例

\DBUtil::drop_fields('users', 'surname');

modify_fields($table, $fields, $db = null)

modify_fields 方法修改在資料表中的欄位。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱
`$fields`	必要	包含欄位的陣列
`$db`	`null`	資料庫連線。

回傳回傳受影響的列数。

拋出 \Database_Exception 在失敗時

範例

\DBUtil::modify_fields('users2', array(
	'name' => array('constraint' => 100, 'type' => 'varchar', 'charset' => 'utf8_general_ci'),
	'title' => array('constraint' => 50, 'type' => 'varchar', 'default' => 'mrs.'),
));

create_index($table, $index_columns, $index_name, $index = '', $db = null)

create_index 方法能让你在資料表建立次要索引。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱
`$index_columns`	選擇性	混合，字串或包含欄位字串的陣列
`$index_name`	必要	要被建立的索引名稱
`$index`	選擇性	要被建立的索引类型。目前支援：UNIQUE、FULLTEXT、SPATIAL、NONCLUSTERED
`$db`	`null`	資料庫連線。

回傳回傳資料庫操作的結果。

拋出 \Database_Exception 在失敗時

範例

\DBUtil::create_index('table', 'name');
// 產生 CREATE INDEX name ON table ( `name` )

\DBUtil::create_index('table', array('nameA', 'nameB'), 'name');
// 產生 CREATE INDEX name ON table ( `nameA`, `nameB` )

\DBUtil::create_index('table', array('nameA' => 'ASC', 'nameB'), 'name', 'fulltext');
// 產生 CREATE FULLTEXT INDEX name ON table ( `nameA` ASC, `nameB` )

drop_index($table, $index_name, $db = null)

drop_index 方法能让你從資料表除去次要索引。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱
`$index_name`	必要	要被除去的索引名稱
`$db`	`null`	資料庫連線。

回傳回傳資料庫操作的結果。

拋出 \Database_Exception 在失敗時

範例

\DBUtil::drop_index('table', 'name');
// 產生 DROP INDEX name ON table

add_foregin_key($table, $foreign_key)

add_foreign_key 方法能让你在資料表建立後添加外鍵。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱
`$foreign_key`	必要	包含外鍵定義的陣列。

回傳回傳資料庫操作的結果。

拋出 \InvalidArgumentException 在無效輸入時，\Database_Exception 在失敗時

範例

\DBUtil::add_foreign_key('users', array(
	'constraint' => 'constraintA',
	'key' => 'keyA',
	'reference' => array(
		'table' => 'table',
		'column' => 'field',
	),
	'on_update' => 'CASCADE',
	'on_delete' => 'RESTRICT'
));

drop_foreign_key($table, $fk_name)

drop_foreign_key 方法能让你從資料表除去外鍵。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱
`$fk_name`	必要	要被除去的外鍵名稱

回傳回傳資料庫操作的結果。

拋出 \Database_Exception 在失敗時

範例

\DBUtil::drop_foreign_key('table', 'name');
// 產生 ALTER TABLE `table` DROP FOREIGN KEY name

資料庫操作

truncate_table($table, $db = null)

truncate_table 方法截斷一張資料表。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱。
`$db`	`null`	資料庫連線。

回傳回傳受影響的列数。

拋出 \Database_Exception 當不支援時

範例

\DBUtil::truncate_table('my_table');

analyze_table($table, $db = null)

analyze_table 分析一張資料表。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱。
`$db`	`null`	資料庫連線。

回傳 True 如果資料表是 OK 的。False 當需要注意時。如果不支援它会記錄错误訊息。

範例

if(\DBUtil::analyze_table('table_name') === false)
{
	// 做點什么
}

check_table($table, $db = null)

check_table 方法確認一張資料表。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱。
`$db`	`null`	資料庫連線。

回傳 True 如果資料表是 OK 的。False 當需要注意時。如果不支援它会記錄错误訊息。

範例

if(\DBUtil::check_table('table_name') === false)
{
	// 做點什么
}

optimize_table($table, $db = null)

optimize_table 方法優化一張資料表。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱。
`$db`	`null`	資料庫連線。

回傳 True 如果資料表是 OK 或已優化的。False 在失敗時。如果不支援或失敗它会記錄错误訊息。

範例

if(\DBUtil::optimize_table('table_name') === false)
{
	// 做點什么
}

repair_table($table, $db = null)

repair_table 方法修復一張資料表。

靜態是

參数

參数	預設	描述
`$table`	必要	資料表名稱。
`$db`	`null`	資料庫連線。

回傳 True 如果資料表是 OK 或已修復的。false 在失敗時。如果不支援或失敗它会記錄错误訊息。

範例

if(\DBUtil::repair_table('table_name') === false)
{
	// 做點什么
}