+ url="http://www.cpan.org/SITES.html">
CPAN 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>-
+ $pg_dbh that can be used to perform queries with
in PL/Perl
-
- in PL/Perl
-
- spi_exec_query( [ SELECT query [, max_rows]] | [non-SELECT query] )
+ spi_exec_query(query [, max-rows])
+ spi_exec_query(command)
- Here is an example of a SELECT query with the optional maximum
-number of rows.
+ Executes an SQL command. Here is an example of a query
+ (SELECT command) with the optional maximum
+ number of rows:
-$rv = spi_exec_query('SELECT * from my_table', 5);
+$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
+ This returns up to 5 rows from the table
+ my_table. If my_table
+ has a column my_column, it could be accessed
+ like this:
$foo = $rv->{rows}[$i]->{my_column};
-
-The number of rows actually returned would be:
+ The total number of rows returned can be accessed like this:
$nrows = @{$rv->{rows}};
-
-Here is an example using a non-SELECT statement.
+
+
+ Here is an example using a different command type:
$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.
+ You can then access the command status (e.g.,
+ SPI_OK_INSERT) like this:
$res = $rv->{status};
-
-
-To get the rows affected, do:
+ To get the number of rows affected, do:
$nrows = $rv->{rows};
-
-
+
-
+
- elog level, msg
+
+ in PL/Perl
+
+
+ elog(level, msg)
Emit a log or error message. Possible levels are
- 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. Note that a composite type is always represented as a
- hash reference.
+ PL/Perl can also return row sets and composite types, and row sets
+ of composite types. Here is an example of a PL/Perl function
+ returning a row set of a row type. Note that a composite type is
+ always represented as a hash reference.
CREATE TABLE test (
- i int,
- v varchar
+ 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');
+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 $$
+CREATE FUNCTION test_munge() RETURNS SETOF test AS $$
my $res = [];
- my $rv = spi_exec_query('select i,v from test;');
+ 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) {
+ 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;
+ push @$res, $row;
}
return $res;
-$$;
+$$ LANGUAGE plperl;
-select * from test_munge();
+SELECT * FROM test_munge();
- Here is an example of a PL/Perl function returning a composite type:
+ 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'};
-
+ 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. As a rowset is always a reference to an array
-and a composite type is always a reference to a hash, a rowset of a
-composite type is a reference to an array of hash references.
+ Here is an example of a PL/Perl function returning a row set of a
+ composite type. Since a row set is always a reference to an array
+ and a composite type is always a reference to a hash, a rowset of a
+ composite type is a reference to an array of hash references.
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'}
- ];
+ return [
+ { f1 => 1, f2 => 'Hello', f3 => 'World' },
+ { f1 => 2, f2 => 'Hello', f3 => 'PostgreSQL' },
+ { f1 => 3, f2 => 'Hello', f3 => 'PL/Perl' }
+ ];
$$ LANGUAGE plperl;
+
Global Values in PL/Perl
+
- You can use the %_SHARED to store data between function calls.
-
-For example:
+ You can use the global hash %_SHARED to store
+ data between function calls. For example:
-CREATE OR REPLACE FUNCTION set_var(name TEXT, val TEXT) RETURNS TEXT AS $$
+CREATE OR REPLACE FUNCTION set_var(name text, val text) RETURNS text AS $$
if ($_SHARED{$_[0]} = $_[1]) {
return 'ok';
} else {
- return "Can't set shared variable $_[0] to $_[1]";
+ return "can't set shared variable $_[0] to $_[1]";
}
$$ LANGUAGE plperl;
-CREATE OR REPLACE FUNCTION get_var(name TEXT) RETURNS text AS $$
+CREATE OR REPLACE FUNCTION get_var(name text) RETURNS text AS $$
return $_SHARED{$_[0]};
$$ LANGUAGE plperl;
-SELECT set_var('sample', $q$Hello, PL/Perl! How's tricks?$q$);
+SELECT set_var('sample', 'Hello, PL/Perl! How's tricks?');
SELECT get_var('sample');
-
-
-
plperlu, execution would succeed.
+
PL/Perl Triggers
- PL/Perl can now be used to write trigger functions using the
-$_TD hash reference.
-
+ PL/Perl can be used to write trigger functions. The global hash
+ reference $_TD contains information about the
+ current trigger event. The parts of $_TD hash
+ reference are:
- Some useful parts of the $_TD hash reference are:
+
+
+ $_TD->{new}{foo}
+
+ NEW value of column foo
+
+
+
-$_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?
-
+
+ $_TD->{old}{foo}
+
+ OLD value of column foo
+
+
+
+
+
+ $_TD{name}
+
+ Name of the trigger being called
+
+
+
+
+
+ $_TD{event}
+
+ Trigger event: INSERT, UPDATE, DELETE, or UNKNOWN
+
+
+
+
+
+ $_TD{when}
+
+ When the trigger was called: BEFORE, AFTER, or UNKNOWN
+
+
+
+
+
+ $_TD{level}
+
+ The trigger level: ROW, STATEMENT, or UNKNOWN
+
+
+
+
+
+ $_TD{relid}
+
+ OID of the table on which the trigger fired
+
+
+
+
+ $_TD{relname}
+
+ Name of the table on which the trigger fired
+
+
+
+
+
+ @{$_TD{argv}}
+
+ Arguments of the trigger function
+
+
+
+
+
+ $_TD{argc}
+
+ Number of arguments of the trigger functions
+
+
+
+
Triggers can return one of the following:
-return; -- Executes the statement
-SKIP; -- Doesn't execute the statement
-MODIFY; -- Says it modified a NEW row
-
+
+
+
+ return;
+
+ Execute the statement
+
+
+
+
+
+ "SKIP"
+
+ Don't execute the statement
+
+
+
+
+
+ "MODIFY"
+
+ Indicates that the NEW rows was modified by
+ the trigger function
+
+
+
+
-Here is an example of a trigger function, illustrating some of the
-above.
+ Here is an example of a trigger function, illustrating some of the
+ above:
CREATE TABLE test (
- i int,
- v varchar
+ 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
+ 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
+ return "MODIFY"; # modify row and execute INSERT/UPDATE command
} else {
- return; # Proceed INSERT/UPDATE command
+ return; # execute INSERT/UPDATE command
}
$$ LANGUAGE plperl;
-CREATE TRIGGER "test_valid_id_trig" BEFORE INSERT OR UPDATE ON test
-FOR EACH ROW EXECUTE PROCEDURE "valid_id"();
+CREATE TRIGGER test_valid_id_trig
+ BEFORE INSERT OR UPDATE ON test
+ FOR EACH ROW EXECUTE PROCEDURE valid_id();
-
Full SPI is not yet implemented.
+ SPI is not yet fully implemented.
+
- 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.
-
+ In the current implementation, if you are fetching or returning
+ very large data sets, 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