diff --git a/doc/src/sgml/plhandler.sgml b/doc/src/sgml/plhandler.sgml index b6ad9a6630..8090f96272 100644 --- a/doc/src/sgml/plhandler.sgml +++ b/doc/src/sgml/plhandler.sgml @@ -1,5 +1,5 @@ @@ -154,6 +154,12 @@ CREATE LANGUAGE plsample + + The procedural languages included in the standard distribution + are good references when trying to write your own call handler. + Look into the src/pl subdirectory of the source tree. + + @@ -132,9 +132,66 @@ CREATE FUNCTION empcomp(employee) RETURNS integer AS $$ return $emp->{basesalary} + $emp->{bonus}; $$ LANGUAGE plperl; -SELECT name, empcomp(employee) FROM employee; +SELECT name, empcomp(employee.*) FROM employee; + + + A PL/Perl function can return a composite-type result using the same + approach: return a reference to a hash that has the required attributes. + For example, + + +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; + +SELECT * FROM perl_row(); + + + Any columns in the declared result data type that are not present in the + hash will be returned as NULLs. + + + + PL/Perl functions can also return sets of either scalar or composite + types. To do this, return a reference to an array that contains + either scalars or references to hashes, respectively. Here are + some simple examples: + + +CREATE OR REPLACE FUNCTION perl_set_int(int) RETURNS SETOF INTEGER AS $$ +return [0..$_[0]]; +$$ LANGUAGE plperl; + +SELECT * FROM perl_set_int(5); + + +CREATE OR REPLACE FUNCTION perl_set() RETURNS SETOF testrowperl AS $$ + return [ + { f1 => 1, f2 => 'Hello', f3 => 'World' }, + { f1 => 2, f2 => 'Hello', f3 => 'PostgreSQL' }, + { f1 => 3, f2 => 'Hello', f3 => 'PL/Perl' } + ]; +$$ LANGUAGE plperl; + +SELECT * FROM perl_set(); + + + Note that when you do this, Perl will have to build the entire array in + memory; therefore the technique does not scale to very large result sets. + + + + PL/Perl does not currently have full support for + domain types: it treats a domain the same as the underlying scalar + type. This means that constraints associated with the domain will + not be enforced. This is not an issue for function arguments, but + it is a hazard if you declare a PL/Perl function + as returning a domain type. + @@ -204,53 +261,9 @@ $res = $rv->{status}; $nrows = $rv->{processed}; - - - - - elog - in PL/Perl - - - elog(level, msg) - - Emit a log or error message. Possible levels are - DEBUG, LOG, INFO, - NOTICE, WARNING, and ERROR. - ERROR - raises an error condition; if this is not trapped by the surrounding - Perl code, the error propagates out to the calling query, causing - the current transaction or subtransaction to be aborted. This - is effectively the same as the Perl die command. - The other levels simply report the message to the system log - and/or client. - - - - - - - - - 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 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. + Here is a complete example: CREATE TABLE test ( i int, @@ -278,36 +291,53 @@ $$ LANGUAGE plperl; SELECT * FROM test_munge(); + + + + + + + elog + in PL/Perl + + + elog(level, msg) + + + Emit a log or error message. Possible levels are + DEBUG, LOG, INFO, + NOTICE, WARNING, and ERROR. + ERROR + raises an error condition; if this is not trapped by the surrounding + Perl code, the error propagates out to the calling query, causing + the current transaction or subtransaction to be aborted. This + is effectively the same as the Perl die command. + The other levels only generate messages of different + priority levels. + Whether messages of a particular priority are reported to the client, + written to the server log, or both is controlled by the + and + configuration + variables. See for more + information. + + + + + + + + Data Values in PL/Perl - 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 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 row set 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 => 'PostgreSQL' }, - { f1 => 3, f2 => 'Hello', f3 => 'PL/Perl' } - ]; -$$ LANGUAGE plperl; - + 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, within the PL/Perl function, + all values are just text strings. @@ -317,8 +347,7 @@ $$ LANGUAGE plperl; You can use the global hash %_SHARED to store data, including code references, between function calls for the - lifetime of the current session, which is bounded from below by - the lifetime of the current transaction. + lifetime of the current session. @@ -360,12 +389,12 @@ SELECT myfuncs(); /* initializes the function */ CREATE OR REPLACE FUNCTION use_quote(TEXT) RETURNS text AS $$ my $text_to_quote = shift; my $qfunc = $_SHARED{myquote}; - return &$qfunc($text_to_quote); + return &$qfunc($text_to_quote); $$ LANGUAGE plperl; (You could have replaced the above with the one-liner - return $_SHARED{myquote}->($_[0]); + return $_SHARED{myquote}->($_[0]); at the expense of readability.) @@ -619,9 +648,7 @@ CREATE TRIGGER test_valid_id_trig 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. + into memory. diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index 6352116cb9..96d68d6d5b 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -1,5 +1,5 @@ @@ -150,7 +150,7 @@ $$ LANGUAGE plpgsql; SQL is the language PostgreSQL - (and most other relational databases) use as query language. It's + and most other relational databases use as query language. It's portable and easy to learn. But every SQL statement must be executed individually by the database server. @@ -214,6 +214,15 @@ $$ LANGUAGE plpgsql; Finally, a PL/pgSQL function may be declared to return void if it has no useful return value. + + + PL/pgSQL does not currently have full support for + domain types: it treats a domain the same as the underlying scalar + type. This means that constraints associated with the domain will + not be enforced. This is not an issue for function arguments, but + it is a hazard if you declare a PL/pgSQL function + as returning a domain type. + @@ -267,7 +276,8 @@ $$ LANGUAGE plpgsql; the code can become downright incomprehensible, because you can easily find yourself needing half a dozen or more adjacent quote marks. It's recommended that you instead write the function body as a - dollar-quoted string literal. In the dollar-quoting + dollar-quoted string literal (see ). In the dollar-quoting approach, you never double any quote marks, but instead take care to choose a different dollar-quoting delimiter for each level of nesting you need. For example, you might write the CREATE @@ -437,8 +447,10 @@ END; Each declaration and each statement within a block is terminated - by a semicolon, although the final END that - concludes a function body does not require one. + by a semicolon. A block that appears within another block must + have a semicolon after END, as shown above; + however the final END that + concludes a function body does not require a semicolon. @@ -503,7 +515,7 @@ $$ LANGUAGE plpgsql; transaction, since there would be no context for them to execute in. However, a block containing an EXCEPTION clause effectively forms a subtransaction that can be rolled back without affecting the - outer transaction. For more details see . @@ -556,7 +568,7 @@ arow RECORD; The default value is evaluated every time the block is entered. So, - for example, assigning 'now' to a variable of type + for example, assigning now() to a variable of type timestamp causes the variable to have the time of the current function call, not the time when the function was precompiled. @@ -581,6 +593,9 @@ user_id CONSTANT integer := 10; $n parameter names for increased readability. Either the alias or the numeric identifier can then be used to refer to the parameter value. + + + There are two ways to create an alias. The preferred way is to give a name to the parameter in the CREATE FUNCTION command, for example: @@ -827,17 +842,11 @@ RENAME this_var TO that_var; All expressions used in PL/pgSQL statements are processed using the server's regular - SQL executor. Expressions that appear to - contain constants may in fact require run-time evaluation - (e.g., 'now' for the timestamp - type) so it is impossible for the - PL/pgSQL parser to identify real - constant values other than the key word NULL. All expressions are - evaluated internally by executing a query + SQL executor. In effect, a query like SELECT expression - using the SPI manager. For evaluation, + is executed using the SPI manager. Before evaluation, occurrences of PL/pgSQL variable identifiers are replaced by parameters, and the actual values from the variables are passed to the executor in the parameter array. @@ -1013,6 +1022,14 @@ SELECT INTO target select_expressions + + The INTO clause can appear almost anywhere in the + SELECT statement. Customarily it is written + either just after SELECT as shown above, or + just before FROM — that is, either just before + or just after the list of select_expressions. + + If the query returns zero rows, null values are assigned to the target(s). If the query returns multiple rows, the first @@ -1022,14 +1039,11 @@ SELECT INTO target select_expressions - The INTO clause can appear almost anywhere in the SELECT - statement. - - - - You can use FOUND immediately after a SELECT - INTO statement to determine whether the assignment was successful - (that is, at least one row was was returned by the query). For example: + You can check the special FOUND variable (see + ) after a + SELECT INTO statement to determine whether the + assignment was successful, that is, at least one row was was returned by + the query. For example: SELECT INTO myrec * FROM emp WHERE empname = myname; @@ -1175,22 +1189,13 @@ EXECUTE command-string; be inserted in the command string as it is constructed. - - When working with dynamic commands you will often have to handle escaping - of single quotes. The recommended method for quoting fixed text in your - function body is dollar quoting. If you have legacy code that does - not use dollar quoting, please refer to the - overview in , which can save you - some effort when translating said code to a more reasonable scheme. - - Unlike all other commands in PL/pgSQL, a command run by an EXECUTE statement is not prepared and saved just once during the life of the session. Instead, the command is prepared each time the statement is run. The command string can be dynamically created within the function to perform - actions on variable tables and columns. + actions on different tables and columns. @@ -1207,6 +1212,18 @@ EXECUTE command-string; + When working with dynamic commands you will often have to handle escaping + of single quotes. The recommended method for quoting fixed text in your + function body is dollar quoting. (If you have legacy code that does + not use dollar quoting, please refer to the + overview in , which can save you + some effort when translating said code to a more reasonable scheme.) + + + + Dynamic values that are to be inserted into the constructed + query require special handling since they might themselves contain + quote characters. An example (this assumes that you are using dollar quoting for the function as a whole, so the quote marks need not be doubled): @@ -1333,17 +1350,18 @@ GET DIAGNOSTICS integer_var = ROW_COUNT; all three variants of the FOR statement (integer FOR loops, record-set FOR loops, and dynamic record-set FOR - loops). FOUND is only set when the - FOR loop exits: inside the execution of the loop, + loops). FOUND is set this way when the + FOR loop exits; inside the execution of the loop, FOUND is not modified by the FOR statement, although it may be changed by the execution of other statements within the loop body. - FOUND is a local variable; any changes - to it affect only the current PL/pgSQL - function. + + FOUND is a local variable within each + PL/pgSQL function; so any changes + to it affect only the current function. @@ -1434,15 +1452,14 @@ RETURN NEXT expression; SELECT * FROM some_func(); - That is, the function is used as a table source in a FROM - clause. + That is, the function must be used as a table source in a + FROM clause. RETURN NEXT does not actually return from the - function; it simply saves away the value of the expression (or - record or row variable, as appropriate for the data type being - returned). Execution then continues with the next statement in + function; it simply saves away the value of the expression. + Execution then continues with the next statement in the PL/pgSQL function. As successive RETURN NEXT commands are executed, the result set is built up. A final RETURN, which should @@ -1727,7 +1744,7 @@ END LOOP; BEGIN -- some computations IF stocks > 100000 THEN - EXIT; -- invalid; cannot use EXIT outside of LOOP + EXIT; -- causes exit from the BEGIN block END IF; END; @@ -1821,8 +1838,9 @@ FOR record_or_row IN query END LOOP; The record or row variable is successively assigned each row - resulting from the query (which must be a SELECT - command) and the loop body is executed for each row. Here is an example: + resulting from the query (which must be a + SELECT command) and the loop body is executed for each + row. Here is an example: CREATE FUNCTION cs_refresh_mviews() RETURNS integer AS $$ DECLARE @@ -1874,7 +1892,7 @@ END LOOP; IN and LOOP. If .. is not seen then the loop is presumed to be a loop over rows. Mistyping the .. is thus likely to lead to a complaint along the lines of - loop variable of loop over rows must be a record or row, + loop variable of loop over rows must be a record or row variable, rather than the simple syntax error one might expect to get. @@ -1902,7 +1920,7 @@ EXCEPTION handler_statements WHEN condition OR condition ... THEN handler_statements - ... + ... END; @@ -2060,7 +2078,7 @@ DECLARE <command>OPEN FOR SELECT</command> -OPEN unbound-cursor FOR SELECT ...; +OPEN unbound_cursor FOR SELECT ...; @@ -2086,7 +2104,7 @@ OPEN curs1 FOR SELECT * FROM foo WHERE key = mykey; <command>OPEN FOR EXECUTE</command> -OPEN unbound-cursor FOR EXECUTE query-string; +OPEN unbound_cursor FOR EXECUTE query_string; @@ -2111,7 +2129,7 @@ OPEN curs1 FOR EXECUTE 'SELECT * FROM ' || quote_ident($1); Opening a Bound Cursor -OPEN bound-cursor ( argument_values ) ; +OPEN bound_cursor ( argument_values ) ; @@ -2312,8 +2330,8 @@ RAISE level ' and + configuration variables. See for more information. @@ -2573,11 +2591,8 @@ CREATE TRIGGER emp_stamp BEFORE INSERT OR UPDATE ON emp Another way to log changes to a table involves creating a new table that - holds a row for each insert, update, delete that occurs. This approach can - be thought of as auditing changes to a table. - - - + holds a row for each insert, update, or delete that occurs. This approach + can be thought of as auditing changes to a table. shows an example of an audit trigger procedure in PL/pgSQL. @@ -2606,7 +2621,7 @@ CREATE TABLE emp_audit( salary integer ); -CREATE OR REPLACE FUNCTION process_emp_audit() RETURNS TRIGGER AS $emp_audit$ +CREATE OR REPLACE FUNCTION process_emp_audit() RETURNS TRIGGER AS $emp_audit$ BEGIN -- -- Create a row in emp_audit to reflect the operation performed on emp, @@ -2622,14 +2637,13 @@ CREATE OR REPLACE FUNCTION process_emp_audit() RETURNS TRIGGER AS $emp_audit$ INSERT INTO emp_audit SELECT 'I', now(), user, NEW.*; RETURN NEW; END IF; + RETURN NULL; -- result is ignored since this is an AFTER trigger END; $emp_audit$ language plpgsql; - CREATE TRIGGER emp_audit AFTER INSERT OR UPDATE OR DELETE ON emp - FOR EACH ROW EXECUTE PROCEDURE process_emp_audit() -; + FOR EACH ROW EXECUTE PROCEDURE process_emp_audit(); diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml index a3d64bd353..32fce8c4c6 100644 --- a/doc/src/sgml/plpython.sgml +++ b/doc/src/sgml/plpython.sgml @@ -1,4 +1,4 @@ - + PL/Python - Python Procedural Language @@ -46,15 +46,16 @@ PL/Python Functions - The Python code you write gets transformed into a Python function. - For example, + Functions in PL/Python are declared in the usual way, for example CREATE FUNCTION myfunc(text) RETURNS text AS 'return args[0]' LANGUAGE plpythonu; - gets transformed into + The Python code that is given as the body of the function definition + gets transformed into a Python function. + For example, the above results in def __plpython_procedure_myfunc_23456(): @@ -151,19 +152,23 @@ def __plpython_procedure_myfunc_23456(): plpy.notice(msg), plpy.warning(msg), plpy.error(msg), and - plpy.fatal(msg). - These are mostly equivalent to calling - elog(level, msg) - from C code.elogin - PL/Python plpy.error and + plpy.fatal(msg).elogin PL/Python + plpy.error and plpy.fatal actually raise a Python exception - which, if uncaught, causes the PL/Python module to call - elog(ERROR, msg) when the function handler - returns from the Python interpreter. raise - plpy.ERROR(msg) and raise - plpy.FATAL(msg) are equivalent to calling + which, if uncaught, propagates out to the calling query, causing + the current transaction or subtransaction to be aborted. + raise plpy.ERROR(msg) and + raise plpy.FATAL(msg) are + equivalent to calling plpy.error and plpy.fatal, respectively. + The other functions only generate messages of different + priority levels. + Whether messages of a particular priority are reported to the client, + written to the server log, or both is controlled by the + and + configuration + variables. See for more information. diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml index b454c6a45f..0ba4d22859 100644 --- a/doc/src/sgml/pltcl.sgml +++ b/doc/src/sgml/pltcl.sgml @@ -1,5 +1,5 @@ @@ -16,7 +16,8 @@ $PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.32 2004/11/21 21:17:02 tgl Exp $ PL/Tcl is a loadable procedural language for the PostgreSQL database system - that enables the Tcl language to be used to write functions and + that enables the Tcl + language to be used to write functions and trigger procedures. @@ -59,7 +60,7 @@ $PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.32 2004/11/21 21:17:02 tgl Exp $ The shared object for the PL/Tcl and PL/TclU call handlers is automatically built and installed in the PostgreSQL - library directory if Tcl/Tk support is specified + library directory if Tcl support is specified in the configuration step of the installation procedure. To install PL/Tcl and/or PL/TclU in a particular database, use the createlang program, for example @@ -77,8 +78,7 @@ $PostgreSQL: pgsql/doc/src/sgml/pltcl.sgml,v 2.32 2004/11/21 21:17:02 tgl Exp $ To create a function in the PL/Tcl language, use the standard syntax: -CREATE FUNCTION funcname -(argument-types) RETURNS return-type AS $$ +CREATE FUNCTION funcname (argument-types) RETURNS return-type AS $$ # PL/Tcl function body $$ LANGUAGE pltcl; @@ -169,7 +169,16 @@ $$ LANGUAGE pltcl; There is currently no support for returning a composite-type - result value. + result value, nor for returning sets. + + + + PL/Tcl does not currently have full support for + domain types: it treats a domain the same as the underlying scalar + type. This means that constraints associated with the domain will + not be enforced. This is not an issue for function arguments, but + it is a hazard if you declare a PL/Tcl function + as returning a domain type. @@ -180,10 +189,11 @@ $$ LANGUAGE pltcl; The argument values supplied to a PL/Tcl 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 + 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/Tcl programmer can - manipulate data values as if they were just text. + the function's declared return type. So, within the PL/Tcl function, + all values are just text strings. @@ -215,9 +225,9 @@ $$ LANGUAGE pltcl; command. The global name of this variable is the function's internal name, and the local name is GD. It is recommended that GD be used - for private data of a function. Use regular Tcl global variables - only for values that you specifically intend to be shared among multiple - functions. + for persistent private data of a function. Use regular Tcl global + variables only for values that you specifically intend to be shared among + multiple functions. @@ -239,48 +249,48 @@ $$ LANGUAGE pltcl; spi_exec -count n -array name command loop-body - Executes an SQL command given as a string. An error in the command - causes an error to be raised. Otherwise, the return value of spi_exec - is the number of rows processed (selected, inserted, updated, or - deleted) by the command, or zero if the command is a utility - statement. In addition, if the command is a SELECT statement, the - values of the selected columns are placed in Tcl variables as - described below. + Executes an SQL command given as a string. An error in the command + causes an error to be raised. Otherwise, the return value of spi_exec + is the number of rows processed (selected, inserted, updated, or + deleted) by the command, or zero if the command is a utility + statement. In addition, if the command is a SELECT statement, the + values of the selected columns are placed in Tcl variables as + described below. - The optional -count value tells - spi_exec the maximum number of rows - to process in the command. The effect of this is comparable to - setting up a query as a cursor and then saying FETCH n. + The optional -count value tells + spi_exec the maximum number of rows + to process in the command. The effect of this is comparable to + setting up a query as a cursor and then saying FETCH n. - If the command is a SELECT statement, the values of the - result columns are placed into Tcl variables named after the columns. + If the command is a SELECT statement, the values of the + result columns are placed into Tcl variables named after the columns. If the -array option is given, the column values are - instead stored into the named associative array, with the - column names used as array indexes. + instead stored into the named associative array, with the + column names used as array indexes. If the command is a SELECT statement and no loop-body - script is given, then only the first row of results are stored into - Tcl variables; remaining rows, if any, are ignored. No storing occurs - if the - query returns no rows. (This case can be detected by checking the - result of spi_exec.) For example, + script is given, then only the first row of results are stored into + Tcl variables; remaining rows, if any, are ignored. No storing occurs + if the + query returns no rows. (This case can be detected by checking the + result of spi_exec.) For example, spi_exec "SELECT count(*) AS cnt FROM pg_proc" - will set the Tcl variable $cnt to the number of rows in - the pg_proc system catalog. + will set the Tcl variable $cnt to the number of rows in + the pg_proc system catalog. If the optional loop-body argument is given, it is - a piece of Tcl script that is executed once for each row in the - query result. (loop-body is ignored if the given - command is not a SELECT.) The values of the current row's columns - are stored into Tcl variables before each iteration. For example, + a piece of Tcl script that is executed once for each row in the + query result. (loop-body is ignored if the given + command is not a SELECT.) The values of the current row's columns + are stored into Tcl variables before each iteration. For example, spi_exec -array C "SELECT * FROM pg_class" { @@ -288,14 +298,14 @@ spi_exec -array C "SELECT * FROM pg_class" { } - will print a log message for every row of pg_class. This - feature works similarly to other Tcl looping constructs; in - particular continue and break work in the - usual way inside the loop body. + will print a log message for every row of pg_class. This + feature works similarly to other Tcl looping constructs; in + particular continue and break work in the + usual way inside the loop body. If a column of a query result is null, the target - variable for it is unset rather than being set. + variable for it is unset rather than being set. @@ -304,27 +314,27 @@ spi_exec -array C "SELECT * FROM pg_class" { spi_prepare query typelist - Prepares and saves a query plan for later execution. The - saved plan will be retained for the life of the current - session.preparing a queryin - PL/Tcl + Prepares and saves a query plan for later execution. The + saved plan will be retained for the life of the current + session.preparing a queryin + PL/Tcl The query may use parameters, that is, placeholders for - values to be supplied whenever the plan is actually executed. - In the query string, refer to parameters - by the symbols $1 ... $n. - If the query uses parameters, the names of the parameter types - must be given as a Tcl list. (Write an empty list for - typelist if no parameters are used.) - Presently, the parameter types must be identified by the internal - type names shown in the system table pg_type; for example int4 not - integer. + values to be supplied whenever the plan is actually executed. + In the query string, refer to parameters + by the symbols $1 ... $n. + If the query uses parameters, the names of the parameter types + must be given as a Tcl list. (Write an empty list for + typelist if no parameters are used.) + Presently, the parameter types must be identified by the internal + type names shown in the system table pg_type; for example int4 not + integer. The return value from spi_prepare is a query ID - to be used in subsequent calls to spi_execp. See - spi_execp for an example. + to be used in subsequent calls to spi_execp. See + spi_execp for an example. @@ -333,31 +343,31 @@ spi_exec -array C "SELECT * FROM pg_class" { spi_execp -count n -array name -nulls string queryid value-list loop-body - Executes a query previously prepared with spi_prepare. - queryid is the ID returned by - spi_prepare. If the query references parameters, - a value-list must be supplied. This - is a Tcl list of actual values for the parameters. The list must be - the same length as the parameter type list previously given to - spi_prepare. Omit value-list - if the query has no parameters. + Executes a query previously prepared with spi_prepare. + queryid is the ID returned by + spi_prepare. If the query references parameters, + a value-list must be supplied. This + is a Tcl list of actual values for the parameters. The list must be + the same length as the parameter type list previously given to + spi_prepare. Omit value-list + if the query has no parameters. - The optional value for -nulls is a string of spaces and - 'n' characters telling spi_execp - which of the parameters are null values. If given, it must have exactly the - same length as the value-list. If it - is not given, all the parameter values are nonnull. + The optional value for -nulls is a string of spaces and + 'n' characters telling spi_execp + which of the parameters are null values. If given, it must have exactly the + same length as the value-list. If it + is not given, all the parameter values are nonnull. Except for the way in which the query and its parameters are specified, - spi_execp works just like spi_exec. + spi_execp works just like spi_exec. The -count, -array, and - loop-body options are the same, - and so is the result value. + loop-body options are the same, + and so is the result value. - Here's an example of a PL/Tcl function using a prepared plan: + Here's an example of a PL/Tcl function using a prepared plan: CREATE FUNCTION t1_count(integer, integer) RETURNS integer AS $$ @@ -389,9 +399,9 @@ $$ LANGUAGE pltcl; spi_lastoid - Returns the OID of the row inserted by the last - spi_exec or spi_execp, - if the command was a single-row INSERT. (If not, you get zero.) + Returns the OID of the row inserted by the last + spi_exec or spi_execp, + if the command was a single-row INSERT. (If not, you get zero.) @@ -400,43 +410,43 @@ $$ LANGUAGE pltcl; quote string - Doubles all occurrences of single quote and backslash characters - in the given string. This may be used to safely quote strings - that are to be inserted into SQL commands given - to spi_exec or - spi_prepare. - For example, think about an SQL command string like + Doubles all occurrences of single quote and backslash characters + in the given string. This may be used to safely quote strings + that are to be inserted into SQL commands given + to spi_exec or + spi_prepare. + For example, think about an SQL command string like "SELECT '$val' AS ret" - where the Tcl variable val actually contains - doesn't. This would result - in the final command string + where the Tcl variable val actually contains + doesn't. This would result + in the final command string SELECT 'doesn't' AS ret - which would cause a parse error during - spi_exec or - spi_prepare. - To work properly, the submitted command should contain + which would cause a parse error during + spi_exec or + spi_prepare. + To work properly, the submitted command should contain SELECT 'doesn''t' AS ret - which can be formed in PL/Tcl using + which can be formed in PL/Tcl using "SELECT '[ quote $val ]' AS ret" One advantage of spi_execp is that you don't - have to quote parameter values like this, since the parameters are never - parsed as part of an SQL command string. + have to quote parameter values like this, since the parameters are never + parsed as part of an SQL command string. @@ -452,8 +462,7 @@ SELECT 'doesn''t' AS ret Emits a log or error message. Possible levels are DEBUG, LOG, INFO, NOTICE, WARNING, ERROR, and - FATAL. Most simply emit the given message just like - the elog C function. ERROR + FATAL. ERROR raises an error condition; if this is not trapped by the surrounding Tcl code, the error propagates out to the calling query, causing the current transaction or subtransaction to be aborted. This @@ -461,7 +470,14 @@ SELECT 'doesn''t' AS ret FATAL aborts the transaction and causes the current session to shut down. (There is probably no good reason to use this error level in PL/Tcl functions, but it's provided for - completeness.) + completeness.) The other levels only generate messages of different + priority levels. + Whether messages of a particular priority are reported to the client, + written to the server log, or both is controlled by the + and + configuration + variables. See for more + information. @@ -494,100 +510,100 @@ SELECT 'doesn''t' AS ret $TG_name - - The name of the trigger from the CREATE TRIGGER statement. - + + The name of the trigger from the CREATE TRIGGER statement. + $TG_relid - - The object ID of the table that caused the trigger procedure - to be invoked. - + + The object ID of the table that caused the trigger procedure + to be invoked. + $TG_relatts - - A Tcl list of the table column names, prefixed with an empty list + + A Tcl list of the table column names, prefixed with an empty list element. So looking up a column name in the list with Tcl's lsearch command returns the element's number starting - with 1 for the first column, the same way the columns are customarily - numbered in PostgreSQL. (Empty list - elements also appear in the positions of columns that have been - dropped, so that the attribute numbering is correct for columns - to their right.) - + with 1 for the first column, the same way the columns are customarily + numbered in PostgreSQL. (Empty list + elements also appear in the positions of columns that have been + dropped, so that the attribute numbering is correct for columns + to their right.) + $TG_when - - The string BEFORE or AFTER depending on the - type of trigger call. - + + The string BEFORE or AFTER depending on the + type of trigger call. + $TG_level - - The string ROW or STATEMENT depending on the - type of trigger call. - + + The string ROW or STATEMENT depending on the + type of trigger call. + $TG_op - - The string INSERT, UPDATE, or - DELETE depending on the type of trigger call. - + + The string INSERT, UPDATE, or + DELETE depending on the type of trigger call. + $NEW - - An associative array containing the values of the new table - row for INSERT or UPDATE actions, or - empty for DELETE. The array is indexed by column - name. Columns that are null will not appear in the array. - + + An associative array containing the values of the new table + row for INSERT or UPDATE actions, or + empty for DELETE. The array is indexed by column + name. Columns that are null will not appear in the array. + $OLD - - An associative array containing the values of the old table - row for UPDATE or DELETE actions, or - empty for INSERT. The array is indexed by column - name. Columns that are null will not appear in the array. - + + An associative array containing the values of the old table + row for UPDATE or DELETE actions, or + empty for INSERT. The array is indexed by column + name. Columns that are null will not appear in the array. + $args - - A Tcl list of the arguments to the procedure as given in the - CREATE TRIGGER statement. These arguments are also accessible as - $1 ... $n in the procedure body. - + + A Tcl list of the arguments to the procedure as given in the + CREATE TRIGGER statement. These arguments are also accessible as + $1 ... $n in the procedure body. + @@ -644,39 +660,39 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab Modules and the <function>unknown</> command - PL/Tcl has support for autoloading Tcl code when used. - It recognizes a special table, pltcl_modules, which - is presumed to contain modules of Tcl code. If this table - exists, the module unknown is fetched from the table - and loaded into the Tcl interpreter immediately after creating - the interpreter. + PL/Tcl has support for autoloading Tcl code when used. + It recognizes a special table, pltcl_modules, which + is presumed to contain modules of Tcl code. If this table + exists, the module unknown is fetched from the table + and loaded into the Tcl interpreter immediately after creating + the interpreter. While the unknown module could actually contain any - initialization script you need, it normally defines a Tcl - unknown procedure that is invoked whenever Tcl does - not recognize an invoked procedure name. PL/Tcl's standard version - of this procedure tries to find a module in pltcl_modules - that will define the required procedure. If one is found, it is - loaded into the interpreter, and then execution is allowed to - proceed with the originally attempted procedure call. A - secondary table pltcl_modfuncs provides an index of - which functions are defined by which modules, so that the lookup - is reasonably quick. + initialization script you need, it normally defines a Tcl + unknown procedure that is invoked whenever Tcl does + not recognize an invoked procedure name. PL/Tcl's standard version + of this procedure tries to find a module in pltcl_modules + that will define the required procedure. If one is found, it is + loaded into the interpreter, and then execution is allowed to + proceed with the originally attempted procedure call. A + secondary table pltcl_modfuncs provides an index of + which functions are defined by which modules, so that the lookup + is reasonably quick. The PostgreSQL distribution includes - support scripts to maintain these tables: - pltcl_loadmod, pltcl_listmod, - pltcl_delmod, as well as source for the standard - unknown module in share/unknown.pltcl. This module - must be loaded - into each database initially to support the autoloading mechanism. + support scripts to maintain these tables: + pltcl_loadmod, pltcl_listmod, + pltcl_delmod, as well as source for the standard + unknown module in share/unknown.pltcl. This module + must be loaded + into each database initially to support the autoloading mechanism. The tables pltcl_modules and pltcl_modfuncs - must be readable by all, but it is wise to make them owned and - writable only by the database administrator. + must be readable by all, but it is wise to make them owned and + writable only by the database administrator. diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml index 29624e5eca..2f6db62c66 100644 --- a/doc/src/sgml/spi.sgml +++ b/doc/src/sgml/spi.sgml @@ -1,5 +1,5 @@ @@ -23,8 +23,8 @@ $PostgreSQL: pgsql/doc/src/sgml/spi.sgml,v 1.36 2004/12/13 18:05:09 petere Exp $ The available procedural languages provide various means to - execute SQL commands from procedures. Some of these are based on or - modelled after SPI, so this documentation might be of use for users + execute SQL commands from procedures. Most of these facilities are + based on SPI, so this documentation might be of use for users of those languages as well. @@ -37,15 +37,15 @@ $PostgreSQL: pgsql/doc/src/sgml/spi.sgml,v 1.36 2004/12/13 18:05:09 petere Exp $ - Note that if during the execution of a procedure the transaction is - aborted because of an error in a command, then control will not be - returned to your procedure. Rather, all work will be rolled back - and the server will wait for the next command from the client. A - related restriction is the inability to execute - BEGIN, COMMIT, and - ROLLBACK (transaction control statements) inside - a procedure. Both of these restrictions will probably be changed in - the future. + Note that if a command invoked via SPI fails, then control will not be + returned to your procedure. Rather, the + transaction or subtransaction in which your procedure executes will be + rolled back. (This may seem surprising given that the SPI functions mostly + have documented error-return conventions. Those conventions only apply + for errors detected within the SPI functions themselves, however.) + It is possible to recover control after an error by establishing your own + subtransaction surrounding SPI calls that might fail. This is not currently + documented because the mechanisms required are still in flux. @@ -104,6 +104,7 @@ int SPI_connect(void) SPI, directly nested calls to SPI_connect and SPI_finish are forbidden. + (But see SPI_push and SPI_pop.) @@ -206,7 +207,7 @@ int SPI_finish(void) SPI_push - pushes SPI stack to allow recursive SPI usage + push SPI stack to allow recursive SPI usage SPI_push @@ -253,7 +254,7 @@ void SPI_push(void) SPI_pop - pops SPI stack to return from recursive SPI usage + pop SPI stack to return from recursive SPI usage SPI_pop @@ -322,8 +323,8 @@ SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5); - You may pass multiple commands in one string, and the commands may - be rewritten by rules. SPI_execute returns the + You may pass multiple commands in one string. + SPI_execute returns the result for the command executed last. The count limit applies to each command separately, but it is not applied to hidden commands generated by rules. @@ -693,7 +694,7 @@ void * SPI_prepare(const char * command, int n The plan returned by SPI_prepare can be used - only in the current invocation of the procedure since + only in the current invocation of the procedure, since SPI_finish frees memory allocated for a plan. But a plan can be saved for longer using the function SPI_saveplan. @@ -770,7 +771,7 @@ void * SPI_prepare(const char * command, int n SPI_getargcount - returns the number of arguments needed by a plan + return the number of arguments needed by a plan prepared by SPI_prepare @@ -825,7 +826,7 @@ int SPI_getargcount(void * plan) SPI_getargtypeid - returns the expected typeid for the specified argument of + return the data type OID for an argument of a plan prepared by SPI_prepare @@ -892,7 +893,7 @@ Oid SPI_getargtypeid(void * plan, int argIndex SPI_is_cursor_plan - returns true if a plan + return true if a plan prepared by SPI_prepare can be used with SPI_cursor_open @@ -954,7 +955,7 @@ bool SPI_is_cursor_plan(void * plan) SPI_execute_plan - executes a plan prepared by SPI_prepare + execute a plan prepared by SPI_prepare SPI_execute_plan @@ -1096,7 +1097,7 @@ int SPI_execute_plan(void * plan, Datum * valu SPI_execp - executes a plan in read/write mode + execute a plan in read/write mode SPI_execp @@ -1677,7 +1678,7 @@ char * SPI_fname(TupleDesc rowdesc, int colnum Description - SPI_fname returns the column name of the + SPI_fname returns a copy of the column name of the specified column. (You can use pfree to release the copy of the name when you don't need it anymore.) @@ -1992,7 +1993,7 @@ char * SPI_gettype(TupleDesc rowdesc, int coln Description - SPI_gettype returns the data type name of the + SPI_gettype returns a copy of the data type name of the specified column. (You can use pfree to release the copy of the name when you don't need it anymore.) @@ -2122,7 +2123,7 @@ char * SPI_getrelname(Relation rel) Description - SPI_getrelname returns the name of the + SPI_getrelname returns a copy of the name of the specified relation. (You can use pfree to release the copy of the name when you don't need it anymore.) @@ -2190,7 +2191,7 @@ char * SPI_getrelname(Relation rel) object. SPI_palloc allocates memory in the upper executor context, that is, the memory context that was current when SPI_connect was called, - which is precisely the right context for return a value from your + which is precisely the right context for a value returned from your procedure. @@ -2600,7 +2601,7 @@ HeapTuple SPI_modifytuple(Relation rel, HeapTuple array of the numbers of the columns that are to be changed - (count starts at 1) + (column numbers start at 1) @@ -2674,7 +2675,7 @@ HeapTuple SPI_modifytuple(Relation rel, HeapTuple SPI_freetuple - frees a row allocated in the upper executor context + free a row allocated in the upper executor context SPI_freetuple @@ -2833,16 +2834,15 @@ int SPI_freeplan(void *plan) Visibility of Data Changes - The following two rules govern the visibility of data changes in + The following rules govern the visibility of data changes in functions that use SPI (or any other C function): During the execution of an SQL command, any data changes made by - the command (or by function called by the command, including - trigger functions) are invisible to the command. For - example, in command + the command are invisible to the command itself. For + example, in INSERT INTO a SELECT * FROM a; @@ -2858,6 +2858,29 @@ INSERT INTO a SELECT * FROM a; (during the execution of C) or after C is done. + + + + Commands executed via SPI inside a function called by an SQL command + (either an ordinary function or a trigger) follow one or the + other of the above rules depending on the read/write flag passed + to SPI. Commands executed in read-only mode follow the first + rule: they can't see changes of the calling command. Commands executed + in read-write mode follow the second rule: they can see all changes made + so far. + + + + + + All standard procedural languages set the SPI read-write mode + depending on the volatility attribute of the function. Commands of + STABLE and IMMUTABLE functions are done in + read-only mode, while commands of VOLATILE functions are + done in read-write mode. While authors of C functions are able to + violate this convention, it's unlikely to be a good idea to do so. + + @@ -2934,7 +2957,7 @@ execq(text *sql, int cnt) (This function uses call convention version 0, to make the example - easier to understand. In real applications you should user the new + easier to understand. In real applications you should use the new version 1 interface.) diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 649fd0e4da..dedf4d73f6 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -1,5 +1,5 @@ @@ -823,23 +823,15 @@ CREATE FUNCTION test(int, int) RETURNS int Procedural Language Functions + PostgreSQL allows user-defined functions + to be written in other languages besides SQL and C. These other + languages are generically called procedural + languages (PLs). Procedural languages aren't built into the PostgreSQL server; they are offered - by loadable modules. Please refer to the documentation of the - procedural language in question for details about the syntax and how the - function body is interpreted for each language. - - - - There are currently four procedural languages available in the - standard PostgreSQL distribution: - PL/pgSQL, PL/Tcl, - PL/Perl, and - PL/Python. - Refer to for more information. - Other languages can be defined by users. - The basics of developing a new procedural language are covered in . + by loadable modules. + See and following chapters for more + information. diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml index 88d59d8577..76842017a6 100644 --- a/doc/src/sgml/xplang.sgml +++ b/doc/src/sgml/xplang.sgml @@ -1,5 +1,5 @@ @@ -10,27 +10,32 @@ $PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.27 2004/12/30 03:13:56 tgl Exp $ - PostgreSQL allows users to add new - programming languages to be available for writing functions and - procedures. These are called procedural - languages (PL). In the case of a function or trigger - procedure written in a procedural language, the database server has + PostgreSQL allows user-defined functions + to be written in other languages besides SQL and C. These other + languages are generically called procedural + languages (PLs). For a function + written in a procedural language, the database server has no built-in knowledge about how to interpret the function's source text. Instead, the task is passed to a special handler that knows the details of the language. The handler could either do all the work of parsing, syntax analysis, execution, etc. itself, or it could serve as glue between PostgreSQL and an existing implementation - of a programming language. The handler itself is a special + of a programming language. The handler itself is a C language function compiled into a shared object and - loaded on demand. + loaded on demand, just like any other C function. - Writing a handler for a new procedural language is described in - . Several procedural languages are - available in the core PostgreSQL - distribution, which can serve as examples. + There are currently four procedural languages available in the + standard PostgreSQL distribution: + PL/pgSQL (), + PL/Tcl (), + PL/Perl (), and + PL/Python (). + Other languages can be defined by users. + The basics of developing a new procedural language are covered in . @@ -46,14 +51,16 @@ $PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.27 2004/12/30 03:13:56 tgl Exp $ A procedural language must be installed into each database where it is to be used. But procedural languages installed in the database template1 are automatically available in all - subsequently created databases. So the database administrator can + subsequently created databases, since their entries in + template1 will be copied by CREATE DATABASE. + So the database administrator can decide which languages are available in which databases and can make some languages available by default if he chooses. For the languages supplied with the standard distribution, the - program createlang may be used to install the + program may be used to install the language instead of carrying out the details by hand. For example, to install the language PL/pgSQL into the database @@ -72,23 +79,24 @@ createlang plpgsql template1 - A procedural language is installed in a database in three steps, + A procedural language is installed in a database in four steps, which must be carried out by a database superuser. The - createlang program automates and . + createlang program automates all but . - + The shared object for the language handler must be compiled and installed into an appropriate library directory. This works in the same way as building and installing modules with regular user-defined C - functions does; see . + functions does; see . Often, the language + handler will depend on an external library that provides the actual + programming language engine; if so, that must be installed as well. - + The handler must be declared with the command @@ -104,12 +112,29 @@ CREATE FUNCTION handler_function_name() - + + + Optionally, the language handler may provide a validator + function that checks a function definition for correctness without + actually executing it. The validator function is called by + CREATE FUNCTION if it exists. If a validator function + is provided by the handler, declare it with a command like + +CREATE FUNCTION validator_function_name(oid) + RETURNS void + AS 'path-to-shared-object' + LANGUAGE C; + + + + + The PL must be declared with the command CREATE TRUSTED PROCEDURAL LANGUAGE language-name - HANDLER handler_function_name; + HANDLER handler_function_name + VALIDATOR validator_function_name ; The optional key word TRUSTED specifies that ordinary database users that have no superuser privileges should @@ -150,13 +175,24 @@ CREATE FUNCTION plpgsql_call_handler() RETURNS language_handler AS + + PL/pgSQL has a validator function, + so we declare that too: + + +CREATE FUNCTION plpgsql_validator(oid) RETURNS void AS + '$libdir/plpgsql' LANGUAGE C; + + + The command CREATE TRUSTED PROCEDURAL LANGUAGE plpgsql - HANDLER plpgsql_call_handler; + HANDLER plpgsql_call_handler + VALIDATOR plpgsql_validator; - then defines that the previously declared call handler function + then defines that the previously declared functions should be invoked for functions and trigger procedures where the language attribute is plpgsql. @@ -166,7 +202,7 @@ CREATE TRUSTED PROCEDURAL LANGUAGE plpgsql In a default PostgreSQL installation, the handler for the PL/pgSQL language is built and installed into the library - directory. If Tcl/Tk support is configured in, the handlers for + directory. If Tcl support is configured in, the handlers for PL/Tcl and PL/TclU are also built and installed in the same location. Likewise, the PL/Perl and PL/PerlU handlers are built and installed if Perl support is configured, and PL/PythonU is