AI 助理
备案控制台
文档
输入文档关键字查找
首页 云原生数据库 PolarDB 云原生数据库PolarDB PostgreSQL版（兼容Oracle） 开发指南（Oracle语法兼容2.0） 系统包 DBMS_UTILITY

DBMS_UTILITY

更新时间：
产品详情
我的收藏

DBMS_UTILITY内置包提供了多种工具类子程序。

BMS_UTILITY子程序总览

子程序

说明

ANALYZE_DATABASE Procedure

分析数据库中的表。

ANALYZE_SCHEMA Procedure

分析schema中的表。

ANALYZE_PART_OBJECT Procedure

分析单张表。

CANONICALIZE Procedure

规范化给定的字符串。

COMMA_TO_TABLE Procedure

将逗号分隔的名称标识符列表转换为名称表。

DB_VERSION Procedure

获取数据库版本。

EXEC_DDL_STATEMENT Procedure

执行DDL语句。

FORMAT_CALL_STACK Function

格式化当前调用栈。

FORMAT_ERROR_BACKTRACE Function

格式化从当前的错误点到捕获错误的异常处理程序的堆栈信息。

FORMAT_ERROR_STACK Function

格式化当前错误栈。

GET_CPU_TIME Function

返回当前的CPU时间（以百分之一秒为单位）。

GET_DEPENDENCY Procedure

显示传入对象的依赖关系。

GET_HASH_VALUE Function

计算给定字符串的哈希值。

GET_PARAMETER_VALUE Function

获取数据库初始化参数设置。

GET_TIME Function

返回当前的时钟时间（以百分之一秒为单位）。

NAME_TOKENIZE Procedure

将给定名称解析为其组成部分。

TABLE_TO_COMMA Procedure

将名称标识符的表转为逗号分隔的列表。

DBMS_UTILITY数据类型

LNAME_ARRAY

LNAME_ARRAY用于存储长名称（包括完全限定名称）的列表。

TYPE LNAME_ARRAY IS TABLE OF VARCHAR2(4000);

UNCL_ARRAY

UNCL_ARRAY用于存储名称标识符的列表。

TYPE UNCL_ARRAY IS TABLE OF VARCHAR2(227);

ANALYZE_DATABASE

该存储过程用于分析数据库中的表。

语法

DBMS_UTILITY.ANALYZE_DATABASE (
   method             IN  VARCHAR2,
   estimate_rows      IN  INTEGER DEFAULT NULL,
   estimate_percent   IN  INTEGER DEFAULT NULL,
   method_opt         IN  VARCHAR2 DEFAULT NULL);

参数说明

参数

说明

method

指定ANALYZE的方法。取值如下：

  • DELETE

  • COMPUTE

  • ESTIMATE

COMPUTE 和 ESTIMATE之间没有差异，都是执行ANALYZE语句。其他参数均为兼容性提供参数，执行时会被忽略。

estimate_rows

（可选参数）估计统计信息所依据的行数。

estimate_percent

（可选参数）估计统计信息所依据的行百分比。

method_opt

（可选参数）分析的对象类型。

示例

CALL DBMS_UTILITY.ANALYZE_DATABASE('COMPUTE');

ANALYZE_SCHEMA

该存储过程用于分析schema中的表。

语法

DBMS_UTILITY.ANALYZE_SCHEMA (
   schema             IN  VARCHAR2,
   method             IN  VARCHAR2,
   estimate_rows      IN  INTEGER DEFAULT NULL,
   estimate_percent   IN  INTEGER DEFAULT NULL,
   method_opt         IN  VARCHAR2 DEFAULT NULL);

参数说明

参数

说明

schema

schema的名称。

method

指定ANALYZE的方法。取值如下：

  • DELETE

  • COMPUTE

  • ESTIMATE

COMPUTE和ESTIMATE之间没有差异，都是执行ANALYZE语句。除去schema和method以外的参数均为兼容性提供参数，执行时会被忽略。

estimate_rows

（可选参数）估计统计信息所依据的行数。

estimate_percent

（可选参数）估计统计信息所依据的行百分比。

method_opt

（可选参数）分析的对象类型。

示例

CALL DBMS_UTILITY.ANALYZE_SCHEMA('public', 'compute');

ANALYZE_PART_OBJECT

该存储过程用于分析单张表。

语法

DBMS_UTILITY.ANALYZE_PART_OBJECT (
   schema        IN VARCHAR2 DEFAULT NULL,
   object_name   IN VARCHAR2 DEFAULT NULL,
   object_type   IN CHAR     DEFAULT 'T',
   command_type  IN CHAR     DEFAULT 'E',
   command_opt   IN VARCHAR2 DEFAULT NULL,
   sample_clause IN VARCHAR2 DEFAULT 'sample 5 percent ');

参数说明

参数

说明

