DBUtil - 类別

优质

小牛编辑

119浏览

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`	必要	资料库名称
`$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)
{
	// 做点什幺
}