pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedDocumentation bug: Chapter 35.4, paragraph 4
5+ messages / 3 participants
[nested] [flat]
* Documentation bug: Chapter 35.4, paragraph 4
@ 2010-11-23 18:08 Jonathan Pool <pool@utilika.org>
0 siblings, 1 reply; 5+ messages in thread
From: Jonathan Pool @ 2010-11-23 18:08 UTC (permalink / raw)
To: pgsql-bugs@postgresql.org; +Cc: Susan Colowick <smc@utilika.org>
Chapter 35.4, paragraph 4, of the PostgreSQL 9.0.1 Documentation says:
Any collection of commands in the SQL language can be packaged together and defined as a function. Besides SELECT queries, the commands can include data modification queries (INSERT, UPDATE, and DELETE), as well as other SQL commands. (The only exception is that you cannot put BEGIN, COMMIT, ROLLBACK, or SAVEPOINT commands into a SQL function.)
This appears to be incorrect, in that attempting to include a VACUUM command in a query-language function elicits the following error message:
ERROR: VACUUM cannot be executed from a function or multi-command string
Thus, presumably "VACUUM" should be added to the list of exceptions.
ˉ
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Documentation bug: Chapter 35.4, paragraph 4
@ 2010-11-28 13:05 Robert Haas <robertmhaas@gmail.com>
parent: Jonathan Pool <pool@utilika.org>
0 siblings, 2 replies; 5+ messages in thread
From: Robert Haas @ 2010-11-28 13:05 UTC (permalink / raw)
To: Jonathan Pool <pool@utilika.org>; +Cc: pgsql-bugs@postgresql.org, Susan Colowick <smc@utilika.org>
On Tue, Nov 23, 2010 at 1:08 PM, Jonathan Pool <pool@utilika.org> wrote:
> Chapter 35.4, paragraph 4, of the PostgreSQL 9.0.1 Documentation says:
>
> Any collection of commands in the SQL language can be packaged together and defined as a function. Besides SELECT queries, the commands can include data modification queries (INSERT, UPDATE, and DELETE), as well as other SQL commands. (The only exception is that you cannot put BEGIN, COMMIT, ROLLBACK, or SAVEPOINT commands into a SQL function.)
>
> This appears to be incorrect, in that attempting to include a VACUUM command in a query-language function elicits the following error message:
>
> ERROR: VACUUM cannot be executed from a function or multi-command string
>
> Thus, presumably "VACUUM" should be added to the list of exceptions.
I fear it's worse than that. Taking a look at the places where we
call PreventTransactionChain(), they appear to include database-wide
CLUSTER, DISCARD ALL, VACUUM (as you noted), COMMIT PREPARED, ROLLBACK
PREPARED, CREATE TABLESPACE, DROP TABLESPACE, ALTER TYPE <enum> ADD
VALUE <label> (but the PreventTransactionChain call says ADD rather
than ADD VALUE), CREATE INDEX CONCURRENTLY, CREATE DATABASE, DROP
DATABASE, and REINDEX DATABASE.
I'm not sure if there's some generic way we could refer to all that
rather than listing them all individually.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: [BUGS] Documentation bug: Chapter 35.4, paragraph 4
@ 2010-12-20 19:31 Robert Haas <robertmhaas@gmail.com>
parent: Robert Haas <robertmhaas@gmail.com>
1 sibling, 0 replies; 5+ messages in thread
From: Robert Haas @ 2010-12-20 19:31 UTC (permalink / raw)
To: pgsql-docs
On Sun, Nov 28, 2010 at 8:05 AM, Robert Haas <robertmhaas@gmail.com> wrote:
> On Tue, Nov 23, 2010 at 1:08 PM, Jonathan Pool <pool@utilika.org> wrote:
>> Chapter 35.4, paragraph 4, of the PostgreSQL 9.0.1 Documentation says:
>>
>> Any collection of commands in the SQL language can be packaged together and defined as a function. Besides SELECT queries, the commands can include data modification queries (INSERT, UPDATE, and DELETE), as well as other SQL commands. (The only exception is that you cannot put BEGIN, COMMIT, ROLLBACK, or SAVEPOINT commands into a SQL function.)
>>
>> This appears to be incorrect, in that attempting to include a VACUUM command in a query-language function elicits the following error message:
>>
>> ERROR: VACUUM cannot be executed from a function or multi-command string
>>
>> Thus, presumably "VACUUM" should be added to the list of exceptions.
>
> I fear it's worse than that. Taking a look at the places where we
> call PreventTransactionChain(), they appear to include database-wide
> CLUSTER, DISCARD ALL, VACUUM (as you noted), COMMIT PREPARED, ROLLBACK
> PREPARED, CREATE TABLESPACE, DROP TABLESPACE, ALTER TYPE <enum> ADD
> VALUE <label> (but the PreventTransactionChain call says ADD rather
> than ADD VALUE), CREATE INDEX CONCURRENTLY, CREATE DATABASE, DROP
> DATABASE, and REINDEX DATABASE.
>
> I'm not sure if there's some generic way we could refer to all that
> rather than listing them all individually.
I feel like it would be valuable to document that the commands
mentioned above can't be executed from within a transaction block.
Looking over TFM, the only obvious place to document this seems to be
in the reference place for BEGIN, perhaps in the Notes section. I
don't think that's a great location - it seems like the sort of thing
that maybe ought to go someplace in section III - but there's no
related content there now.
Thoughts?
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Documentation bug: Chapter 35.4, paragraph 4
@ 2011-03-10 23:50 Bruce Momjian <bruce@momjian.us>
parent: Robert Haas <robertmhaas@gmail.com>
1 sibling, 1 reply; 5+ messages in thread
From: Bruce Momjian @ 2011-03-10 23:50 UTC (permalink / raw)
To: Robert Haas <robertmhaas@gmail.com>; +Cc: Jonathan Pool <pool@utilika.org>; pgsql-bugs@postgresql.org, Susan Colowick <smc@utilika.org>
Robert Haas wrote:
> On Tue, Nov 23, 2010 at 1:08 PM, Jonathan Pool <pool@utilika.org> wrote:
> > Chapter 35.4, paragraph 4, of the PostgreSQL 9.0.1 Documentation says:
> >
> > Any collection of commands in the SQL language can be packaged together and defined as a function. Besides SELECT queries, the commands can include data modification queries (INSERT, UPDATE, and DELETE), as well as other SQL commands. (The only exception is that you cannot put BEGIN, COMMIT, ROLLBACK, or SAVEPOINT commands into a SQL function.)
> >
> > This appears to be incorrect, in that attempting to include a VACUUM command in a query-language function elicits the following error message:
> >
> > ERROR: ?VACUUM cannot be executed from a function or multi-command string
> >
> > Thus, presumably "VACUUM" should be added to the list of exceptions.
>
> I fear it's worse than that. Taking a look at the places where we
> call PreventTransactionChain(), they appear to include database-wide
> CLUSTER, DISCARD ALL, VACUUM (as you noted), COMMIT PREPARED, ROLLBACK
> PREPARED, CREATE TABLESPACE, DROP TABLESPACE, ALTER TYPE <enum> ADD
> VALUE <label> (but the PreventTransactionChain call says ADD rather
> than ADD VALUE), CREATE INDEX CONCURRENTLY, CREATE DATABASE, DROP
> DATABASE, and REINDEX DATABASE.
>
> I'm not sure if there's some generic way we could refer to all that
> rather than listing them all individually.
I just made the wording more generic; we rarely are asked about this,
so generic seemed appropriate. Applied doc patch attached.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ It's impossible for everything to be true. +
Attachments:
/rtmp/doc.diff (text/x-diff, 1.4K) download
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
new file mode 100644
index c65f852..1a35014
*** a/doc/src/sgml/xfunc.sgml
--- b/doc/src/sgml/xfunc.sgml
***************
*** 116,124 ****
Besides <command>SELECT</command> queries, the commands can include data
modification queries (<command>INSERT</command>,
<command>UPDATE</command>, and <command>DELETE</command>), as well as
! other SQL commands. (The only exception is that you cannot put
! <command>BEGIN</>, <command>COMMIT</>, <command>ROLLBACK</>, or
! <command>SAVEPOINT</> commands into a <acronym>SQL</acronym> function.)
However, the final command
must be a <command>SELECT</command> or have a <literal>RETURNING</>
clause that returns whatever is
--- 116,124 ----
Besides <command>SELECT</command> queries, the commands can include data
modification queries (<command>INSERT</command>,
<command>UPDATE</command>, and <command>DELETE</command>), as well as
! other SQL commands. (You cannot use transaction control commands, e.g.
! <command>COMMIT</>, <command>SAVEPOINT</>, and some utility
! commands, e.g. <literal>VACUUM</>, in <acronym>SQL</acronym> functions.)
However, the final command
must be a <command>SELECT</command> or have a <literal>RETURNING</>
clause that returns whatever is
* Re: Documentation bug: Chapter 35.4, paragraph 4
@ 2011-03-11 05:26 Jonathan Pool <pool@utilika.org>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 5+ messages in thread
From: Jonathan Pool @ 2011-03-11 05:26 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Robert Haas <robertmhaas@gmail.com>; pgsql-bugs@postgresql.org, Susan Colowick <smc@utilika.org>
> I just made the wording more generic
Thanks much.
ˉ
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2011-03-11 05:26 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2010-11-23 18:08 Documentation bug: Chapter 35.4, paragraph 4 Jonathan Pool <pool@utilika.org>
2010-11-28 13:05 ` Robert Haas <robertmhaas@gmail.com>
2010-12-20 19:31 ` Robert Haas <robertmhaas@gmail.com>
2011-03-10 23:50 ` Bruce Momjian <bruce@momjian.us>
2011-03-11 05:26 ` Jonathan Pool <pool@utilika.org>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox