Postgresql 中文操作指南
45.3. Built-in Functions #
45.3.1. Database Access from PL/Perl #
可以通过以下函数从 Perl 函数访问数据库本身:
-
spi_exec_query(query [, limit_])_
-
spi_exec_query 执行 SQL 命令并返回整个行集,作为对哈希引用的数组的引用。如果指定了 limit 并且它大于 zero,那么 spi_exec_query 最多检索 limit 行,就像查询包含 LIMIT 子句一样。不指定 limit 或将它指定为 zero 会导致无行限制。
-
You should only use this command when you know that the result set will be relatively small. 以下是带可选最大行数的查询 (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_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(_command , argument types )_ spi_query_prepared(_plan , arguments )_ spi_exec_prepared(_plan [, attributes ], arguments )_ spi_freeplan(_plan )_
-
-
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 等定义的,因此避免在双引号中声明容易导致难以发现的 bug 的查询字符串。
-
另一个示例说明了在 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 命令 COMMIT 或 ROLLBACK。必须使用这些函数执行此操作。)在事务结束后,会自动启动一个新事务,因此没有该事务的单独功能。
-
Here is an example:
-
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();
45.3.2. Utility Functions in PL/Perl #
-
elog(_level, msg)_
-
发出日志或错误信息。可能的级别为 DEBUG、LOG、INFO、NOTICE、WARNING 和 ERROR。ERROR 提升错误条件;如果此错误未被周围的 Perl 代码捕获,则错误会传播到调用查询,导致当前事务或子事务中止。这实际上与 Perl die 命令相同。其他级别仅生成不同优先级的消息。是否向客户端报告特定优先级的消息、将消息写入服务器日志或同时进行,由 log_min_messages 和 client_min_messages 配置变量控制。有关更多信息,请参阅 Chapter 20。
-
-
quote_literal(_string)_
-
返回给定字符串,对其适当引用以用作 SQL 语句字符串中的字符串文字。嵌入的单引号和反斜杠被正确加倍。请注意,quote_literal 在 undef 输入上返回 undef;如果参数可能是 undef,quote_nullable 通常更合适。
-
-
quote_nullable(_string)_
-
返回给定字符串,对其适当引用以用作 SQL 语句字符串中的字符串文字;或者,如果参数是 undef,则返回未引用的字符串 "NULL"。嵌入的单引号和反斜杠被正确加倍。
-
-
quote_ident(_string)_
-
返回给定字符串,对其适当引用以用作 SQL 语句字符串中的标识符。仅在必要时添加引号(即,如果字符串包含非标识符字符或会进行大小写折叠)。嵌入的引号被正确加倍。
-
-
decode_bytea(_string)_
-
返回由给定字符串内容表示的未转义二进制数据,该字符串应 bytea 编码。
-
-
encode_bytea(_string)_
-
返回给定字符串的二进制数据内容的 bytea 编码形式。
-
-
encode_array_literal(_array)_ encode_array_literal(_array, delimiter)_
-
以数组文字格式(参见 Section 8.15.2 )返回引用数组的内容,作为一个字符串。如果它不是对数组的引用,则返回未更改的参数值。如果未指定分隔符或分隔符为 undef,则用于数组文字元素之间的分隔符默认为“ , ”。
-
-
encode_typed_literal(_value, typename)_
-
将 Perl 变量转换为作为第二个参数传递的数据类型的变量,并返回此值的一个字符串表示形式。正确处理嵌套数组和复合类型的变量。
-
-
encode_array_constructor(_array)_
-
以数组构造函数格式(参见 Section 4.2.12 )返回引用数组的内容,作为一个字符串。使用 quote_nullable 对单独的值进行引用。如果它不是对数组的引用,则返回使用 quote_nullable 引用的参数值。
-
-
looks_like_number(_string)_
-
如果给定字符串的内容在 Perl 中看起来像一个数字,则返回 true 值,否则返回 false。如果参数是 undef,则返回 undef。忽略前导和尾随空格。将 Inf 和 Infinity 视为一个数字。
-
-
is_array_ref(_argument)_
-
如果给定参数可以视为数组引用,即如果参数的 ref 为 ARRAY 或 PostgreSQL::InServer::ARRAY,则返回 true 值。否则返回 false。
-