Redrock Postgres 搜索 英文
版本: 9.3 / 9.4 / 9.5 / 9.6 / 10 / 11 / 12 / 13 / 14 / 15 / 16 / 17

43.3. 内置函数 #

43.3.1. 从 PL/Perl 访问数据库
43.3.2. PL/Perl 中的实用程序函数

43.3.1. 从 PL/Perl 访问数据库 #

可以通过以下函数从 Perl 函数本身访问数据库

spi_exec_query(查询 [, limit])

spi_exec_query 执行一条 SQL 命令,并将整个行集作为对哈希引用数组的引用的形式返回。如果指定了 limit 并且大于 0,则 spi_exec_query 最多检索 limit 行,就像该查询包含一个 LIMIT 子句一样。省略 limit 或将其指定为 0 时不限制行数。

只当您知道结果集相对较小时才应该使用此命令。这里有一个查询(SELECT 命令)的示例,其中包含最大行数的可选行

$rv = spi_exec_query('SELECT * FROM my_table', 5);

这将从表 my_table 中返回最多 5 行。如果 my_table 有一个列 my_column,您可以使用类似这样的方式从结果中的行 $i 中获取该值

$foo = $rv->{rows}[$i]->{my_column};

SELECT 查询中返回的行总数可按此方式访问

$nrows = $rv->{processed}

这里是一个使用不同命令类型的示例

$query = "INSERT INTO my_table VALUES (1, 'test')";
$rv = spi_exec_query($query);