schema

待分析对象的schema名称。

object_name

待分析对象。

object_type

（可选参数）待分析对象类型。

command_type

（可选参数）需要执行的分析功能类型。

command_opt

（可选参数）command_type使用的可选值。

sample_clause

（可选参数）command_type为'E'时的示例子句。

说明

除了schema和object_name，其他参数均为兼容性提供参数，执行时会被忽略。

示例

CALL DBMS_UTILITY.analyze_part_object('public', 'table2');

CANONICALIZE

该存储过程用于规范化一个给定的字符串。

语法

DBMS_UTILITY.CANONICALIZE(
   name           IN    VARCHAR2,
   canon          OUT   VARCHAR2,
   canon_len      IN    INTEGER);

参数说明

参数

说明

name

待规范化的字符串。

canon

完成规范化的字符串。

canon_len

name中从第一个字符开始待规范化的字节数量。

示例

该示例展示了如何规范化一个给定的字符串。

DECLARE
  name varchar2 default  'aBc."dEf"."ghi"';
  length integer default 50;
  canon  varchar2;
BEGIN
    DBMS_UTILITY.CANONICALIZE(name,canon,length);
    DBMS_OUTPUT.PUT_LINE(canon);
END;
-- "ABC"."dEf"."ghi"

COMMA_TO_TABLE

该存储过程用于将逗号分隔的名称列表转换为名称表。

语法

DBMS_UTILITY.COMMA_TO_TABLE ( 
   list   IN  VARCHAR2,
   tablen OUT INTEGER,
   tab    OUT UNCL_ARRAY);

参数说明

参数

说明

list

以逗号分隔的名称标识符列表。

tablen

tab中的条目数量。

tab

包含list中的各个名称的表。

示例

该示例展示了如何将逗号分隔的名称列表转换为名称表。

DECLARE
    lname    DBMS_UTILITY.LNAME_ARRAY;
    length   integer;
    list     varchar2;
BEGIN
    list := 'a.b.c.d , b , c , select1';
    DBMS_UTILITY.COMMA_TO_TABLE(list,length,lname);
    FOR i IN 1..length LOOP
        DBMS_OUTPUT.PUT_LINE('-> ' || lname(i) || '<- ' || length(lname(i)));
    END LOOP;
    DBMS_OUTPUT.PUT_LINE('--  finished  --');
END;

-> a.b.c.d <- 8
-> b <- 3
-> c <- 3
-> select1 <- 8
--  finished  --

DB_VERSION

该存储过程用于获取数据库的版本信息。

语法

DBMS_UTILITY.DB_VERSION (
   version       OUT VARCHAR2,
   compatibility OUT VARCHAR2);

参数说明

参数

说明

version

数据库版本。

compatibility

数据库兼容性设置（忽略）。

示例

该示例展示了如何获取数据库的版本信息。

DECLARE
    version varchar2(100);
    compatibility varchar2(100);
BEGIN
    DBMS_UTILITY.DB_VERSION(version, compatibility); 
    DBMS_OUTPUT.PUT_LINE(version);
    DBMS_OUTPUT.PUT_LINE(compatibility);
END;
-- PostgreSQL 14.8 (PolarDB 14.8.10.0 build 0d3bf26c debug)
-- PostgreSQL 14.8 (PolarDB 14.8.10.0 build 0d3bf26c debug)

EXEC_DDL_STATEMENT

该存储过程用于执行DDL语句。

语法

DBMS_UTILITY.EXEC_DDL_STATEMENT (
   parse_string IN VARCHAR2);

参数说明

参数

说明

parse_string

待执行的DDL语句。

示例

该示例展示了如何通过该存储过程执行DDL语句。

CALL DBMS_UTILITY.EXEC_DDL_STATEMENT('CREATE TABLE test(a int, b varchar2(20))');

SELECT * FROM test;
 a | b
---+---
(0 rows)

FORMAT_CALL_STACK

该函数用于格式化当前的调用栈。

语法

DBMS_UTILITY.FORMAT_CALL_STACK();
  RETURN VARCHAR2;

返回值

返回值

说明

VARCHAR2

格式化后的调用栈信息。

示例

该示例展示了如何输出当前的调用栈的格式化信息。

CREATE FUNCTION func() RETURNS varchar2
IS
BEGIN
     return dbms_utility.format_call_stack();
END;

select * from func();
                       func
--------------------------------------------------
 ----- PL/SQL Call Stack -----                   +
   object    line     object                     +
   handle    number    name                      +
        0        2   function format_call_stack()+
    17089        2   function func()
(1 row)

FORMAT_ERROR_BACKTRACE

该函数用于格式化从当前的错误点到捕获错误的异常处理程序的堆栈信息。

语法

DBMS_UTILITY.FORMAT_ERROR_BACKTRACE()
  RETURN VARCHAR2;

