Perl-DBI 指南 Release V8R6 Nov 08, 2021 北京人大金仓信息技术股份有限公司 Email: support@kingbase.com.cn
目 录 目录....................................................... 1 1 概述 2 2 DBI 类 3 2.1 DBI 类方法................................................ 3 2.2 句柄的通用方法............................................. 4 3 DBI 数据库句柄对象 6 3.1 数据库句柄方法............................................. 6 3.2 数据库句柄属性............................................. 10 4 DBI 语句句柄对象 12 4.1 语句句柄方法.............................................. 12 4.2 语句句柄属性.............................................. 16 5 示例 18 5.1 示例 1................................................... 18 A 版权声明 19 1
第 1 章 概述 KingbaseES database driver for the DBI module 是为了向用户提供使用 Perl 语言访问数据库的接口, 使用户可以在使用 Perl 语言开发时使用 KingbaseES 数据库 本手册详细说明了 DBD::KB 中提供的接口和方法, 以及使用时应该注意的情况和使用示例 2
第 2 章 DBI 类 2.1 DBI 类方法 a. connect $dbh = DBI->connect($data_source, $username, $password, \%attr); 该方法可建立与所查询的数据库 $data_source 相连的数据库连接或者会话 如果连接成功, 返回一个数据库句柄对象 可以使用 $dbh->disconnect 来终止这个连接 如果连接失败, 将返回 undef 并且设置 $DBI::err 和 $DBI::errstr 参数说明 : $data_source 包含了连接到数据库的参数, 应当以 dbi::kb 开头 如果没有定义或是定义为空, 将用环境变量 DBI_DSN 代替这个值 连接参数如下表所示 : 表 2.1.1: 连接参数 parameter hard coded default host local domain socket hostaddr local domain socket port 54321 dbname* current userid username current userid password (none) options (none) service (none) sslmode (none) 3
\%attr 参数用来改变 PrintError,RaiseError,AutoCommit 及其他属性的缺省设置 b. connect_cached $dbh = DBI->connect_cached( dbi:kb:dbname=$dbname, $username, $password, \%options); 作用与 connect 相似, 返回相应缓存的数据库句柄 c. data_sources @data_sources = DBI->data_sources( KB ); @data_sources = $dbh->data_sources(); 使用给定的驱动程序名, 返回所有可用的数据源的列表 2.2 句柄的通用方法 这些方法对所有的 DBI 句柄都是通用的 a. err $rv = $h->err; 返回最后一次调用的错误代码 b. errstr $str = $h->errstr; 返回错误信息 c. state $str = $h->state; 返回一个五个字符表示的 SQLSTATE 代码 d. trace $h->trace($trace_settings); $h->trace($trace_settings, $trace_filename); $trace_settings = $h->trace; 2.2. 句柄的通用方法 4
修改数据库句柄或者语句句柄上的 trace 设置 e. trace_msg $h->trace_msg($message_text); $h->trace_msg($message_text, $min_level); 把输出信息写到文件中 $min_level 表示日志级别 f. private_attribute_info $hashref = $dbh->private_attribute_info(); $hashref = $sth->private_attribute_info(); 返回所有的 DBD::KB 的私有属性的哈希引用 2.2. 句柄的通用方法 5
第 3 章 DBI 数据库句柄对象 本部分将列出与 DBI 数据库句柄相关的方法和属性 更详细的信息可参考 DBI 的规范, 本文不详细说明各方法和属性的相关信息 对于私有方法和属性, 本文将详细说明 3.1 数据库句柄方法 1. selectall_arrayref $ary_ref = $dbh->selectall_arrayref($sql); $ary_ref = $dbh->selectall_arrayref($sql, \%attr); $ary_ref = $dbh->selectall_arrayref($sql, \%attr, @bind_values); 返回一个数组引用 数组中的元素是指向取回的每一行数据的引用 2. selectall_hashref $hash_ref = $dbh->selectall_hashref($sql, $key_field); 作用与 selectall_arrayref 相似, 返回一个哈希引用 3. selectcol_arrayref $ary_ref = $dbh->selectcol_arrayref($sql, \%attr, @bind_values); 6
返回一个含有每一行第一列值的数组的引用 4. prepare $sth = $dbh->prepare($statement, \%attr); 对语句做预处理, 并且返回一个语句句柄对象的引用 5. prepare_cached $sth = $dbh->prepare_cached($statement, \%attr); 与 prepare 类似 返回的语句句柄存储在一个与 $dbh 有关的哈希列表中 如果使用同一组 $statement 和 %attr 值调用另外一个 prepare_cached, 那么不与数据库服务器交互就可以返回相应的 $sth 6. do $rv = $dbh->do($statement); $rv = $dbh->do($statement, \%attr); $rv = $dbh->do($statement, \%attr, @bind_values); 预处理并执行单个 SQL 语句 返回所影响的行数, 或者出错时返回 undef 如果返回 -1 表示不知道这个行数或者不能得到行数 该方法适用于不需预处理或者不需重复执行的非 SELECT 语句 如果使用该方法执行 SELECT 语句, 将不返回任何数据 7. last_insert_id $rv = $dbh->last_insert_id(undef, $schema, $table, undef); $rv = $dbh->last_insert_id(undef, $schema, $table, undef, {sequence => $seqname}); 返回最后插入的一行数据的序列值 8. commit $rv = $dbh->commit; 如果 AutoCommit 处于 off 状态, 该方法将提交最近的数据库修改 如果 AutoCommit 处于 on 状态, 该方法将产生一个提交无效的警告 9. rollback $rv = $dbh->rollback; 3.1. 数据库句柄方法 7
如果 AutoCommit 处于 off 状态, 该方法将最近未提交的数据库修改进行回滚操作 如果 AutoCommit 处于 on 状态, 该方法将产生一个回滚无效的警告 10. begin_work $rv = $dbh->begin_work; 该方法将开始一个事务, 直到调用 commit 或者 rollback 如果 AutoCommit 处于 on 状态, 该方法无效 11. disconnect $rv = $dbh->disconnect; 断开数据库连接 数据库句柄在断开连接后就无效了 12. quote $rv = $dbh->quote($value, $data_type); 将数据按照该驱动程序的标准转换成可识别的格式 例如 : 将单个单引号或反斜线转换成两个 13. quote_identifier $string = $dbh->quote_identifier( $name ); $string = $dbh->quote_identifier( undef, $schema, $table); 14. ping 返回给定的字符串的标识符的形式 这些字符串为表名, 列名或者模式名 $rv = $dbh->ping; 检查数据库句柄是否有效 15. table_info $sth = $dbh->table_info(undef, $schema, $table, $type); 返回数据库中所有的表和视图的信息 16. column_info $sth = $dbh->column_info( undef, $schema, $table, $column ); 3.1. 数据库句柄方法 8
返回数据库中所有的列信息 17. primary_key_info $sth = $dbh->primary_key_info( undef, $schema, $table, \%attr ); 返回表的主键信息 如果没有指定模式名, 使用 search path 中的第一个模式名 18. primary_key @key_column_names = $dbh->primary_key(undef, $schema, $table); 返回表的主键包含的所有列名 如果没有主键, 返回空值 19. foreign_key_info $sth = $dbh->foreign_key_info( $pk_catalog, $pk_schema, $pk_table, $fk_catalog, $fk_schema, $fk_table ); 返回表的外键信息 20. statistics_info $sth = $dbh->statistics_info( undef, $schema, $table, $unique_only, $quick ); 返回一个能取到表的所有统计信息的语句句柄 21. tables @names = $dbh->tables( undef, $schema, $table, $type, \%attr ); 返回当前用户可见的所有表的信息 22. type_info_all $type_info_all = $dbh->type_info_all; 返回常用的 SQL 数据类型的信息 23. type_info @type_info = $dbh->type_info($data_type); 3.1. 数据库句柄方法 9
返回包含该数据类型所有信息的哈希列表 24. selectrow_array @row_ary = $dbh->selectrow_array($sql); @row_ary = $dbh->selectrow_array($sql, \%attr); @row_ary = $dbh->selectrow_array($sql, \%attr, @bind_values); 返回一个包含所有行信息的数组 25. selectrow_arrayref $ary_ref = $dbh->selectrow_arrayref($statement); $ary_ref = $dbh->selectrow_arrayref($statement, \%attr); $ary_ref = $dbh->selectrow_arrayref($statement, \%attr, @bind_values); 与 selectrow_array 类似 返回一个包含所有行信息的数组的引用 26. selectrow_hashref $hash_ref = $dbh->selectrow_hashref($sql); $hash_ref = $dbh->selectrow_hashref($sql, \%attr); $hash_ref = $dbh->selectrow_hashref($sql, \%attr, @bind_values); 与 selectrow_array 类似 返回一个包含所有行信息的数组的哈希引用 27. clone $other_dbh = $dbh->clone(); 克隆一个语句句柄 3.2 数据库句柄属性 本部分介绍数据库句柄的属性 这些属性的改变不会影响其他已经存在的数据库句柄 a. AutoCommit (boolean) 事务是否自动提交 为真时, 表示数据库的改变不可回滚 为假时, 在事务中对数据库的修改必须使用 commit 或 rollback 进行提交或者回滚 缺省值为真, 即自动提交模式 b. ReadOnly (boolean) 表示当前的数据库连接是否为只读模式的 如果为只读模式, 对数据库的任何修改都是无效的 当 AutoCommit 为 true 时, 该设置无效 3.2. 数据库句柄属性 10
c. Name (string, read-only) 返回当前连接的数据库名 d. Username (string, read-only) 返回当前连接使用的用户名 e. Driver (handle, read-only) 返回其驱动程序句柄 3.2. 数据库句柄属性 11
第 4 章 DBI 语句句柄对象 本部分将列出与 DBI 语句句柄相关的方法和属性 更详细的信息可参考 DBI 的规范, 本文不详细说明各方法和属性的相关信息 对于私有方法和属性, 本文将详细说明 4.1 语句句柄方法 a. bind_param $rv = $sth->bind_param($param_num, $bind_value); $rv = $sth->bind_param($param_num, $bind_value, $bind_type); $rv = $sth->bind_param($param_num, $bind_value, \%attr); 绑定值, 可使用完成了预处理的语句中的占位符, 占位符用? 表示 参数说明 : $param_num 表示占位符的序号, 例如 :1,2,3 $bind_value 表示绑定的值 undef 表示绑定到占位符的是一个空值 null \%attr 指定绑定的数据类型, 缺省的数据类型是 varchar 如果需要使用其他的数据类型, 可使用 DBI 或者是 DBD::KB 提供的数据类型 如果使用 SQL 数据类型, 将 use DBI 修改为 use DBI qw(:sql_types) 可将类似于 SQL_INTEGER 这样一些常量导入自己的脚本中, 可直接调用 示例 : 12
use DBI qw(:sql_types); $SQL = "SELECT id FROM ptable WHERE size >? AND title =?"; $sth = $dbh->prepare($sql); ## Both arguments below are bound to placeholders as "varchar" $sth->execute(123, "Merk"); ## Reset the datatype for the first placeholder to an integer $sth->bind_param(1, undef, SQL_INTEGER); ## The "undef" bound above is not used, since we supply params to execute $sth->execute(123, "Merk"); b. bind_param_inout $rv = $sth->bind_param_inout($param_num, \$scalar, 0); 作用与 bind_param 相似, 可进行语句中值的更新 参数说明 : $param_num 表示占位符的序号, 例如 :1,2,3 $bind_value 表示绑定的值 undef 表示绑定到占位符的是一个空值 null 第三个参数可以简单的设置为 0 注意 : 这是指定返回列的变量 示例 : my $foo = 123; $sth = $dbh->prepare("select 1+?::int"); $sth->bind_param_inout(1, \$foo, 0); $foo = 222; $sth->execute(444); $sth->fetch; c. bind_param_array $rv = $sth->bind_param_array($param_num, $array_ref_or_value) $rv = $sth->bind_param_array($param_num, $array_ref_or_value, $bind_type) $rv = $sth->bind_param_array($param_num, $array_ref_or_value, \%attr) 绑定一组参数值 d. execute $rv = $sth->execute(@bind_values); 4.1. 语句句柄方法 13
执行已经预处理的语句 对于 UPDATE, DELETE, INSERT 语句, 返回影响的行数 如果影响的行数不知道, 返回 -1 对于 SELECT 语句, 只返回一个真值, 不返回行数, 在调用 select 后使用取数据的方法来获取数据 参数说明 : @bind_values 设置为 undef 等同于设置的值为 null, 将 bind_values 设置为 $DBDKB_DEFAULT 表示使用缺省值 示例 : $dbh->do(q{create TABLE abc (id SERIAL, country TEXT)}); $SQL = q{insert INTO abc (country) VALUES (?) RETURNING id}; $sth = $dbh->prepare($sql); $sth->execute('france'); $countryid = $sth->fetch()->[0]; $sth->execute('new Zealand'); $countryid = $sth->fetch()->[0]; e. execute_array $tuples = $sth->execute_array() or die $sth->errstr; $tuples = $sth->execute_array(%attr) or die $sth->errstr; $tuples = $sth->execute_array(%attr, @bind_values) or die $sth->errstr; ($tuples, $rows) = $sth->execute_array(%attr) or die $sth->errstr; ($tuples, $rows) = $sth->execute_array(%attr, @bind_values) or die $sth->errstr; 对于通过 bind_param_array 方法传入的每组参数, 执行已经预处理的 SQL 语句 f. execute_for_fetch $tuples = $sth->execute_for_fetch($fetch_tuple_sub); $tuples = $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status); ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub); ($tuples, $rows) = $sth->execute_for_fetch($fetch_tuple_sub, \@tuple_status); 被 execute_array 内部调用, 很少直接调用 g. fetchrow_arrayref $ary_ref = $sth->fetchrow_arrayref; 返回下一行数据并返回一个指向存有各个字段值的数组的引用 如果在数组中有 undef 值的话, 将不返回该字段 如果没有更多的行或者出错, 该方法的返回值为 undef 用户需检查 $sth->err 或者使用 RaiseError 属性来检测返回的 undef 是否是由于发生错误导致的 4.1. 语句句柄方法 14
h. fetchrow_array @ary = $sth->fetchrow_array; 与 fetchrow_arrayref 方法类似 将下一行数据取回, 并将其以含有字段值列表的形式返回 如果这个列表中有 undef 值, 表示没有返回字段 如果没有更多的行或者出错, 该方法的返回值为 undef 用户需检查 $sth->err 或者使用 RaiseError 属性来检测返回的 undef 是否是由于发生错误导致的 i. fetchrow_hashref $hash_ref = $sth->fetchrow_hashref; $hash_ref = $sth->fetchrow_hashref($name); 功能与 fetchrow_array 类似 将下一行数据取回并同时返回指向含有字段名和字段值的散列的引用 散列中有 undef 表示没有返回字段 如果没有更多的行或者出错, 该方法的返回值为 undef 用户需检查 $sth->err 或者使用 RaiseError 属性来检测返回的 undef 是否是由于发生错误导致的 j. fetchall_arrayref $tbl_ary_ref = $sth->fetchall_arrayref(); $tbl_ary_ref = $sth->fetchall_arrayref( $slice ); $tbl_ary_ref = $sth->fetchall_arrayref( $slice, $max_rows ); 使用一个已经预处理的语句句柄, 取回所有数据 该方法将返回数组引用, 每一行在这个数组中有一个引用 如果没有要返回的行或者出错, 该方法将返回迄今已取回的数据, 可能是没有任何数据 用户需检查 $sth->err 或者使用 RaiseError 属性来检测数据是否已经完成还是由于发生错误导致中断 k. fetchall_hashref $hash_ref = $sth->fetchall_hashref( $key_field ); 取回所有数据, 返回哈希引用, 包含所有数据并同时返回指向含有字段名和字段值的哈希的引用 如果没有更多的行或者出错, 该方法的返回值为 undef 用户需检查 $sth->err 或者使用 RaiseError 属性来检测返回的 undef 是否是由于发生错误导致的 l. finish $rv = $sth->finish; 指示该句柄在再次被执行或销毁之前, 从该句柄无数据可取 可以使服务器释放资源 m. rows $rv = $sth->rows; 4.1. 语句句柄方法 15
返回最后一个影响行的语句所影响的行数 如果该行数不知道或者无法得到, 返回 -1 n. bind_col $rv = $sth->bind_col($column_number, \$var_to_bind); $rv = $sth->bind_col($column_number, \$var_to_bind, \%attr); $rv = $sth->bind_col($column_number, \$var_to_bind, $bind_type ); 将一个 SELECT 语句的输出字段绑定到一个 Perl 变量 o. bind_columns $rv = $sth->bind_columns(@list_of_refs_to_vars_to_bind); 对 SELECT 语句的每一列调用 bind_col p. dump_results $rows = $sth->dump_results($maxlen, $lsep, $fsep, $fh); 从语句句柄中取回所有的行, 并对每一行调用 DBI::neat_list 将结果打印到 $fh 4.2 语句句柄属性 本部分介绍语句句柄的属性 这些属性多数是只读的 这些属性的改变不会影响其他已经存在的语句句柄 a. NUM_OF_FIELDS (integer, read-only) 已经预处理的语句的列数 对于非 SELECT 语句将设置 NUM_OF_FIELDS = 0 b. NUM_OF_PARAMS (integer, read-only) 已经预处理的语句的参数个数 c. NAME (arrayref, read-only) 返回列名数组的引用 名字中可以包含空格, 但不允许进行截断或有尾部空格 区分大小写, 与数据库服务器返回一致 d. NAME_lc (arrayref, read-only) 与 NAME 相同, 返回小写列名 e. NAME_uc (arrayref, read-only) 与 NAME 相同, 返回大写列名 f. NAME_hash (hashref, read-only) 与 NAME 相同, 返回哈希引用 4.2. 语句句柄属性 16
g. NAME_lc_hash (hashref, read-only) 与 NAME_lc 相同, 返回哈希引用 h. NAME_uc_hash (hashref, read-only) 与 NAME_uc 相同, 返回哈希引用 i. TYPE (arrayref, read-only) 为每一列返回一个整数数组的引用, 该数值与列的数据类型一致 j. PRECISION (arrayref, read-only) 为每一列返回一个指向一个整数数组的引用 对于非数值型列, 该值为该列的最大长度或者定义的长度 对于数值型列, 是该数据类型的最大数字个数 k. SCALE (arrayref, read-only) 为每一列返回一个指向一个整数数组的引用 undef 表示这一列不适合用 SCALE l. NULLABLE (arrayref, read-only) 返回一个数组引用, 表示每一列是否可为空 0 表示不能为空,1 表示可以为空,2 表示未知 m. Database (dbh, read-only) 返回该语句句柄的数据库句柄 n. ParamValues (hash ref, read-only) 返回一个指向当前已绑定的参数值的哈希引用 o. ParamTypes (hash ref, read-only) 返回一个指向当前已绑定的参数的数据类型的哈希引用 p. Statement (string, read-only) 返回传给 prepare 方法的 SQL 语句字符串 4.2. 语句句柄属性 17
第 5 章 示例 下面给出示例, 描述了如何通过 KingbaseES PERL DBI 访问 KingbaseES 数据库 5.1 示例 1 下面的例子描述了如何建立与数据库的连接以及获取结果集 #!/usr/bin/perl use DBI; use DBD::KB; printf("before connect\n"); $dbh = DBI->connect("DBI:KB:dbname=TEST;host=192.168.4.8", 'SYSTEM', 'MANAGER'); printf("after connect\n"); $sth = $dbh->prepare("select 123 as a, 456 as b"); $sth->execute(); while(@row = $sth->fetchrow_array()) { print "row = @row\n"; } 18
第 A 章 版权声明 人大金仓版权所有, 并保留对本手册及本声明的一切权利 未得到人大金仓的书面许可, 任何人不得以任何方式或形式对本手册内的任何部分进行复制 摘录 备份 修改 传播 翻译成其他语言 将其全部或部分用于商业用途 免责声明 本手册内容依据现有信息制作, 由于产品版本升级或其他原因, 其内容有可能变更 人大金仓保留在没有任何通知或者提示的情况下对手册内容进行修改的权利 本手册仅作为使用指导, 人大金仓在编写本手册时已尽力保证其内容准确可靠, 但并不确保手册内容完全没有错误或遗漏, 本手册中的所有信息也不构成任何明示或暗示的担保 技术支持 人大金仓官方网站 :http://www.kingbase.com.cn/ 您可以在官网中获得人大金仓所有产品的资讯信息, 销售联系方式 金仓数据库子网站 :http://kes.kingbase.com.cn/ 您可以在产品子网站中获得最新的产品技术资料 产品故障原因及问题分析 产品的应用解决方案 软件升级资料等等 全国服务热线 :400-601-1188 人大金仓技术支持与反馈信箱 :support@kingbase.com.cn 19