spi_exec_query 执行一条 SQL 命令，并把 整个行集作为对一个哈希引用数组的引用返回。 如果指定了 limit 且大于零， 那么 spi_exec_query 至多取回 limit 行，就像查询包含了 LIMIT 子句那样。 省略 limit 或将其指定为 零则表示没有行数限制。

只有当您知道结果集相对较小时才应使用这个 命令。 以下是一个带有可选最大行数的查询 （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 和 spi_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、spi_query_prepared、 spi_exec_prepared 和 spi_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_fetchrow）。 spi_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)

提交或回滚当前事务。这只能在从顶层调用的过程或匿名代码块 （DO 命令）中调用。 （注意，无法通过 spi_exec_query 或类似方式 运行 SQL 命令 COMMIT 或 ROLLBACK。必须 使用这些函数完成。） 事务结束后，会自动开始一个新事务，因此没有单独的函数来做这件 事。

下面是一个例子：

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();

发出一条日志或错误消息。可能的级别有 DEBUG、LOG、 INFO、 NOTICE、WARNING 和 ERROR。 ERROR 会抛出错误条件；如果外围 Perl 代码没有捕获它，该错误会传播到 调用查询，导致当前事务或子事务被中止。 这实际上与 Perl 的 die 命令相同。 其他级别只会生成不同优先级的消息。 特定优先级的消息是否被报告给客户端、写入服务器日志或两者兼有， 由 log_min_messages 和 client_min_messages 配置 变量控制。更多信息见 Chapter 19。

返回经过适当加引号的给定字符串，以便用作 SQL 语句字符串中的字符串字面量。内嵌的单引号和反斜杠会被正确地 加倍。 注意，quote_literal 对 undef 输入返回 undef；如果参数可能是 undef， quote_nullable 通常更合适。

返回经过适当加引号的给定字符串，以便用作 SQL 语句字符串中的字符串字面量；如果参数为 undef，则返回未加引号的 字符串 "NULL"。 内嵌的单引号和反斜杠会被正确地加倍。

返回经过适当加引号的给定字符串，以便用作 SQL 语句字符串中的 标识符。只在必要时才加引号（即字符串包含非标识符字符或会被 折叠大小写时）。内嵌的引号会被正确地加倍。

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

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

把被引用数组的内容作为数组字面量格式的字符串返回 （见 Section 8.15.2）。 如果参数不是对数组的引用，则原样返回参数值。 如果未指定分隔符或分隔符为 undef，则数组字面量元素之间的 分隔符默认为 ", "。

把 Perl 变量转换为第二个参数传入的数据类型的值，并返回该值的 字符串表示。 它能正确处理嵌套数组和复合类型的值。

把被引用数组的内容作为数组构造器格式的字符串返回 （见 Section 4.2.12）。 各个值会用 quote_nullable 加引号。 如果参数不是对数组的引用，则返回用 quote_nullable 加引号的参数值。

按照 Perl 的标准，如果给定字符串的内容看起来像一个数字，返回 真值，否则返回假。 如果参数为 undef，返回 undef。前导和尾随空白会被忽略。 Inf 和 Infinity 被视为 数字。

如果给定的参数可以被当作数组引用，即参数的 ref 是 ARRAY 或 PostgreSQL::InServer::ARRAY，则返回真值。 否则返回假。