当前位置: 首页 > 文档资料 > FuelPHP 中文文档 >

DBUtil - 类別

优质
小牛编辑
131浏览
2023-12-01

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必要资料库名称
$charsetnull预设字符集
$if_not_existstrue是否使用 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_keysarray()包含主键的阵列
$if_not_existstrue是否使用 IF NOT EXISTS
$enginefalse要使用哪个储存引擎(MyISAM、InnoDB、……)
$charset
null
预设字符集,退回到活动 db 群组字符集
$foreign_keysarray()外键约束定义的阵列,阵列键 '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)
{
	// 做点什幺
}