aboutsummaryrefslogtreecommitdiff
path: root/doc/src/sgml/ref/create_function.sgml
Commit message (Collapse)AuthorAge
* Allow "internal" subtransactions in parallel mode.Tom Lane2024-03-28
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Allow use of BeginInternalSubTransaction() in parallel mode, so long as the subtransaction doesn't attempt to acquire an XID or increment the command counter. Given those restrictions, the other parallel processes don't need to know about the subtransaction at all, so this should be safe. The benefit is that it allows subtransactions intended for error recovery, such as pl/pgsql exception blocks, to be used in PARALLEL SAFE functions. Another reason for doing this is that the API of BeginInternalSubTransaction() doesn't allow reporting failure. pl/python for one, and perhaps other PLs, copes very poorly with an error longjmp out of BeginInternalSubTransaction(). The headline feature of this patch removes the only easily-triggerable failure case within that function. There remain some resource-exhaustion and similar cases, which we now deal with by promoting them to FATAL errors, so that callers need not try to clean up. (It is likely that such errors would leave us with corrupted transaction state inside xact.c, making recovery difficult if not impossible anyway.) Although this work started because of a report of a pl/python crash, we're not going to do anything about that in the back branches. Back-patching this particular fix is obviously not very wise. While we could contemplate some narrower band-aid, pl/python is already an untrusted language, so it seems okay to classify this as a "so don't do that" case. Patch by me, per report from Hao Zhang. Thanks to Robert Haas for review. Discussion: https://postgr.es/m/CALY6Dr-2yLVeVPhNMhuBnRgOZo1UjoTETgtKBx1B2gUi8yy+3g@mail.gmail.com
* Assorted improvements to SECURITY DEFINER functions documentation.Robert Haas2023-01-16
| | | | | | | | | | | | | | | | | | | | | Add a cross-reference from the part of the page that introdues SECURITY INVOKER and SECURITY DEFINER to the part of the page that talks about writing SECURITY DEFINER functions safely, so that users are less likely to miss it. Remove discussion of the pre-8.3 behavior on the theory that it's probably not very relevant any more, that release having gone out of support nearly a decade ago. Add a mention of the new createrole_self_grant GUC, which in certain cases might need to be set to a safe value to avoid unexpected consequences. Possibly this section needs major surgery rather than just these small tweaks, but hopefully this is at least a small step forward. Discussion: http://postgr.es/m/CA+Tgmoauqd1cHQjsNEoxL5O-kEO4iC9dAPyCudSvmNqPJGmy9g@mail.gmail.com
* revert "warn of SECURITY DEFINER schemas for non-sql_body funcs"Bruce Momjian2022-09-28
| | | | | | | | | | | | doc revert of commit 1703726488. Change was applied to irrelevant branches, and was not detailed enough to be helpful in relevant branches. Reported-by: Peter Eisentraut, Noah Misch Discussion: https://postgr.es/m/a2dc9de4-24fc-3222-87d3-0def8057d7d8@enterprisedb.com Backpatch-through: 10
* doc: warn of SECURITY DEFINER schemas for non-sql_body functionsBruce Momjian2022-08-31
| | | | | | | | | | Non-sql_body functions are evaluated at runtime. Reported-by: Erki Eessaar Discussion: https://postgr.es/m/AM9PR01MB8268BF5E74E119828251FD34FE409@AM9PR01MB8268.eurprd01.prod.exchangelabs.com Backpatch-through: 10
* Doc: fix confusion about LEAKPROOF in syntax summaries.Tom Lane2021-06-23
| | | | | | | | | | | | The syntax summaries for CREATE FUNCTION and allied commands made it look like LEAKPROOF is an alternative to IMMUTABLE/STABLE/VOLATILE, when of course it is an orthogonal option. Improve that. Per gripe from aazamrafeeque0. Thanks to David Johnston for suggestions. Discussion: https://postgr.es/m/162444349581.694.5818572718530259025@wrigleys.postgresql.org
* Use the correct article for abbreviationsDavid Rowley2021-06-11
| | | | | | | | | | | | | | | | | | | | | | | We've accumulated quite a mix of instances of "an SQL" and "a SQL" in the documents. It would be good to be a bit more consistent with these. The most recent version of the SQL standard I looked at seems to prefer "an SQL". That seems like a good lead to follow, so here we change all instances of "a SQL" to become "an SQL". Most instances correctly use "an SQL" already, so it also makes sense to use the dominant variation in order to minimise churn. Additionally, there were some other abbreviations that needed to be adjusted. FSM, SSPI, SRF and a few others. Also fix some pronounceable, abbreviations to use "a" instead of "an". For example, "a SASL" instead of "an SASL". Here I've only adjusted the documents and error messages. Many others still exist in source code comments. Translator hint comments seem to be the biggest culprit. It currently does not seem worth the churn to change these. Discussion: https://postgr.es/m/CAApHDvpML27UqFXnrYO1MJddsKVMQoiZisPvsAGhKE_tsKXquw%40mail.gmail.com
* SQL-standard function bodyPeter Eisentraut2021-04-07
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | This adds support for writing CREATE FUNCTION and CREATE PROCEDURE statements for language SQL with a function body that conforms to the SQL standard and is portable to other implementations. Instead of the PostgreSQL-specific AS $$ string literal $$ syntax, this allows writing out the SQL statements making up the body unquoted, either as a single statement: CREATE FUNCTION add(a integer, b integer) RETURNS integer LANGUAGE SQL RETURN a + b; or as a block CREATE PROCEDURE insert_data(a integer, b integer) LANGUAGE SQL BEGIN ATOMIC INSERT INTO tbl VALUES (a); INSERT INTO tbl VALUES (b); END; The function body is parsed at function definition time and stored as expression nodes in a new pg_proc column prosqlbody. So at run time, no further parsing is required. However, this form does not support polymorphic arguments, because there is no more parse analysis done at call time. Dependencies between the function and the objects it uses are fully tracked. A new RETURN statement is introduced. This can only be used inside function bodies. Internally, it is treated much like a SELECT statement. psql needs some new intelligence to keep track of function body boundaries so that it doesn't send off statements when it sees semicolons that are inside a function body. Tested-by: Jaime Casanova <jcasanov@systemguards.com.ec> Reviewed-by: Julien Rouhaud <rjuju123@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/1c11f1eb-f00c-43b7-799d-2d44132c02d7@2ndquadrant.com
* Doc: improve introductory information about procedures.Tom Lane2021-03-10
| | | | | | | | | | | | | Clarify the discussion in "User-Defined Procedures", by laying out the key differences between functions and procedures in a bulleted list. Notably, this avoids burying the lede about procedures being able to do transaction control. Make the back-link in the CREATE FUNCTION reference page more prominent, and add one in CREATE PROCEDURE. Per gripe from Guyren Howe. Thanks to David Johnston for discussion. Discussion: https://postgr.es/m/BYAPR03MB4903C53A8BB7EFF5EA289674A6949@BYAPR03MB4903.namprd03.prod.outlook.com
* Improve <xref> vs. <command> formatting in the documentationPeter Eisentraut2020-10-03
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
* doc: add commas after 'i.e.' and 'e.g.'Bruce Momjian2020-08-31
| | | | | | | | | | | This follows the American format, https://jakubmarian.com/comma-after-i-e-and-e-g/. There is no intention of requiring this format for future text, but making existing text consistent every few years makes sense. Discussion: https://postgr.es/m/20200825183619.GA22369@momjian.us Backpatch-through: 9.5
* doc: make ref/*.sgml file header comment layout consistentBruce Momjian2020-05-15
|
* Create the infrastructure for planner support functions.Tom Lane2019-02-09
| | | | | | | | | | | | | | | | | | | | | | | | | Rename/repurpose pg_proc.protransform as "prosupport". The idea is still that it names an internal function that provides knowledge to the planner about the behavior of the function it's attached to; but redesign the API specification so that it's not limited to doing just one thing, but can support an extensible set of requests. The original purpose of simplifying a function call is handled by the first request type to be invented, SupportRequestSimplify. Adjust all the existing transform functions to handle this API, and rename them fron "xxx_transform" to "xxx_support" to reflect the potential generalization of what they do. (Since we never previously provided any way for extensions to add transform functions, this change doesn't create an API break for them.) Also add DDL and pg_dump support for attaching a support function to a user-defined function. Unfortunately, DDL access has to be restricted to superusers, at least for now; but seeing that support functions will pretty much have to be written in C, that limitation is just theoretical. (This support is untested in this patch, but a follow-on patch will add cases that exercise it.) Discussion: https://postgr.es/m/15193.1548028093@sss.pgh.pa.us
* Refactor documentation about privileges to centralize the info.Tom Lane2018-12-03
| | | | | | | | | | | | Expand section 5.6 "Privileges" to include the full definition of each privilege type, and an explanation of aclitem privilege displays, along with some helpful summary tables. Most of this material came out of the GRANT reference page, although some of it is new. Adjust a bunch of links that were pointing to GRANT to point to 5.6. Fabien Coelho and Tom Lane, reviewed by Bradley DeJong Discussion: https://postgr.es/m/alpine.DEB.2.21.1807311735200.20743@lancre
* Document security implications of qualified names.Noah Misch2018-07-28
| | | | | | | | | | | Commit 5770172cb0c9df9e6ce27c507b449557e5b45124 documented secure schema usage, and that advice suffices for using unqualified names securely. Document, in typeconv-func primarily, the additional issues that arise with qualified names. Back-patch to 9.3 (all supported versions). Reviewed by Jonathan S. Katz. Discussion: https://postgr.es/m/20180721012446.GA1840594@rfd.leadboat.com
* Remove the obsolete WITH clause of CREATE FUNCTION.Tom Lane2018-01-26
| | | | | | | | | | | | | This clause was superseded by SQL-standard syntax back in 7.3. We've kept it around for backwards-compatibility purposes ever since; but 15 years seems like long enough for that, especially seeing that there are undocumented weirdnesses in how it interacts with the SQL-standard syntax for specifying the same options. Michael Paquier, per an observation by Daniel Gustafsson; some small cosmetic adjustments to nearby code by me. Discussion: https://postgr.es/m/20180115022748.GB1724@paquier.xyz
* SQL proceduresPeter Eisentraut2017-11-30
| | | | | | | | | | | | | | | | | | | | | This adds a new object type "procedure" that is similar to a function but does not have a return type and is invoked by the new CALL statement instead of SELECT or similar. This implementation is aligned with the SQL standard and compatible with or similar to other SQL implementations. This commit adds new commands CALL, CREATE/ALTER/DROP PROCEDURE, as well as ALTER/DROP ROUTINE that can refer to either a function or a procedure (or an aggregate function, as an extension to SQL). There is also support for procedures in various utility commands such as COMMENT and GRANT, as well as support in pg_dump and psql. Support for defining procedures is available in all the languages supplied by the core distribution. While this commit is mainly syntax sugar around existing functionality, future features will rely on having procedures as a separate object type. Reviewed-by: Andrew Dunstan <andrew.dunstan@2ndquadrant.com>
* Convert documentation to DocBook XMLPeter Eisentraut2017-11-23
| | | | | | | | | | | | | | | | | | Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
* Convert SGML IDs to lower casePeter Eisentraut2017-10-20
| | | | | | | | | | | | | | IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
* Don't use SGML empty tagsPeter Eisentraut2017-10-17
| | | | | | | | For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
* Upgrade documentation connected with shared_preload_libraries et al.Tom Lane2017-06-20
| | | | | | | | Noplace in the documentation actually defined what these variables contain. Define them as lists of arguments for LOAD, and improve that command's documentation a bit. Discussion: https://postgr.es/m/CAB-oJtxHVDc3H+Km3CjB9mY1VDzuyaVH_ZYSz7iXcRqCtb93Ew@mail.gmail.com
* Remove createlang and droplangPeter Eisentraut2017-03-23
| | | | | | | They have been deprecated since PostgreSQL 9.1. Reviewed-by: Magnus Hagander <magnus@hagander.net> Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
* doc: clarify that function "ownership" that controls permissionBruce Momjian2017-03-20
| | | | | | It used to say the creation user. Reported-by: Nathan Wagner
* Make UNKNOWN into an actual pseudo-type.Tom Lane2017-01-25
| | | | | | | | | | | | Previously, type "unknown" was labeled as a base type in pg_type, which perhaps had some sense to it because you were allowed to create tables with unknown-type columns. But now that we don't allow that, it makes more sense to label it a pseudo-type. This has the additional effects of forbidding use of "unknown" as a domain base type, cast source or target type, PL function argument or result type, or plpgsql local variable type; all of which seem like good holes to plug. Discussion: https://postgr.es/m/CAH2L28uwwbL9HUM-WR=hromW1Cvamkn7O-g8fPY2m=_7muJ0oA@mail.gmail.com
* Doc: clarify description of CREATE/ALTER FUNCTION ... SET FROM CURRENT.Tom Lane2016-08-09
| | | | Per discussion with David Johnston.
* Improve documentation about search_path for SECURITY DEFINER functions.Tom Lane2016-07-15
| | | | | | | | Clarify that the reason for recommending that pg_temp be put last is to prevent temporary tables from capturing unqualified table names. Per discussion with Albe Laurenz. Discussion: <A737B7A37273E048B164557ADEF4A58B5386C6E1@ntex2010i.host.magwien.gv.at>
* doc: Small wording change for clarityPeter Eisentraut2016-05-12
| | | | From: Martín Marqués <martin@2ndquadrant.com>
* Determine whether it's safe to attempt a parallel plan for a query.Robert Haas2015-09-16
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Commit 924bcf4f16d54c55310b28f77686608684734f42 introduced a framework for parallel computation in PostgreSQL that makes most but not all built-in functions safe to execute in parallel mode. In order to have parallel query, we'll need to be able to determine whether that query contains functions (either built-in or user-defined) that cannot be safely executed in parallel mode. This requires those functions to be labeled, so this patch introduces an infrastructure for that. Some functions currently labeled as safe may need to be revised depending on how pending issues related to heavyweight locking under paralllelism are resolved. Parallel plans can't be used except for the case where the query will run to completion. If portal execution were suspended, the parallel mode restrictions would need to remain in effect during that time, but that might make other queries fail. Therefore, this patch introduces a framework that enables consideration of parallel plans only when it is known that the plan will be run to completion. This probably needs some refinement; for example, at bind time, we do not know whether a query run via the extended protocol will be execution to completion or run with a limited fetch count. Having the client indicate its intentions at bind time would constitute a wire protocol break. Some contexts in which parallel mode would be safe are not adjusted by this patch; the default is not to try parallel plans except from call sites that have been updated to say that such plans are OK. This commit doesn't introduce any parallel paths or plans; it just provides a way to determine whether they could potentially be used. I'm committing it on the theory that the remaining parallel sequential scan patches will also get committed to this release, hopefully in the not-too-distant future. Robert Haas and Amit Kapila. Reviewed (in earlier versions) by Noah Misch.
* doc: Spell checkingPeter Eisentraut2015-09-10
|
* Improve CREATE FUNCTION doc WRT to LEAKPROOF RLS interaction.Joe Conway2015-07-30
| | | | Patch by Dean Rasheed. Back-patched to 9.5 where RLS was introduced.
* Add transforms featurePeter Eisentraut2015-04-26
| | | | | | | | This provides a mechanism for specifying conversions between SQL data types and procedural languages. As examples, there are transforms for hstore and ltree for PL/Perl and PL/Python. reviews by Pavel Stěhule and Andres Freund
* doc: Improve DocBook XML validityPeter Eisentraut2014-02-23
| | | | | | | | | | | DocBook XML is superficially compatible with DocBook SGML but has a slightly stricter DTD that we have been violating in a few cases. Although XSLT doesn't care whether the document is valid, the style sheets don't necessarily process invalid documents correctly, so we need to work toward fixing this. This first commit moves the indexterms in refentry elements to an allowed position. It has no impact on the output.
* docs: improve CREATE FUNCTION docs about language case and quotingBruce Momjian2014-02-13
| | | | Report from Marc Mamin
* Clarify CREATE FUNCTION documentation about handling of typmods.Tom Lane2013-11-13
| | | | | The previous text was a bit misleading, as well as unnecessarily vague about what information would be discarded. Per gripe from Craig Skinner.
* Further update CREATE FUNCTION documentation about argument namesPeter Eisentraut2013-06-19
| | | | More languages than SQL and PL/pgSQL actually support parameter names.
* Update CREATE FUNCTION documentation about argument names.Tom Lane2013-05-11
| | | | | | The 9.2 patch that added argument name support in SQL-language functions missed updating a parenthetical comment about that in the CREATE FUNCTION reference page. Noted by Erwin Brandstetter.
* doc: revert 80c20fcf3df17309b3c131962045825f42e45bc7 andBruce Momjian2013-01-25
| | | | | | | | 0e93959a70ac6e7c7858d1d6fb00645e7540a1cc Revert patch that modified doc index mentions of search_path Per Peter E.
* doc: split search_path index entries into separate secondariesBruce Momjian2013-01-25
| | | | Karl O. Pinc
* doc: Update CREATE FUNCTION compatibility informationPeter Eisentraut2013-01-05
| | | | | Parameter defaults are actually in the SQL standard, while it was previously claimed they were not.
* doc: Improve search_path mentions in indexPeter Eisentraut2012-12-13
| | | | Karl O. Pinc
* doc: Put pg_temp into documentation indexPeter Eisentraut2012-11-17
| | | | Karl O. Pinc
* Make CREATE/ALTER FUNCTION support NOT LEAKPROOF.Robert Haas2012-02-15
| | | | Because it isn't good to be able to turn things on, and not off again.
* Allow LEAKPROOF functions for better performance of security views.Robert Haas2012-02-13
| | | | | | | | | | | | | | | | We don't normally allow quals to be pushed down into a view created with the security_barrier option, but functions without side effects are an exception: they're OK. This allows much better performance in common cases, such as when using an equality operator (that might even be indexable). There is an outstanding issue here with the CREATE FUNCTION / ALTER FUNCTION syntax: there's no way to use ALTER FUNCTION to unset the leakproof flag. But I'm committing this as-is so that it doesn't have to be rebased again; we can fix up the grammar in a future commit. KaiGai Kohei, with some wordsmithing by me.
* Add support for privileges on typesPeter Eisentraut2011-12-20
| | | | | | | | | This adds support for the more or less SQL-conforming USAGE privilege on types and domains. The intent is to be able restrict which users can create dependencies on types, which restricts the way in which owners can alter types. reviewed by Yeb Havinga
* Fix a whitespace issue with the man pagesPeter Eisentraut2011-08-07
| | | | | | | | | | | | | | | | | | | | | There is what may actually be a mistake in our markup. The problem is in a situation like <para> <command>FOO</command> is ... there is strictly speaking a line break before "FOO". In the HTML output, this does not appear to be a problem, but in the man page output, this shows up, so you get double blank lines at odd places. So far, we have attempted to work around this with an XSL hack, but that causes other problems, such as creating run-ins in places like <acronym>SQL</acronym> <command>COPY</command> So fix the problem properly by removing the extra whitespace. I only fixed the problems that affect the man page output, not all the places.
* Remove useless whitespace at end of linesPeter Eisentraut2010-11-23
|
* Remove cvs keywords from all files.Magnus Hagander2010-09-20
|
* Remove unnecessary xref endterm attributes and title idsPeter Eisentraut2010-04-03
| | | | | | | | | The endterm attribute is mainly useful when the toolchain does not support automatic link target text generation for a particular situation. In the past, this was required by the man page tools for all reference page links, but that is no longer the case, and it now actually gets in the way of proper automatic link text generation. The only remaining use cases are currently xrefs to refsects.
* Fix SGML markup.Bruce Momjian2010-03-03
|
* Restructure CREATE FUNCTION "NOTES" section to be shorter; move itemsBruce Momjian2010-03-03
| | | | into proper sections, per suggestion from Tom.
* Document that after triggers that need to see changed rows should not beBruce Momjian2010-02-25
| | | | marked stable.
generated by cgit v1.2.3 (git 2.25.1) at 2025-06-07 07:19:04 +0000