From 61e6f930d24d72b1212fafaed904205fa9ca15a0 Mon Sep 17 00:00:00 2001 From: Robert Haas Date: Thu, 21 Mar 2024 10:20:34 -0400 Subject: [PATCH v2 5/5] docs: Merge all procedural language documentation into one chapter. The documentation index is getting very long, which makes it hard to find things. These chapters are consecutive and cover closely related topics, so merge them into one. Hopefully, that will reduce the size of the index without making it harder for users to find the information they need. Rather than actually combining all of the SGML into a single file, keep one file per , and add a glue file that includes all of them. --- doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/plang.sgml | 47 ++++++ doc/src/sgml/plperl.sgml | 52 +++---- doc/src/sgml/plpgsql.sgml | 300 ++++++++++++++++++------------------- doc/src/sgml/plpython.sgml | 80 +++++----- doc/src/sgml/pltcl.sgml | 52 +++---- doc/src/sgml/postgres.sgml | 8 +- doc/src/sgml/xplang.sgml | 42 +----- 8 files changed, 292 insertions(+), 290 deletions(-) create mode 100644 doc/src/sgml/plang.sgml diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 1bb662c16f..b801d1cdf3 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -66,6 +66,7 @@ + diff --git a/doc/src/sgml/plang.sgml b/doc/src/sgml/plang.sgml new file mode 100644 index 0000000000..cdcf81ca3d --- /dev/null +++ b/doc/src/sgml/plang.sgml @@ -0,0 +1,47 @@ + + + + Procedural Languages + + + procedural language + + + + 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 + C language function compiled into a shared object and + loaded on demand, just like any other C function. + + + + There are currently four procedural languages available in the + standard PostgreSQL distribution: + PL/pgSQL (), + PL/Tcl (), + PL/Perl (), and + PL/Python (). + There are additional procedural languages available that are not + included in the core distribution. + has information about finding them. In addition other languages can + be defined by users; the basics of developing a new procedural + language are covered in . + + + &xplang; + &plsql; + &pltcl; + &plperl; + &plpython; + + diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml index 25b1077ad7..912677724a 100644 --- a/doc/src/sgml/plperl.sgml +++ b/doc/src/sgml/plperl.sgml @@ -1,6 +1,6 @@ - + PL/Perl — Perl Procedural Language @@ -46,7 +46,7 @@ - + PL/Perl Functions and Arguments @@ -405,9 +405,9 @@ use strict; The feature pragma is also available to use if your Perl is version 5.10.0 or higher. - + - + Data Values in PL/Perl @@ -425,12 +425,12 @@ use strict; for bool values. Several examples of transform modules are included in the PostgreSQL distribution. - + - + Built-in Functions - + Database Access from PL/Perl @@ -779,9 +779,9 @@ CALL transaction_test1(); - + - + Utility Functions in PL/Perl @@ -993,10 +993,10 @@ CALL transaction_test1(); - - + + - + Global Values in PL/Perl @@ -1069,9 +1069,9 @@ $$ LANGUAGE plperl; them SECURITY DEFINER. You must of course take care that such functions can't be used to do anything unintended. - + - + Trusted and Untrusted PL/Perl @@ -1169,9 +1169,9 @@ $$ LANGUAGE plperl; - + - + PL/Perl Triggers @@ -1357,9 +1357,9 @@ CREATE TRIGGER test_valid_id_trig FOR EACH ROW EXECUTE FUNCTION valid_id(); - + - + PL/Perl Event Triggers @@ -1407,12 +1407,12 @@ CREATE EVENT TRIGGER perl_a_snitch EXECUTE FUNCTION perlsnitch(); - + - + PL/Perl Under the Hood - + Configuration @@ -1538,9 +1538,9 @@ DO 'elog(WARNING, join ", ", sort keys %INC)' LANGUAGE plperl; - + - + Limitations and Missing Features @@ -1588,8 +1588,8 @@ DO 'elog(WARNING, join ", ", sort keys %INC)' LANGUAGE plperl; - + - + - + diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index 6f880b705f..4175e4763b 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -1,13 +1,13 @@ - + <application>PL/pgSQL</application> — <acronym>SQL</acronym> Procedural Language PL/pgSQL - + Overview @@ -65,7 +65,7 @@ administrators could choose to remove it. - + Advantages of Using <application>PL/pgSQL</application> @@ -112,9 +112,9 @@ Also, with PL/pgSQL you can use all the data types, operators and functions of SQL. - + - + Supported Argument and Result Data Types @@ -174,10 +174,10 @@ and . - - + + - + Structure of <application>PL/pgSQL</application> @@ -310,9 +310,9 @@ $$ LANGUAGE plpgsql; outer transaction. For more about that see . - + - + Declarations @@ -393,7 +393,7 @@ DECLARE - + Declaring Function Parameters @@ -637,9 +637,9 @@ SELECT add_three_values(1, 2, 4.7); The function using anyelement would require you to cast the three inputs to the same type manually. - + - + <literal>ALIAS</literal> @@ -669,9 +669,9 @@ DECLARE object, unrestricted use can be confusing. It's best to use it only for the purpose of overriding predetermined names. - + - + Copying Types @@ -724,9 +724,9 @@ user_ids users.user_id%TYPE ARRAY[4]; -- equivalent to the above arguments or result placeholders. - + - + Row Types @@ -787,9 +787,9 @@ $$ LANGUAGE plpgsql; SELECT merge_fields(t.*) FROM table1 t WHERE ... ; - + - + Record Types @@ -817,9 +817,9 @@ SELECT merge_fields(t.*) FROM table1 t WHERE ... ; calling query is parsed, whereas a record variable can change its row structure on-the-fly. - + - + Collation of <application>PL/pgSQL</application> Variables @@ -910,10 +910,10 @@ $$ LANGUAGE plpgsql; parameters, or local variables used in the expression, just as would happen in a plain SQL command. + - - + Expressions @@ -972,9 +972,9 @@ IF count(*) > 0 FROM my_table THEN ... more than one row. (If it produces no rows, the result is taken as NULL.) - + - + Basic Statements @@ -986,7 +986,7 @@ IF count(*) > 0 FROM my_table THEN ... as described in . - + Assignment @@ -1027,9 +1027,9 @@ my_array[1:3] := array[1,2,3]; complex_array[n].realpart = 12.3; - + - + Executing SQL Commands @@ -1146,9 +1146,9 @@ PERFORM query; PERFORM create_mv('cs_session_page_requests_mv', my_query); - + - + Executing a Command with a Single-Row Result @@ -1307,9 +1307,9 @@ CONTEXT: PL/pgSQL function get_userid(text) line 6 at SQL statement - + - + Executing Dynamic Commands @@ -1608,9 +1608,9 @@ EXECUTE format('UPDATE tbl SET %I = $1 WHERE key = $2', colname) linkend="plpgsql-porting-ex2"/>, which builds and executes a CREATE FUNCTION command to define a new function. - + - + Obtaining the Result Status @@ -1749,9 +1749,9 @@ GET DIAGNOSTICS integer_var = ROW_COUNT; affect only the current function. - + - + Doing Nothing At All @@ -1795,10 +1795,10 @@ END; - - + + - + Control Structures @@ -1809,7 +1809,7 @@ END; flexible and powerful way. - + Returning from a Function @@ -1818,7 +1818,7 @@ END; NEXT. - + <command>RETURN</command> @@ -1877,9 +1877,9 @@ RETURN composite_type_var; RETURN (1, 2, 'three'::text); -- must cast columns to correct types - + - + <command>RETURN NEXT</command> and <command>RETURN QUERY</command> RETURN NEXT @@ -2026,10 +2026,10 @@ SELECT * FROM get_available_flightid(CURRENT_DATE); increasing this parameter. - - + + - + Returning from a Procedure @@ -2043,9 +2043,9 @@ SELECT * FROM get_available_flightid(CURRENT_DATE); If the procedure has output parameters, the final values of the output parameter variables will be returned to the caller. - + - + Calling a Procedure @@ -2079,9 +2079,9 @@ $$; variable or a field of a composite-type variable. Currently, it cannot be an element of an array. - + - + Conditionals @@ -2111,7 +2111,7 @@ $$; - + <literal>IF-THEN</literal> @@ -2136,9 +2136,9 @@ IF v_user_id <> 0 THEN END IF; - + - + <literal>IF-THEN-ELSE</literal> @@ -2177,9 +2177,9 @@ ELSE END IF; - + - + <literal>IF-THEN-ELSIF</literal> @@ -2253,9 +2253,9 @@ END IF; for each IF, so it is much more cumbersome than using ELSIF when there are many alternatives. - + - + Simple <literal>CASE</literal> @@ -2296,9 +2296,9 @@ CASE x END CASE; - + - + Searched <literal>CASE</literal> @@ -2347,10 +2347,10 @@ END CASE; than doing nothing. - - + + - + Simple Loops @@ -2365,7 +2365,7 @@ END CASE; PL/pgSQL function to repeat a series of commands. - + <literal>LOOP</literal> @@ -2383,9 +2383,9 @@ END LOOP label ; and CONTINUE statements within nested loops to specify which loop those statements refer to. - + - + <literal>EXIT</literal> @@ -2455,9 +2455,9 @@ BEGIN END; - + - + <literal>CONTINUE</literal> @@ -2503,10 +2503,10 @@ LOOP END LOOP; - + - + <literal>WHILE</literal> @@ -2541,9 +2541,9 @@ WHILE NOT done LOOP END LOOP; - + - + <literal>FOR</literal> (Integer Variant) @@ -2597,10 +2597,10 @@ END LOOP; referenced with a qualified name, using that label. - - + + - + Looping through Query Results @@ -2694,9 +2694,9 @@ END LOOP label ; through is to declare it as a cursor. This is described in . - + - + Looping through Arrays @@ -2778,9 +2778,9 @@ NOTICE: row = {7,8,9} NOTICE: row = {10,11,12} - + - + Trapping Errors @@ -2943,7 +2943,7 @@ SELECT merge_db(1, 'dennis'); - + Obtaining Information about an Error @@ -3069,10 +3069,10 @@ EXCEPTION WHEN OTHERS THEN END; - - + + - + Obtaining Execution Location Information @@ -3124,10 +3124,10 @@ CONTEXT: PL/pgSQL function outer_func() line 3 at RETURN returns the same sort of stack trace, but describing the location at which an error was detected, rather than the current location. + - - + Cursors @@ -3148,7 +3148,7 @@ CONTEXT: PL/pgSQL function outer_func() line 3 at RETURN large row sets from functions. - + Declaring Cursor Variables @@ -3200,9 +3200,9 @@ DECLARE assumes that re-reading the query's output will give consistent results, which a volatile function might not do. - + - + Opening Cursors @@ -3242,7 +3242,7 @@ DECLARE . - + <command>OPEN FOR</command> <replaceable>query</replaceable> @@ -3274,9 +3274,9 @@ OPEN unbound_cursorvar NO - + - + <command>OPEN FOR EXECUTE</command> @@ -3311,9 +3311,9 @@ OPEN curs1 FOR EXECUTE format('SELECT * FROM %I WHERE col1 = $1',tabname) USING is inserted via a USING parameter, so it needs no quoting. - + - + Opening a Bound Cursor @@ -3374,10 +3374,10 @@ BEGIN OPEN curs4; - - + + - + Using Cursors @@ -3401,7 +3401,7 @@ BEGIN only until the end of the transaction. - + <literal>FETCH</literal> @@ -3456,9 +3456,9 @@ FETCH LAST FROM curs3 INTO x, y; FETCH RELATIVE -2 FROM curs4 INTO x; - + - + <literal>MOVE</literal> @@ -3483,9 +3483,9 @@ MOVE RELATIVE -2 FROM curs4; MOVE FORWARD 2 FROM curs4; - + - + <literal>UPDATE/DELETE WHERE CURRENT OF</literal> @@ -3509,9 +3509,9 @@ DELETE FROM table WHERE CURRENT OF curso UPDATE foo SET dataval = myval WHERE CURRENT OF curs1; - + - + <literal>CLOSE</literal> @@ -3530,9 +3530,9 @@ CLOSE cursor; CLOSE curs1; - + - + Returning Cursors @@ -3643,10 +3643,10 @@ FETCH ALL FROM b; COMMIT; - - + + - + Looping through a Cursor's Result @@ -3677,11 +3677,11 @@ END LOOP label ; Each row returned by the cursor is successively assigned to this record variable and the loop body is executed. - + - + - + Transaction Management @@ -3782,12 +3782,12 @@ CALL transaction_test2(); A transaction cannot be ended inside a block with exception handlers. - + - + Errors and Messages - + Reporting Errors and Messages @@ -3984,9 +3984,9 @@ RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id; - + - + Checking Assertions @@ -4043,11 +4043,11 @@ ASSERT condition , RAISE statement, described above, for that. - + - + - + Trigger Functions @@ -4066,7 +4066,7 @@ ASSERT condition , - + Triggers on Data Changes @@ -4680,9 +4680,9 @@ CREATE TRIGGER emp_audit_del - + - + Triggers on Events @@ -4742,11 +4742,11 @@ $$ LANGUAGE plpgsql; CREATE EVENT TRIGGER snitch ON ddl_command_start EXECUTE FUNCTION snitch(); - + - + - + <application>PL/pgSQL</application> under the Hood @@ -4754,7 +4754,7 @@ CREATE EVENT TRIGGER snitch ON ddl_command_start EXECUTE FUNCTION snitch(); frequently important for PL/pgSQL users to know. - + Variable Substitution @@ -4930,9 +4930,9 @@ $$ LANGUAGE plpgsql; the utility statement as a string and EXECUTE it. - + - + Plan Caching @@ -5083,11 +5083,11 @@ $$ LANGUAGE plpgsql; use of the now() function would still be a better idea. - + - + - + Tips for Developing in <application>PL/pgSQL</application> @@ -5124,7 +5124,7 @@ $$ LANGUAGE plpgsql; making it easier to recreate and debug functions. - + Handling of Quotation Marks @@ -5279,8 +5279,8 @@ a_output := a_output || $$ if v_$$ || referrer_keys.kind || $$ like '$$ - - + + Additional Compile-Time and Run-Time Checks @@ -5400,12 +5400,12 @@ HINT: Make sure the query returns the exact list of columns. (1 row) - - + + - + Porting from <productname>Oracle</productname> PL/SQL @@ -5519,7 +5519,7 @@ HINT: Make sure the query returns the exact list of columns. - + Porting Examples @@ -5912,9 +5912,9 @@ $$ LANGUAGE plpgsql; - + - + Other Things to Watch For @@ -5923,7 +5923,7 @@ $$ LANGUAGE plpgsql; PostgreSQL. - + Implicit Rollback after Exceptions @@ -5953,9 +5953,9 @@ END; SAVEPOINT and ROLLBACK TO in a different way then some actual thought will be required. - + - + <command>EXECUTE</command> @@ -5968,9 +5968,9 @@ END; type EXECUTE 'SELECT * FROM $1'; will not work reliably unless you use these functions. - + - + Optimizing <application>PL/pgSQL</application> Functions @@ -5994,10 +5994,10 @@ CREATE FUNCTION foo(...) RETURNS integer AS $$ $$ LANGUAGE plpgsql STRICT IMMUTABLE; - - + + - + Appendix @@ -6126,8 +6126,8 @@ END; $$ LANGUAGE plpgsql STRICT IMMUTABLE; ]]> - + - + - + diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml index e5d51d6e9f..aaedb30d2e 100644 --- a/doc/src/sgml/plpython.sgml +++ b/doc/src/sgml/plpython.sgml @@ -1,6 +1,6 @@ - + PL/Python — Python Procedural Language PL/Python @@ -46,7 +46,7 @@ - + PL/Python Functions @@ -142,9 +142,9 @@ $$ LANGUAGE plpython3u; PL/Python. It is better to treat the function parameters as read-only. - + - + Data Values Generally speaking, the aim of PL/Python is to provide @@ -153,7 +153,7 @@ $$ LANGUAGE plpython3u; below. - + Data Type Mapping When a PL/Python function is called, its arguments are converted from @@ -267,9 +267,9 @@ $$ LANGUAGE plpython3u; return type and the Python data type of the actual return object are not flagged; the value will be converted in any case. - + - + Null, None If an SQL null valuenull valueNone. This can be done whether the function is strict or not. - + - + Arrays, Lists SQL array values are passed into PL/Python as a Python list. To @@ -367,9 +367,9 @@ SELECT return_str_arr(); (1 row) - + - + Composite Types Composite-type arguments are passed to the function as Python mappings. The @@ -514,9 +514,9 @@ $$ LANGUAGE plpython3u; CALL python_triple(5, 10); - + - + Set-Returning Functions A PL/Python function can also return sets of @@ -613,10 +613,10 @@ $$ LANGUAGE plpython3u; SELECT * FROM multiout_simple_setof(3); - - + + - + Sharing Data The global dictionary SD is available to store @@ -634,9 +634,9 @@ SELECT * FROM multiout_simple_setof(3); myfunc2. The exception is the data in the GD dictionary, as mentioned above. - + - + Anonymous Code Blocks @@ -652,9 +652,9 @@ $$ LANGUAGE plpython3u; An anonymous code block receives no arguments, and whatever value it might return is discarded. Otherwise it behaves just like a function. - + - + Trigger Functions @@ -767,9 +767,9 @@ $$ LANGUAGE plpython3u; "MODIFY" to indicate you've modified the new row. Otherwise the return value is ignored. - + - + Database Access @@ -779,7 +779,7 @@ $$ LANGUAGE plpython3u; plpy.foo. - + Database Access Functions @@ -1037,9 +1037,9 @@ $$ LANGUAGE plpython3u; - + - + Trapping Errors @@ -1109,10 +1109,10 @@ $$ LANGUAGE plpython3u; the SQLSTATE error code. This approach provides approximately the same functionality - - + + - + Explicit Subtransactions @@ -1124,7 +1124,7 @@ $$ LANGUAGE plpython3u; the form of explicit subtransactions. - + Subtransaction Context Managers @@ -1189,10 +1189,10 @@ $$ LANGUAGE plpython3u; explicit subtransaction block would also cause the subtransaction to be rolled back. - - + + - + Transaction Management @@ -1229,9 +1229,9 @@ CALL transaction_test1(); Transactions cannot be ended when an explicit subtransaction is active. - + - + Utility Functions The plpy module also provides the functions @@ -1317,9 +1317,9 @@ plpy.execute("UPDATE tbl SET %s = %s WHERE key = %s" % ( plpy.quote_literal(keyvalue))) - + - + Python 2 vs. Python 3 @@ -1328,9 +1328,9 @@ plpy.execute("UPDATE tbl SET %s = %s WHERE key = %s" % ( plpythonu and plpython2u language names. - + - + Environment Variables @@ -1393,5 +1393,5 @@ plpy.execute("UPDATE tbl SET %s = %s WHERE key = %s" % ( the python man page are only effective in a command-line interpreter and not an embedded Python interpreter.) - - + + diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml index b31f2c1330..9e12df3816 100644 --- a/doc/src/sgml/pltcl.sgml +++ b/doc/src/sgml/pltcl.sgml @@ -1,6 +1,6 @@ - + PL/Tcl — Tcl Procedural Language @@ -21,7 +21,7 @@ - + Overview @@ -70,11 +70,11 @@ CREATE EXTENSION pltcl or CREATE EXTENSION pltclu. - + - + PL/Tcl Functions and Arguments @@ -238,9 +238,9 @@ $$ LANGUAGE pltcl; - + - + Data Values in PL/Tcl @@ -252,9 +252,9 @@ $$ LANGUAGE pltcl; result type, or for the specified column of a composite result type. - + - + Global Data in PL/Tcl @@ -314,9 +314,9 @@ $$ LANGUAGE pltcl; An example of using GD appears in the spi_execp example below. - + - + Database Access from PL/Tcl @@ -570,9 +570,9 @@ SELECT 'doesn''t' AS ret - + - + Trigger Functions in PL/Tcl @@ -782,9 +782,9 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab name; that's supplied from the trigger arguments. This lets the trigger function be reused with different tables. - + - + Event Trigger Functions in PL/Tcl @@ -841,9 +841,9 @@ $$ LANGUAGE pltcl; CREATE EVENT TRIGGER tcl_a_snitch ON ddl_command_start EXECUTE FUNCTION tclsnitch(); - + - + Error Handling in PL/Tcl @@ -916,9 +916,9 @@ if {[catch { spi_exec $sql_command }]} { (The double colons explicitly specify that errorCode is a global variable.) - + - + Explicit Subtransactions in PL/Tcl @@ -998,9 +998,9 @@ $$ LANGUAGE pltcl; contained Tcl code (for instance, due to return) do not cause a rollback. - + - + Transaction Management @@ -1039,9 +1039,9 @@ CALL transaction_test1(); Transactions cannot be ended when an explicit subtransaction is active. - + - + PL/Tcl Configuration @@ -1113,9 +1113,9 @@ CALL transaction_test1(); - + - + Tcl Procedure Names @@ -1131,5 +1131,5 @@ CALL transaction_test1(); when debugging. - - + + diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 5bc47a9e71..f841570bc8 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -215,13 +215,7 @@ break is not needed in a wider output rendering. &trigger; &event-trigger; &rules; - - &xplang; - &plsql; - &pltcl; - &plperl; - &plpython; - + &plang; &spi; &bgworker; &logicaldecoding; diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml index 31d403c480..2c0acdc0f7 100644 --- a/doc/src/sgml/xplang.sgml +++ b/doc/src/sgml/xplang.sgml @@ -1,44 +1,6 @@ - - Procedural Languages - - - procedural language - - - - 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 - C language function compiled into a shared object and - loaded on demand, just like any other C function. - - - - There are currently four procedural languages available in the - standard PostgreSQL distribution: - PL/pgSQL (), - PL/Tcl (), - PL/Perl (), and - PL/Python (). - There are additional procedural languages available that are not - included in the core distribution. - has information about finding them. In addition other languages can - be defined by users; the basics of developing a new procedural - language are covered in . - - - + Installing Procedural Languages @@ -226,5 +188,3 @@ CREATE TRUSTED LANGUAGE plperl - - -- 2.39.3 (Apple Git-145)