返回值

返回值

说明

VARCHAR2

回溯的堆栈信息。

示例

该示例创建了一个函数的调用链，被调用函数抛出异常，调用方捕获异常，并通过FORMAT_ERROR_BACKTRACE打印错误堆栈信息。

CREATE FUNCTION inner(a integer) RETURNS integer
IS
DECLARE
  res integer;
BEGIN
  res = a/0;
  RETURN res;
EXCEPTION
  WHEN others THEN
    RAISE EXCEPTION 'expected exception';
END;

CREATE FUNCTION outer() RETURNS integer
IS
BEGIN
  return inner(100);
EXCEPTION
  WHEN others THEN
    DBMS_OUTPUT.PUT_LINE(DBMS_UTILITY.FORMAT_ERROR_BACKTRACE());
    return -1;
END;

SELECT outer() FROM dual;

----- Error Stack -----
ERR-33816706: division by zero
PL/SQL function "inner"(integer) line 4 at assignment
PL/SQL function "outer"() line 2 at RETURN
ERR-16777248: expected exception
PL/SQL function "inner"(integer) line 8 at RAISE
PL/SQL function "outer"() line 2 at RETURN

FORMAT_ERROR_STACK

该函数用于格式化当前的错误栈。

语法

DBMS_UTILITY.FORMAT_ERROR_STACK 
  RETURN VARCHAR2;

返回值

返回值

说明

VARCHAR2

格式化后的错误调用栈信息。

示例

该示例创建了一个函数的调用链，被调用函数抛出异常，调用方捕获异常，并通过FORMAT_ERROR_STACK打印错误栈信息。

CREATE FUNCTION inner(a integer) RETURNS integer
IS
DECLARE
  res integer;
BEGIN
  res = a/0;
  RETURN res;
EXCEPTION
  WHEN others THEN
    RAISE EXCEPTION 'expected exception';
END;

CREATE FUNCTION outer() RETURNS integer
IS
BEGIN
  return inner(100);
EXCEPTION
  WHEN others THEN
    DBMS_OUTPUT.PUT_LINE(DBMS_UTILITY.FORMAT_ERROR_STACK());
    return -1;
END;

SELECT outer() FROM dual;

----- Error Stack -----
ERR-33816706: division by zero
PL/SQL function "inner"(integer) line 4 at assignment
PL/SQL function "outer"() line 2 at RETURN
ERR-16777248: expected exception
PL/SQL function "inner"(integer) line 8 at RAISE
PL/SQL function "outer"() line 2 at RETURN

GET_CPU_TIME

该函数用于返回当前的CPU时间。

语法

DBMS_UTILITY.GET_CPU_TIME
   RETURN INTEGER;

返回值

返回值

说明

INTEGER

任意时间点的CPU时间（百分之一秒为单位）。

示例

该示例展示了在程序sleep前后的CPU时间（两个CPU时间的差值远小于程序的sleep时间）。

BEGIN
    DBMS_OUTPUT.PUT_LINE('start cpu time:' || DBMS_UTILITY.GET_CPU_TIME());
-- start cpu time:11
    DBMS_SESSION.SLEEP(5);
    DBMS_OUTPUT.PUT_LINE('end cpu time:' || DBMS_UTILITY.GET_CPU_TIME());
-- end cpu time:11
END;

GET_DEPENDENCY

该存储过程用于显示传入对象的依赖关系。

语法

DBMS_UTILITY.GET_DEPENDENCY
   type      IN     VARCHAR2,
   schema    IN     VARCHAR2,
   name      IN     VARCHAR2);

参数说明

参数

说明

type

name的对象类型。

schema

name所在的schema的名称。

name

待获取依赖项的对象的名称。

示例

该示例创建了一张表，并在此基础上创建了一张视图，通过该存储过程查看该视图的依赖关系。

CREATE TABLE t(a int, b int);
CREATE VIEW v AS SELECT a, b FROM t;
CALL DBMS_UTILITY.GET_DEPENDENCY('view','public','v');
-- TABLE T

GET_HASH_VALUE

该函数用于计算给定字符串的哈希值。

语法

DBMS_UTILITY.GET_HASH_VALUE (
   name      VARCHAR2, 
   base      INTEGER, 
   hash_size INTEGER)
  RETURN INTEGER;

参数说明

参数

说明

name

待计算哈希值的字符串。

base

返回的哈希值的起始基值。

hash_size

返回的哈希值的范围。

返回值

返回值

说明

INTEGER

生成的哈希值。

示例

该示例展示了如何计算给定字符串的哈希值（该示例计算给定字符串在1到99内的哈希值）。

SELECT DBMS_UTILITY.GET_HASH_VALUE('PolarDB', 1, 100) FROM dual;

 get_hash_value 
----------------
             67
(1 row)

