Thread: Documentation for SET var_name FROM CURRENT
While reading documentation for SET command, I observed that FROM CURRENT syntax and its description is missing from SET command's syntax page (http://www.postgresql.org/docs/devel/static/sql-set.html). Do you think that documentation should be updated for the same or is there any reason why it is not documented? With Regards, Amit Kapila. EnterpriseDB: http://www.enterprisedb.com
Amit Kapila-2 wrote > While reading documentation for SET command, I observed that FROM > CURRENT syntax and its description is missing from SET command's > syntax page (http://www.postgresql.org/docs/devel/static/sql-set.html). > > Do you think that documentation should be updated for the same or is > there any reason why it is not documented? It is documented as part of "CREATE FUNCTION" since its use is only valid in that context. The paragraph with the link to CREATE FUNCTION seems sufficient to notify and direct people to the needed description for this. David J. -- View this message in context: http://postgresql.1045698.n5.nabble.com/Documentation-for-SET-var-name-FROM-CURRENT-tp5772920p5772922.html Sent from the PostgreSQL - hackers mailing list archive at Nabble.com.
On Tue, Oct 1, 2013 at 10:25 AM, David Johnston <polobo@yahoo.com> wrote: > Amit Kapila-2 wrote >> While reading documentation for SET command, I observed that FROM >> CURRENT syntax and its description is missing from SET command's >> syntax page (http://www.postgresql.org/docs/devel/static/sql-set.html). >> >> Do you think that documentation should be updated for the same or is >> there any reason why it is not documented? > > It is documented as part of "CREATE FUNCTION" since its use is only valid in > that context. Not only as part of "CREATE FUNCTION", but as part of "ALTER DATABASE", "ALTER ROLE", "ALTER FUNCTION" syntax as well. In all these places other syntax of "SET" is also used and described. I think you are right that syntax <SET .. FROM CURRENT> is mainly used in context with few other SQL statements, but as it is part of SET command, so isn't it better to mention the syntax on SET page and may be explain a bit about its usage? > The paragraph with the link to CREATE FUNCTION seems > sufficient to notify and direct people to the needed description for this. After explaining the usage in short, may be can provide links to all other statements where it can be used, but I think syntax <SET .. FROM CURRENT> should be there with SET command's other syntax. With Regards, Amit Kapila. EnterpriseDB: http://www.enterprisedb.com
Amit Kapila-2 wrote > On Tue, Oct 1, 2013 at 10:25 AM, David Johnston < > polobo@ > > wrote: >> Amit Kapila-2 wrote >>> While reading documentation for SET command, I observed that FROM >>> CURRENT syntax and its description is missing from SET command's >>> syntax page (http://www.postgresql.org/docs/devel/static/sql-set.html). >>> >>> Do you think that documentation should be updated for the same or is >>> there any reason why it is not documented? >> >> It is documented as part of "CREATE FUNCTION" since its use is only valid >> in >> that context. > > Not only as part of "CREATE FUNCTION", but as part of "ALTER > DATABASE", "ALTER ROLE", "ALTER FUNCTION" syntax as well. In all these > places other syntax of "SET" is also used and described. > I think you are right that syntax > <SET .. FROM CURRENT> > is mainly used > in context with few other SQL statements, but as it is part of SET > command, so isn't it better to mention the syntax on SET page and may > be explain a bit about its usage? > >> The paragraph with the link to CREATE FUNCTION seems >> sufficient to notify and direct people to the needed description for >> this. > > After explaining the usage in short, may be can provide links to > all other statements where it can be used, but I think syntax > <SET .. > FROM CURRENT> > should be there with SET command's other syntax. FROM CURRENT is only valid as part of the SET sub-command attached to CREATE FUNCTION. Yes, a number of SQL commands take a sub-command called SET. These are not the same as the Top-level SQL SET command and have their own rules and syntax defined on the parent command's page. They share a key word to make the grammar and usage saner but these are semantically different statements. A paragraph cross-referencing where SET sub-commands exist has merit but since the main SET command does not accept FROM CURRENT it (FC) should not be included in its page directly. If you want to put forth an actual documentation change and get a concrete opinion then by all means. If you want someone else to do it I'm detailing why that is unlikely to happen. The link to section 18.1 from the SET command documentation covers most of the other relevant info about how to go about configuring the system. The SQL command reference is generally a much more narrow scope focusing on the syntax of the specific command listed. The current documentation for SET conforms to this reality. We both know how the settings sub-system works. I don't see many novice questions, though my only exposure is the mailing list, about this kind of thing so the documentation seems effective. Other than supposed completeness are there other reasons you feel a change regarding FROM CURRENT or SETtings in general need modification? David J. -- View this message in context: http://postgresql.1045698.n5.nabble.com/Documentation-for-SET-var-name-FROM-CURRENT-tp5772920p5772958.html Sent from the PostgreSQL - hackers mailing list archive at Nabble.com.
On Tue, Oct 1, 2013 at 6:27 PM, David Johnston <polobo@yahoo.com> wrote: > Amit Kapila-2 wrote >> On Tue, Oct 1, 2013 at 10:25 AM, David Johnston < > >> polobo@ > >> > wrote: >>> Amit Kapila-2 wrote >>>> While reading documentation for SET command, I observed that FROM >>>> CURRENT syntax and its description is missing from SET command's >>>> syntax page (http://www.postgresql.org/docs/devel/static/sql-set.html). >>>> >>>> Do you think that documentation should be updated for the same or is >>>> there any reason why it is not documented? >>> >>> It is documented as part of "CREATE FUNCTION" since its use is only valid >>> in >>> that context. >> >> Not only as part of "CREATE FUNCTION", but as part of "ALTER >> DATABASE", "ALTER ROLE", "ALTER FUNCTION" syntax as well. In all these >> places other syntax of "SET" is also used and described. >> I think you are right that syntax >> <SET .. FROM CURRENT> >> is mainly used >> in context with few other SQL statements, but as it is part of SET >> command, so isn't it better to mention the syntax on SET page and may >> be explain a bit about its usage? >> >>> The paragraph with the link to CREATE FUNCTION seems >>> sufficient to notify and direct people to the needed description for >>> this. >> >> After explaining the usage in short, may be can provide links to >> all other statements where it can be used, but I think syntax >> <SET .. >> FROM CURRENT> >> should be there with SET command's other syntax. > > FROM CURRENT is only valid as part of the SET sub-command attached to CREATE > FUNCTION. > > Yes, a number of SQL commands take a sub-command called SET. These are not > the same as the Top-level SQL SET command and have their own rules and > syntax defined on the parent command's page. They share a key word to make > the grammar and usage saner but these are semantically different statements. > > A paragraph cross-referencing where SET sub-commands exist has merit but > since the main SET command does not accept FROM CURRENT it (FC) should not > be included in its page directly. Do you mean to say that SET <var_name> FROM CURRENT doesn't work, so we don't need on main page? With Regards, Amit Kapila. EnterpriseDB: http://www.enterprisedb.com
David Johnston wrote > A paragraph cross-referencing where SET sub-commands exist has merit but > since the main SET command does not accept FROM CURRENT it (FC) should not > be included in its page directly. It is strange that this actually does work - at least in 9.0 - given that SET ... FROM CURRENT does not seem to have any usage outside of its interaction as part of the CREATE FUNCTION command. Is there some use-case I am not seeing? Since the command works I would agree that it should be provided in the syntax section for "SET" and that a comment be added that says generally that its presence is an historical artifact and has no real use as part of the top-level command. Its intended use is in conjunction with the CREATE FUNCTION command. Alternative wordings to describe uses I am not seeing are good too. David J. -- View this message in context: http://postgresql.1045698.n5.nabble.com/Documentation-for-SET-var-name-FROM-CURRENT-tp5772920p5772977.html Sent from the PostgreSQL - hackers mailing list archive at Nabble.com.
Amit Kapila escribió: > While reading documentation for SET command, I observed that FROM > CURRENT syntax and its description is missing from SET command's > syntax page (http://www.postgresql.org/docs/devel/static/sql-set.html). > > Do you think that documentation should be updated for the same or is > there any reason why it is not documented? Did you look at the commit message that introduced it? commit e7889b83b7059e776f0a3d76bbbdd98687f4592c Author: Tom Lane <tgl@sss.pgh.pa.us> Date: Mon Sep 3 18:46:30 2007 +0000 Support SET FROM CURRENT in CREATE/ALTER FUNCTION, ALTER DATABASE, ALTER ROLE. (Actually, it works as a plain statementtoo, but I didn't document that because it seems a bit useless.) Unify VariableResetStmt with VariableSetStmt,and clean up some ancient cruft in the representation of same. -- Álvaro Herrera http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Training & Services
On Tue, Oct 1, 2013 at 9:01 PM, Alvaro Herrera <alvherre@2ndquadrant.com> wrote: > Amit Kapila escribió: >> While reading documentation for SET command, I observed that FROM >> CURRENT syntax and its description is missing from SET command's >> syntax page (http://www.postgresql.org/docs/devel/static/sql-set.html). >> >> Do you think that documentation should be updated for the same or is >> there any reason why it is not documented? > > Did you look at the commit message that introduced it? No, I just noticed while reading documentation that although syntax SET var_name FROM CURRENT works, but the documentation didn't have it. Commit meesage below explains why it is not there,but I think as it works, it might be better to mention in some form (as described by David in previous mail or some other variant). > commit e7889b83b7059e776f0a3d76bbbdd98687f4592c > Author: Tom Lane <tgl@sss.pgh.pa.us> > Date: Mon Sep 3 18:46:30 2007 +0000 > > Support SET FROM CURRENT in CREATE/ALTER FUNCTION, ALTER DATABASE, ALTER ROLE. > (Actually, it works as a plain statement too, but I didn't document that > because it seems a bit useless.) Unify VariableResetStmt with > VariableSetStmt, and clean up some ancient cruft in the representation of > same. Thanks for pointing at right location. With Regards, Amit Kapila. EnterpriseDB: http://www.enterprisedb.com