Subject: Re: generate documentation keywords table automatically
To: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>,
 Tom Lane <tgl@sss.pgh.pa.us>
Cc: pgsql-hackers <pgsql-hackers@postgresql.org>
References: <07daeadd-8c82-0d95-5e19-e350502cb749@2ndquadrant.com>
 <21977.1556378722@sss.pgh.pa.us>
 <fd3df804-bf09-2b08-264b-c4985d25ded1@2ndquadrant.com>
From: Chapman Flack <chap@anastigmatix.net>
Message-ID: <f9bf4ea8-b6ea-e61e-1f76-94c7dc5738c2@anastigmatix.net>
Date: Mon, 29 Apr 2019 15:19:02 -0400
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101
 Thunderbird/60.5.1
MIME-Version: 1.0
In-Reply-To: <fd3df804-bf09-2b08-264b-c4985d25ded1@2ndquadrant.com>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 4/29/19 2:45 PM, Peter Eisentraut wrote:
>> A policy issue, independent of this mechanism, is how many different
>> SQL spec versions we want to show in the table.
> 
> We had previously established that we want to show 92 and the latest
> two.  I don't propose to change that.

An annoying API requirement imposed by the JDBC spec applies to its
method DatabaseMetaData.getSQLKeywords():

It is required to return a list of the keywords supported by the DBMS
that are NOT also SQL:2003 keywords. [1]

Why? I have no idea. Were the JDBC spec authors afraid of infringing
ISO copyright if they specified a method that just returns all the
keywords?

So instead they implicitly require every JDBC developer to know just
what all the SQL:2003 keywords are, to make any practical use of the
JDBC method that returns only the keywords that aren't those.

To make it even goofier, the requirement in the JDBC spec has changed
(once, that I know of). It has been /all the keywords not in SQL:2003/
since JDBC 4 / Java SE 6 [2], but before that, it (the same method!)
was spec'd to return /all the keywords not in SQL92/. [3]

So the ideal JDBC developer will know (a) exactly what keywords are
SQL92, (b) exactly what keywords are SQL:2003, and (c) which JDBC
version the driver in use is implementing (though, mercifully, drivers
from pre-4.0 should be rare by now).

If the reorganization happening in this thread were to make possible
run-time-enumerable keyword lists that could be filtered for SQL92ness
or SQL:2003ness, that might relieve an implementation headache that,
at present, both PgJDBC and PL/Java have to deal with.

Regards,
-Chap


[1]
https://docs.oracle.com/en/java/javase/12/docs/api/java.sql/java/sql/DatabaseMetaData.html#getSQLKeywords()

[2]
https://docs.oracle.com/javase/6/docs/api/index.html?overview-summary.html

[3]
https://docs.oracle.com/javase/1.5.0/docs/api/index.html?overview-summary.html