Thread: Reserved word "date" in tutorial example
doc/src/sgml/query.sgml includes a tutorial example with this definition: CREATE TABLE weather ( ... date date ); The fact that "date" is used for both the column name and the type is highlighted by two later comments: (Yes, the column of type date is also named date. This might be convenient or confusing--you choose.) type names are not key words in the syntax, except where required to support special cases in the SQL standard. But as a documentation comment submitted recently points out, "date" *is* a reserved word in the SQL spec: http://www.postgresql.org/docs/current/interactive/sql-keywords-appendix.html , just not in PostgreSQL. That makes using it as a column name in an example an odd choice for a tutorial. The example is using the ambiguity to point out where the line between what is and isn't legal is at, and maybe that's a feature instead of a bug. There are a few approaches that could improve on this: -Keep all of that, but expand the description to link to "SQL Key Words"--right now "SQL standard" doesn't go to that section--and say this might be a reserved word in other SQL implementations. This is the smallest useful improvement. -Change the name of the column and remove the two related descriptions. This will lose the lesson about where the parser's line is at. -Do both: move this example of parser trivia somewhere else, but remove it from the tutorial material by using a non-reserved column name there. -- Greg Smith 2ndQuadrant US greg@2ndQuadrant.com Baltimore, MD PostgreSQL Training, Services, and 24x7 Support www.2ndQuadrant.com
On Tue, May 21, 2013 at 10:19:45AM -0400, Greg Smith wrote: > doc/src/sgml/query.sgml includes a tutorial example with this definition: > > CREATE TABLE weather ( > ... > date date > ); > > The fact that "date" is used for both the column name and the type > is highlighted by two later comments: > > (Yes, the column of type date is also named date. This might be > convenient or confusing--you choose.) > > type names are not key words in the syntax, except where required > to support special cases in the SQL standard. > > But as a documentation comment submitted recently points out, "date" > *is* a reserved word in the SQL spec: http://www.postgresql.org/docs/current/interactive/sql-keywords-appendix.html > , just not in PostgreSQL. That makes using it as a column name in > an example an odd choice for a tutorial. The example is using the > ambiguity to point out where the line between what is and isn't > legal is at, and maybe that's a feature instead of a bug. > > There are a few approaches that could improve on this: > > -Keep all of that, but expand the description to link to "SQL Key > Words"--right now "SQL standard" doesn't go to that section--and say > this might be a reserved word in other SQL implementations. This is > the smallest useful improvement. > > -Change the name of the column and remove the two related > descriptions. This will lose the lesson about where the parser's > line is at. > > -Do both: move this example of parser trivia somewhere else, but > remove it from the tutorial material by using a non-reserved column > name there. I reviewed this report and I can't see adding details to a tutorial about the fact that other databases might use "date" as a reserved word. I also can't see that renaming the field really add much. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + Everyone has their own god. +