GET_PARAMETER_VALUE

该函数用于获取数据库初始化参数设置。

语法

DBMS_UTILITY.GET_PARAMETER_VALUE (
   parnam     IN        VARCHAR2,
   intval     OUT       INTEGER,
   strval     OUT       VARCHAR2)
  RETURN INTEGER;

参数说明

参数

说明

parnam

需要返回其值的参数的名称。pg_settings系统视图中列出了这些参数。

intval

整数参数的值或strval的长度。

strval

字符串参数的值。

返回值

返回值

说明

INTEGER

如果参数值为INTEGER，返回0。否则返回1。

示例

该示例展示了通过该函数获取字符串和整数类型的参数。

DECLARE
    intval     INTEGER;
    strval     VARCHAR2(80);
    ret        INTEGER;
BEGIN
    ret := DBMS_UTILITY.GET_PARAMETER_VALUE('client_encoding', intval, strval);
    DBMS_OUTPUT.PUT_LINE('ret is: ' || ret || '; intval is: ' || intval || '; strval is: ' || strval);
    ret := DBMS_UTILITY.GET_PARAMETER_VALUE('block_size', intval, strval);
    DBMS_OUTPUT.PUT_LINE('ret is: ' || ret || '; intval is: ' || intval || '; strval is: ' || strval);
END;
ret is: 1; intval is: 4; strval is: UTF8
ret is: 0; intval is: 8192; strval is:

GET_TIME

该函数用于返回当前的时间。

语法

DBMS_UTILITY.GET_TIME
  RETURN INTEGER;

返回值

返回值

说明

INTEGER

任意时间点的时钟时间（百分之一秒为单位）。

示例

该示例展示了通过GET_TIME获取程序执行前后的时间差。

DECLARE
  start_time integer;
  end_time integer;
BEGIN
    start_time := DBMS_UTILITY.GET_TIME;
    DBMS_LOCK.SLEEP(5);
    end_time := DBMS_UTILITY.GET_TIME;
    DBMS_OUTPUT.PUT_LINE('total time is:' || end_time - start_time);
END;

NAME_TOKENIZE

该存储过程用于将给定名称解析为其组成部分。

语法

DBMS_UTILITY.NAME_TOKENIZE ( 
   name    IN  VARCHAR2,
   a       OUT VARCHAR2,
   b       OUT VARCHAR2,
   c       OUT VARCHAR2,
   dblink  OUT VARCHAR2, 
   nextpos OUT INTEGER);

参数说明

参数

说明

name

输入的名称。由SQL标识符组成，格式为a [ . b [ . c ] ] [ @ dblink ]。

a

name中的第一个标识符。

b

name中的第二个标识符。

c

name中的第三个标识符。

dblink

name中的dblink部分。

nextpos

完成输入name解析后的下一个字符位置

示例

该示例展示了如何通过该存储过程进行名称的解析。

DECLARE
  a             varchar2;
  b             varchar2;
  c             varchar2;
  dblink        varchar2;
  nextpos       integer;
  name          varchar2;
BEGIN
  name := 'sch.tbl@dblink';
  DBMS_UTILITY.NAME_TOKENIZE(name, a, b, c, dblink, nextpos);
  DBMS_OUTPUT.PUT_LINE('name   : ' || name);
  DBMS_OUTPUT.PUT_LINE('a      : ' || a);
  DBMS_OUTPUT.PUT_LINE('b      : ' || b);
  DBMS_OUTPUT.PUT_LINE('c      : ' || c);
  DBMS_OUTPUT.PUT_LINE('dblink : ' || dblink);
  DBMS_OUTPUT.PUT_LINE('nextpos: ' || nextpos);
END;
name   : sch.tbl@dblink
a      : SCH
b      : TBL
c      :
dblink : DBLINK
nextpos: 14

TABLE_TO_COMMA

该存储过程用于将名称标识符的表转为逗号分隔的列表。

语法

DBMS_UTILITY.TABLE_TO_COMMA ( 
   tab    IN  UNCL_ARRAY, 
   tablen OUT INTEGER,
   list   OUT VARCHAR2);

参数说明

参数

说明

tab

包含名称标识符的表。

tablen

tab中的条目数量。

list

以逗号分隔的名称列表。

示例

该示例展示了如何将包含名称的表转为逗号分隔的形式。

DECLARE
    result   varchar2;
    length   integer;
    list     dbms_utility.lname_array;
BEGIN
    list := dbms_utility.lname_array('name1', 'name2', 'name3');
    DBMS_UTILITY.TABLE_TO_COMMA(list, length, result);
    DBMS_OUTPUT.PUT_LINE('result is: ' || result || '; length is: ' || length );
END;
-- result is: name1,name2,name3; length is: 3
上一篇：DBMS_STATS下一篇：UTL_ENCODE
文档推荐