虚谷文档 v1.0.1

适用虚谷数据库版本

v12.9



适用虚谷数据库版本

v12.9


DBMS_UTILITY系统包 ​

📄字数 2.2K
👁️阅读量 加载中...

一、概述 ​

DBMS_UTILITY系统包是一个通用工具包，提供时间管理、错误调试、元数据维护等常用接口，广泛用于开发调试、性能监控和元数据处理，是开发者和 DBA 常用的工具之一。

在该系统包中提供了以下接口：

包体函数名简要描述
GET_TIME获取当前时间，返回值为BIGINT数字型
FORMAT_ERROR_STACK获取当前线程上的错误信息
FORMAT_ERROR_BACKTRACE获取当前线程上的格式化后的错误信息
OPEN_TABLE开表操作，更新内存中表元信息

典型应用场景，如：

  • 利用GET_TIME获取过程或SQL语句的执行耗时时间，进行性能分析
  • 利用FORMAT_ERROR_STACK捕获异常信息，进行错误调试
  • 利用FORMAT_ERROR_BACKTRACE定位出错位置
  • 表结构发生变更但未即时生效时，利用OPEN_TABLE强制刷新元数据

二、GET_TIME ​

2.1 功能描述 ​

该接口用于获取当前时间，返回值为BIGINT数字类型（常用于代码级别的时间测量，而非显示当前系统时间）

2.2 方法声明 ​

sql
FUNCTION GET_TIME() RETURN BIGINT;

2.3 参数说明 ​

无

2.4 示例 ​

sql
SQL> DECLARE
     TI BIGINT;
     BEGIN
     TI:= DBMS_UTILITY.GET_TIME();
       DBMS_OUTPUT.PUT_LINE(TI);
     END;
     /
-- 输出结果
175069563582

2.5 应用场景 ​

  • 场景一：定位性能瓶颈。在块语句、存储过程等中间调用，计算执行时间差，辅助分析慢SQL、慢过程
  • 场景二：定时任务执行耗时评估。监控定时作业的运行时间是否在预期范围内

三、FORMAT_ERROR_STACK ​

3.1 功能描述 ​

该接口用于获取当前线程调用栈上最后一个错误信息字符串，用于异常处理、错误日志记录和调试分析

3.2 方法声明 ​

sql
FUNCTION FORMAT_ERROR_STACK() RETURN VARCHAR(5000);

3.3 参数说明 ​

无

3.4 示例 ​

sql
SQL> CREATE FUNCTION ERR_STACK(A BIGINT) RETURN BIGINT
     IS
     DECLARE
     RES BIGINT;
     BEGIN
     RES:= A/0; -- 故意制造除零错误
       RETURN RES;
     END;
     /

SQL> CREATE FUNCTION OUTPUT_ERR() RETURN BIGINT
     IS
     BEGIN
     RETURN ERR_STACK(20); -- 调用会触发异常
     EXCEPTION
     WHEN OTHERS THEN
       DBMS_OUTPUT.PUT_LINE(DBMS_UTILITY.FORMAT_ERROR_STACK()); -- 打印错误信息
       RETURN 1;
     END;
     /

SQL> SELECT OUTPUT_ERR();
除数为0

+-------+
| EXPR1 |
+-------+
| 1     |
+-------+

3.5 应用场景 ​

  • 场景一：用于显示用户操作失败时的具体原因

四、FORMAT_ERROR_BACKTRACE ​

4.1 功能描述 ​

该接口用于获取当前线程上的格式化后的错误信息

4.2 方法声明 ​

sql
FUNCTION FORMAT_ERROR_BACKTRACE() RETURN VARCHAR(5000);

4.3 参数说明 ​

无

4.4 示例 ​

sql
SQL> CREATE FUNCTION ERR_STACK1(A BIGINT) RETURN BIGINT
     IS
     DECLARE
     RES BIGINT;
     BEGIN
     RES:= A/0; -- 故意制造除零错误
       RETURN RES;
     END;
     /

SQL> CREATE FUNCTION OUTPUT_ERR1() RETURN BIGINT
     IS
     BEGIN
     RETURN ERR_STACK1(20); -- 调用会触发异常
     EXCEPTION
     WHEN OTHERS THEN
       DBMS_OUTPUT.PUT_LINE(DBMS_UTILITY.FORMAT_ERROR_BACKTRACE()); -- 打印错误信息
       RETURN 1;
     END;
     /

SQL> SELECT OUTPUT_ERR1();
ERR-19005: Line 6 Column 6

+-------+
| EXPR1 |
+-------+
| 1     |
+-------+

4.5 应用场景 ​

  • 场景一：用于脚本中异常定位点，辅助判断是否是权限、网络或资源问题

五、OPEN_TABLE ​

5.1 功能描述 ​

该接口用于对表进行开表操作，可以将表元信息从磁盘读取内存，更新内存中表元信息

5.2 方法声明 ​

sql
PROCEDURE OPEN_TABLE(
    name    IN VARCHAR, 
    node_id IN INTEGER
    ) AUTHID USER;

5.3 参数说明 ​

参数名类型取值范围是否可选描述
nameVARCHAR*或者schema_name.*或者tab_name否表名，'*'表示当前库下所有表，'schema_name.*'表示指定模式下所有表，'tab_name'表示当前库当前模式下的指定表
node_idINTEGER无否节点id

提示

node_id取值为0时表示当前节点，取值为-1时表示所有节点。

5.4 示例 ​

  • 在当前节点（取值为0）打开当前库下所有表

    sql
    SQL> DBMS_UTILITY.OPEN_TABLE('*', 0);

  • 在当前节点打开当前库下模式sysdba的所有表

    sql
    SQL> DBMS_UTILITY.OPEN_TABLE('sysdba.*', 0);

  • 在所有节点（取值为-1）打开当前库当前模式的tab_open表

    sql
    SQL> CREATE TABLE tab_open(id INT);
SQL> DBMS_UTILITY.OPEN_TABLE('tab_open', -1);

5.5 应用场景 ​

  • 场景一：预加载元数据，提高访问性能。批量开表操作可以减少首次访问时的等待时间
  • 场景二：用于排查权限配置或锁冲突问题。当执行 OPEN_TABLE 操作失败时，可借此判断是否存在权限不足或表被锁定等情况，从而辅助定位并解决问题