然后,您可以按此方式访问命令状态(例如 SPI_OK_INSERT

$res = $rv->{status};

要获取受影响的行数,请执行以下操作

$nrows = $rv->{processed};

这里是一个完整示例

CREATE TABLE test (
    i int,
    v varchar
);

INSERT INTO test (i, v) VALUES (1, 'first line');
INSERT INTO test (i, v) VALUES (2, 'second line');
INSERT INTO test (i, v) VALUES (3, 'third line');
INSERT INTO test (i, v) VALUES (4, 'immortal');

CREATE OR REPLACE FUNCTION test_munge() RETURNS SETOF test AS $$
    my $rv = spi_exec_query('select i, v from test;');
    my $status = $rv->{status};
    my $nrows = $rv->{processed};
    foreach my $rn (0 .. $nrows - 1) {
        my $row = $rv->{rows}[$rn];
        $row->{i} += 200 if defined($row->{i});
        $row->{v} =~ tr/A-Za-z/a-zA-Z/ if (defined($row->{v}));
        return_next($row);
    }
    return undef;
$$ LANGUAGE plperl;

SELECT * FROM test_munge();
spi_query(command)
spi_fetchrow(cursor)
spi_cursor_close(cursor)

spi_queryspi_fetchrow 作为一对用于可能很大的行集,或者是在行到达时返回行的案例。 spi_fetchrow spi_query 配合使用。以下示例说明了如何将它们组合使用

CREATE TYPE foo_type AS (the_num INTEGER, the_text TEXT);

CREATE OR REPLACE FUNCTION lotsa_md5 (INTEGER) RETURNS SETOF foo_type AS $$
    use Digest::MD5 qw(md5_hex);
    my $file = '/usr/share/dict/words';
    my $t = localtime;
    elog(NOTICE, "opening file $file at $t" );
    open my $fh, '<', $file # ooh, it's a file access!
        or elog(ERROR, "cannot open $file for reading: $!");
    my @words = <$fh>;
    close $fh;
    $t = localtime;
    elog(NOTICE, "closed file $file at $t");
    chomp(@words);
    my $row;
    my $sth = spi_query("SELECT * FROM generate_series(1,$_[0]) AS b(a)");
    while (defined ($row = spi_fetchrow($sth))) {
        return_next({
            the_num => $row->{a},
            the_text => md5_hex($words[rand @words])
        });
    }
    return;
$$ LANGUAGE plperlu;

SELECT * from lotsa_md5(500);

一般情况下,应该重复 spi_fetchrow 直到它返回 undef,指示没有更多行要读取。当 spi_fetchrow 返回 undef 时,spi_query 返回的光标将自动释放。如果不希望读取所有行,可以改用 spi_cursor_close 来释放光标。如果不这样做,会导致内存泄漏。

spi_prepare(command, argument types)
spi_query_prepared(plan, arguments)
spi_exec_prepared(plan [, attributes], arguments)
spi_freeplan(plan)

spi_preparespi_query_preparedspi_exec_preparedspi_freeplan 提供相同的功能,但针对已准备的查询。spi_prepare 接受带有编号参数占位符的查询字符串 ($1、$2 等) 以及参数类型的字符串列表

$plan = spi_prepare('SELECT * FROM test WHERE id > $1 AND name = $2',
                                                     'INTEGER', 'TEXT');

可以通过调用 spi_prepare 为一个查询计划做好准备,随后可以在 spi_exec_prepared 中将该计划用于字符串查询,其结果与 spi_exec_query 返回的结果相同,也可以在 spi_query_prepared 中使用,它返回一个游标,就像 spi_query 所做的那样,该游标稍后可以传递给 spi_fetchrowspi_exec_prepared 的可选第二个参数是哈希参考属性;目前仅支持以下属性:limit,用于设置查询返回的最大行数。如果省略 limit 或将其指定为零,则意味着没有行数限制。

已准备查询的优势在于可以使用一个已准备的计划完成多个查询执行。在不再需要该计划之后,可以使用 spi_freeplan 释放该计划

CREATE OR REPLACE FUNCTION init() RETURNS VOID AS $$
        $_SHARED{my_plan} = spi_prepare('SELECT (now() + $1)::date AS now',
                                        'INTERVAL');
$$ LANGUAGE plperl;

CREATE OR REPLACE FUNCTION add_time( INTERVAL ) RETURNS TEXT AS $$
        return spi_exec_prepared(
                $_SHARED{my_plan},
                $_[0]
        )->{rows}->[0]->{now};
$$ LANGUAGE plperl;

CREATE OR REPLACE FUNCTION done() RETURNS VOID AS $$
        spi_freeplan( $_SHARED{my_plan});
        undef $_SHARED{my_plan};
$$ LANGUAGE plperl;

SELECT init();
SELECT add_time('1 day'), add_time('2 days'), add_time('3 days');
SELECT done();

  add_time  |  add_time  |  add_time
------------+------------+------------
 2005-12-10 | 2005-12-11 | 2005-12-12

注意,其参数下标在 spi_prepare 中通过 $1、$2、$3 等来定义,因此请避免在双引号中声明查询字符串,这很容易导致难以捕捉的错误。

另一个示例说明了在 spi_exec_prepared 中使用可选参数

CREATE TABLE hosts AS SELECT id, ('192.168.1.'||id)::inet AS address
                      FROM generate_series(1,3) AS id;

CREATE OR REPLACE FUNCTION init_hosts_query() RETURNS VOID AS $$
        $_SHARED{plan} = spi_prepare('SELECT * FROM hosts
                                      WHERE address << $1', 'inet');
$$ LANGUAGE plperl;

CREATE OR REPLACE FUNCTION query_hosts(inet) RETURNS SETOF hosts AS $$
        return spi_exec_prepared(
                $_SHARED{plan},
                {limit => 2},
                $_[0]
        )->{rows};
$$ LANGUAGE plperl;

CREATE OR REPLACE FUNCTION release_hosts_query() RETURNS VOID AS $$
        spi_freeplan($_SHARED{plan});
        undef $_SHARED{plan};
$$ LANGUAGE plperl;

SELECT init_hosts_query();
SELECT query_hosts('192.168.1.0/30');
SELECT release_hosts_query();

    query_hosts
-----------------
 (1,192.168.1.1)
 (2,192.168.1.2)
(2 rows)
spi_commit()
spi_rollback()

提交或回滚当前事务。只能在从顶级调用的存储过程中或匿名代码块(DO 命令)中调用它。(请注意,不可能通过 spi_exec_query 或类似功能运行 SQL 命令 COMMITROLLBACK。必须使用此类函数来完成该操作。)在事务结束后,将自动开始一个新事务,因此没有用于执行此操作的单独函数。

下面是一个示例

CREATE PROCEDURE transaction_test1()
LANGUAGE plperl
AS $$
foreach my $i (0..9) {
    spi_exec_query("INSERT INTO test1 (a) VALUES ($i)");
    if ($i % 2 == 0) {
        spi_commit();
    } else {
        spi_rollback();
    }
}
$$;

CALL transaction_test1();

43.3.2. PL/Perl 中的实用程序函数 #

elog(level, msg)

输出日志或错误消息。可能的级别有 DEBUGLOGINFONOTICEWARNINGERRORERROR 会引发一个错误条件;如果周围的 Perl 代码没有捕获此错误,该错误会传播到调用查询,导致当前事务或子事务被中止。这实际上与 Perl die 命令相同。其他级别只生成不同优先级的消息。是否将特定优先级消息报告给客户端、写入服务器日志,还是同时报告给客户端和服务器日志,由 log_min_messagesclient_min_messages 配置变量控制。有关详细信息,请参见 第 19 章

quote_literal(string)

返回给定字符串,将其适当地加上引号,以便用作 SQL 语句字符串中的字符串字面量。正确地将嵌入的单引号和反斜杠加倍。请注意,quote_literal 会对未定义的输入返回未定义;如果参数可能是未定义的,则通常 quote_nullable 更合适。

quote_nullable(string)

返回给定字符串,将其适当地加上引号,以便用作 SQL 语句字符串中的字符串字面量;或者,如果参数未定义,则返回未加引号的字符串“NULL”。正确地将嵌入的单引号和反斜杠加倍。

quote_ident(string)

返回给定字符串,将其适当地加上引号,以便用作 SQL 语句字符串中的标识符。仅在必要时添加引号(即,如果字符串包含非标识符字符或将转换为小写)。正确地将嵌入的引号加倍。

decode_bytea(string)

返回由给定字符串内容表示的未转义二进制数据,该字符串应采用 bytea 编码。

encode_bytea(string)

返回给定字符串的二进制数据内容的 bytea 编码形式。

encode_array_literal(array)
encode_array_literal(array, delimiter)

以数组字面格式将引用的数组内容作为字符串返回(请参见第 8.15.2 节)。如果引用不是指向数组,则未做更改地返回参数值。用于数组字面元素之间的分隔符在未指定分隔符或其为 undef 时默认为 ", "。

encode_typed_literal(value, typename)

将 Perl 变量转换为作为第二个参数传递的数据类型的数值,并返回该值的字符串表示形式。正确处理嵌套数组和复合类型的数值。

encode_array_constructor(array)

以数组构造函数格式将引用的数组内容作为字符串返回(请参见第 4.2.12 节)。使用 quote_nullable 对各个数值进行引用。如果引用不是指向数组,则使用 quote_nullable 对参数值进行引用并返回。

looks_like_number(string)

如果给定字符串的内容按照 Perl 看来像一个数字,则返回真值,否则返回假值。如果参数为 undef,则返回 undef。前导和尾随空格将被忽略。InfInfinity 被视为数字。

is_array_ref(argument)

如果给定的参数可以被视为数组引用(换句话说,如果参数的 ref 为 ARRAYPostgreSQL::InServer::ARRAY),则返回真值。否则返回假值。