url="http://www.cpan.org/modules/by-module/DBD/APILOS/">DBD::PgSPI
- mirror sites). This module makes available a
+ mirror sites). This module makes available a
DBI-compliant database-handle named
$pg_dbh that can be used to perform queries
with normal
DBI syntax.DBI+
- PL/Perl itself presently provides only one additional Perl command:
+ PL/Perl itself presently provides two additional Perl commands:
+
+ in PL/Perl
+
in PL/Perl
+ spi_exec_query( [ SELECT query [, max_rows]] | [non-SELECT query] )
+
+ Here is an example of a SELECT query with the optional maximum
+number of rows.
+$rv = spi_exec_query('SELECT * from my_table', 5);
+
+
+This returns up to 5 rows from my_table.
+
+If my_table has a column my_column, it would be accessed as
+$foo = $rv->{rows}[$i]->{my_column};
+
+
+The number of rows actually returned would be:
+$nrows = @{$rv->{rows}};
+
+
+Here is an example using a non-SELECT statement.
+$query = "INSERT INTO my_table VALUES (1, 'test')";
+$rv = spi_exec_query($query);
+
+
+You can then access status (SPI_OK_INSERT, e.g.) like this.
+$res = $rv->{status};
+
+
+
+To get the rows affected, do:
+$nrows = $rv->{rows};
+
+
+
+
+
+
+
elog level, msg
+
+
Data Values in PL/Perl
+
+ The argument values supplied to a PL/Perl function's code are
+ simply the input arguments converted to text form (just as if they
+ had been displayed by a SELECT statement).
+ Conversely, the return command will accept any string
+ that is acceptable input format for the function's declared return
+ type. So, the PL/Perl programmer can manipulate data values as if
+ they were just text.
+
+
+ PL/Perl can now return rowsets and composite types, and rowsets of
+composite types.
+
+
+ Here is an example of a PL/Perl function returning a rowset of a row type:
+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 function test_munge() returns setof test language plperl as $$
+ my $res = [];
+ my $rv = spi_exec_query('select i,v from test;');
+ my $status = $rv->{status};
+ my $rows = @{$rv->{rows}};
+ my $processed = $rv->{processed};
+ foreach my $rn (0..$rows-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}));
+ push @$res,$row;
+ }
+ return $res;
+$$;
+
+select * from test_munge();
+
+
+
+ Here is an example of a PL/Perl function returning a composite type:
+CREATE TYPE testrowperl AS (f1 integer, f2 text, f3 text);
+
+CREATE OR REPLACE FUNCTION perl_row() RETURNS testrowperl AS $$
+
+ return {f2 => 'hello', f1 => 1, f3 => 'world'};
+
+$$ LANGUAGE plperl;
+
+
+
+ Here is an example of a PL/Perl function returning a rowset of a composite type.
+CREATE TYPE testsetperl AS (f1 integer, f2 text, f3 text);
+
+CREATE OR REPLACE FUNCTION perl_set() RETURNS SETOF testsetperl AS $$
+ return[
+ {f1 => 1, f2 => 'hello', f3 => 'world'},
+ {f1 => 2, f2 => 'hello', f3 => 'postgres'},
+ {f1 => 3, f2 => 'hello', f3 => 'plperl'}
+ ];
+$$ LANGUAGE plperl;
+
+
+
+
+
Global Values in PL/Perl
+ You can use the %_SHARED to store data between function calls. WHY
+IS THIS A HASH, AND NOT A HASH REF?
+
+For example:
+CREATE OR REPLACE FUNCTION set_var(TEXT) RETURNS TEXT AS $$
+ $_SHARED{first} = 'Hello, PL/Perl!';
+ return 'ok';
+$$ LANGUAGE plperl;
+
+CREATE OR REPLACE FUNCTION get_var() RETURNS text AS $$
+ return $_SHARED{first};
+$$ LANGUAGE plperl;
+
+SELECT set_var('hello plperl');
+SELECT get_var();
+
+
+
+
+
+
+
Trusted and Untrusted PL/Perl
plperlu, execution would succeed.
+
+
PL/Perl Triggers
+
+ PL/Perl can now be used to write trigger functions using the
+$_TD hash reference.
+
+
+ Some useful parts of the $_TD hash reference are:
+
+$_TD->{new}{foo} # NEW value of column foo
+$_TD->{old}{bar} # OLD value of column bar
+$_TD{name} # Name of the trigger being called
+$_TD{event} # INSERT, UPDATE, DELETE or UNKNOWN
+$_TD{when} # BEFORE, AFTER or UNKNOWN
+$_TD{level} # ROW, STATEMENT or UNKNOWN
+$_TD{relid} # Relation ID of the table on which the trigger occurred.
+$_TD{relname} # Name of the table on which the trigger occurred.
+@{$_TD{argv}} # Array of arguments to the trigger function. May be empty.
+$_TD{argc} # Number of arguments to the trigger. Why is this here?
+
+
+
+
+ Triggers can return one of the following:
+return; -- Executes the statement
+SKIP; -- Doesn't execute the statement
+MODIFY; -- Says it modified a NEW row
+
+
+
+Here is an example of a trigger function, illustrating some of the
+above.
+CREATE TABLE test (
+ i int,
+ v varchar
+);
+
+CREATE OR REPLACE FUNCTION valid_id() RETURNS trigger AS $$
+ if (($_TD->{new}{i}>=100) || ($_TD->{new}{i}<=0)) {
+ return "SKIP"; # Skip INSERT/UPDATE command
+ } elsif ($_TD->{new}{v} ne "immortal") {
+ $_TD->{new}{v} .= "(modified by trigger)";
+ return "MODIFY"; # Modify tuple and proceed INSERT/UPDATE command
+ } else {
+ return; # Proceed INSERT/UPDATE command
+ }
+$$ LANGUAGE plperl;
+
+CREATE TRIGGER "test_valid_id_trig" BEFORE INSERT OR UPDATE ON test
+FOR EACH ROW EXECUTE PROCEDURE "valid_id"();
+
+
+
-
Missing Features
+
<span class="marked">Limitations and </span>Missing Features
The following features are currently missing from PL/Perl, but they
PL/Perl functions cannot call each other directly (because they
- are anonymous subroutines inside Perl). There's presently no
- way for them to share global variables, either.
+ are anonymous subroutines inside Perl).
- PL/Perl cannot be used to write trigger
- PL/Perl
+
Full SPI is not yet implemented.
-
-
DBD::PgSPI or similar capability
- should be integrated into the standard
-
PostgreSQL distribution.
-
+ In the current implementation, if you are fetching or
+ returning very large datasets, you should be aware that these
+ will all go into memory. Future features will help with this.
+ In the meantime, we suggest that you not use pl/perl if you
+ will fetch or return very large result sets.
+
+
projects / postgresql.git / commitdiff