Re: BUG #13775: CREATE RULE documentation seems to be wrong under ON SELECT TO <table> DO INSTEAD SELECT

On Fri, Nov 13, 2015 at 4:23 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> needthistool(at)gmail(dot)com writes:
> >> From the docs:
>
> > "Thus, an ON SELECT rule **effectively** turns the table into a view,
> whose
> > visible contents are the rows returned by the rule's SELECT command
> **rather
> > than whatever had been stored in the table** (if anything). It is
> > **considered better style** to write a CREATE VIEW command than to
> create a
> > real table and define an ON SELECT rule for it." {'**' emphases added}
>
> I don't see anything particularly wrong with those statements...
>
> > It does
> > not appear possible to shadow a table with an alternate selection-clause
> > which makes the real contents of the table appear different in some way
> (for
> > instance, adding a default sorting or if one wasn't specified or such).
>
> I don't see anything in the docs that suggests that that's supported,
> either.
>
> The only reason creating an ON SELECT rule is still supported at all is
> that (1) that used to be how pg_dump dumped views, and (2) that's still
> how pg_dump dumps views in some corner cases involving circular
> dependencies. We could get rid of (2); but in view of the need for
> backwards compatibility with old dump files, it's hard to see when we
> could drop the syntax entirely, so nobody's bothered. In the meantime,
> though, there is no expectation that we'd ever support ON SELECT rules
> that weren't a weird spelling of CREATE VIEW, and I don't see anything
> in the documentation that suggests differently.
>
> regards, tom lane
>

"[T]here is no expectation that we'd ever support ON SELECT rules that
weren't a weird spelling of CREATE VIEW and I don't see anything in the
documentation that suggests differently." I disagree; such an expectation
could easily be taken as an inference by some readers of the relevant
pages; throughout the rest of the documentation, (for example with CREATE
USER versus CREATE ROLE,) it's stated explicitly when one syntax is a
functionally-identical sister-syntax to another, (kept around for legacy
reasons and/or to allow conformance to SQL-specifications). To state "that
particular interpretation of what's written is not the correct one"
indicates that the docs are ambiguous in this instance and should be made
more clear and moreover more consistent with the conventions of the rest of
the documentation, namely in plainly stating why the syntax (still) exists
and what it currently does.

Further, it's misleading that the documentation suggests that it is merely
a frowned-upon choice to use CREATE RULE ... ON SELECT ... DO INSTEAD
SELECT when in fact it is not a choice whatsoever. A justifiable takeaway
from the current phrasing is that VIEWs are semantically easier to
understand and therefore preferred, but somehow different from a DO INSTEAD
SELECT. The actual reality is that there is no such thing as a DO INSTEAD
SELECT rule. I don't see an argument for leaving that as an ambiguity in
the docs, when it is obvious after some experimentation with a server
what's actually happening. Why not save folks the time and state this
explicitly?

Again, it would be helpful for (new) users to be made aware that the CREATE
RULE ... ON SELECT syntax exists primarily for sake of compatibility with
pg-dump and is in essence another way to invoke CREATE VIEW. Although none
of this is currently made explicit, I don't see why it should be left
unstated in official documentation, nevermind that it's been made fairly
clear here.

Respectfully,
- Seldom