Documentation: 21.5. Default Roles
Locked
123
123
Documentation: 21.5. Default Roles
 
|
Re: Documentation: 21.5. Default Roles
|
|
On Fri, Dec 27, 2019 at 05:44:10AM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/12/default-roles.html > Description: > > The title is wrong. The roles are not defaults; they are predefined and > privileged. The title suggests that a user should expect to be assigned > these roles. "21.5 Sub-Administrator Roles" would be accurate--improving > clarity over all and removing any need to explain why postgres is not in > this list of roles. > includes your ideas. -- Bruce Momjian <[hidden email]> http://momjian.us EnterpriseDB http://enterprisedb.com + As you are, so once was I. As I am, so you will be. + + Ancient Roman grave inscription + |
roles.diff (3K)
Re: Documentation: 21.5. Default Roles
|
|
In reply to this post by apt.postgresql.org Repository Update
Greetings,
* PG Doc comments form ([hidden email]) wrote: > The title is wrong. The roles are not defaults; they are predefined and > privileged. The title suggests that a user should expect to be assigned > these roles. "21.5 Sub-Administrator Roles" would be accurate--improving > clarity over all and removing any need to explain why postgres is not in > this list of roles. "postgres" isn't in the list because there is no default "postgres" role. There is a role created that's a superuser role that's given the same name as the user who is running 'initdb', but you can change that if you want. The roles that are listed are, indeed, the default roles that the PG system comes with- and no others. > PostgreSQL provides predefined roles which allow access to various actions > and information otherwise reserved to superusers. Oracle uses 'predefined' as the term, while SQL server talks about "Server-Level" and "Database-Level" roles. We don't have database-level roles yet but it seems entirely reasonable to me that we'd want something like that in the future (eg: a role that's able to read all of the data from a given database), so I'd be more inclined to go with the SQL server terminology here, if we're going to make any change. > Though a note of the old title could be helpful to some searchers. And that we've had them around for a number of years now is what makes me hesistate to make a change unless it's very clearly a good improvement and I'm not entirely sure that this is one. If you'd really like to have fun though, you might check out https://www.postgresql.org/docs/current/user-manag.html which talks about "Database Roles" even though what we have are actually Cluster roles. Maybe we should just remove "Database" from that whole section and just talk about "Roles"... (happened on this while reviewing what google returned for various searches while thinking about this change). Thanks, Stephen |
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Greetings,
* Bruce Momjian ([hidden email]) wrote: > On Tue, Jan 7, 2020 at 11:46:31AM +0100, Laurenz Albe wrote: > > On Fri, 2019-12-27 at 12:16 -0500, Bruce Momjian wrote: > > > On Fri, Dec 27, 2019 at 05:44:10AM +0000, PG Doc comments form wrote: > > > > The following documentation comment has been logged on the website: > > > > > > > > Page: https://www.postgresql.org/docs/12/default-roles.html > > > > Description: > > > > > > > > The title is wrong. The roles are not defaults; they are predefined and > > > > privileged. The title suggests that a user should expect to be assigned > > > > these roles. "21.5 Sub-Administrator Roles" would be accurate--improving > > > > clarity over all and removing any need to explain why postgres is not in > > > > this list of roles. > > > > > > > > > > Good points. I have developed the attached documentation patch which > > > includes your ideas. > > > > +1 > > > > I think that "predefined role" is better than "default role". > > Thanks, patch applied through 9.6. for starters, on a misunderstanding and further wasn't a particularly good idea anyway. I'm not happy that it was committed, and to have been back-patched strikes me as even worse. What about existing links to things like: https://www.postgresql.org/docs/9.6/default-roles.html which will now be broken, like from here?: https://paquier.xyz/postgresql-2/postgres-11-new-system-roles/ Or that the documentation wasn't properly updated to reflect this change as a simple "git grep 'default role'" would have shown? There's at least 5 references still to 'default role' in the documentation after this commit. Not to mention that, with this patch, we now have confusion between things like 'DEFAULT_ROLE_WRITE_SERVER_FILES' in the code vs. the documentation. In short, I don't agree with this change, which strikes me as looking largely like it's trying to make PG look more like Oracle than anything else, but if we're going to move in this direction we should only be doing so in master and we should be much more careful making sure that the documentation, at least, is updated and consistent and that appropriate comments are made to the code to explain that DEFAULT_ROLE in the code is referring to "predefined roles" (or we should change the code, though I can understand if there's argument that doing so would create unnecessary back-patching hazards.. though there isn't all *that* much code, so I could go either way on that myself). Thanks, Stephen |
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
On 2/3/20 3:42 PM, Bruce Momjian wrote:
> On Thu, Jan 23, 2020 at 07:12:08PM -0500, R Ransbottom wrote: >> On Mon, Jan 20, 2020 at 12:23:48PM +0900, Ian Barwick wrote: >>> On 2020/01/19 12:56, R Ransbottom wrote: >> >>>> I would hope to find correct documentation somewhere--that somewhere >> >>> Indeed, however it's important that the PostgreSQL documentation remains >>> stable for released versions. >> >>> As-is, the current patch set would result in the term "default role(s)" >>> disappearing from the documentation in the next minor release, which is >>> bound to cause confusion for anyone searching the documentation for the >>> term they're familiar with (unless they happen to be reading this thread >>> or following the git commit log). Cue cries of "OMG Postgres removed a >>> feature in a minor release!!!?!!". >> >>> And as Stephen mentions, it will break a lot of secondary documentation - >>> not just blogs but things like internal training materials etc. >> >>> If this change is made (which I'm personally not against), then it should be >>> only from PostgreSQL 13. For 9.6 ~ 12, IMHO it would be better to tweak the >>> existing documentation to somehow mention that "default roles" should be >>> thought of as "prefined roles", and note they will be called this from Pg13. >> >> Ian, agreed modulo 13. >> >> The current section(s) could forward readers to a revised section. The >> DEFAULT_ROLE_* stuff could carry two names to allow a comprehensive fix >> in 12.X. That could allow the deprecation and misinformation to end one >> EoL sooner. > > With minor releases coming next week, and no movement on doing web > redirects, and no clarity on what this is missing even in master, I will > revert this patch in all branches soon. I think everyone agrees the new > documentation title is better, but we don't want to break things or add > inconsistency to do it. So, if there was something done to redirect people from specific deprecated documentation pages historically, it was before my time. Most of the redirects have been as general purposes ones (e.g. /docs/12), the rules we put in for getting rid of "static", and the release notes, which still receives some negative feedback towards it for different reasons (though I think overall the effort was well-received). Anyway, if we had a redirect in place, I'd want us to do it well. I don't know if it's possible...but if we were able to make a change in the doc source to say "this page is now this page" either as a standalone page, or generated a HTML page that automatically redirects, that may solve the issue. Or if we can have a "ghost page" available with the old link, perhaps we can put something into pgweb to automatically redirect to the new page. Other than that, the only quick solution I see is to hardcode it, which I'm not a fan of. So from a pgweb standpoint, the safe thing would be to do nothing with the URL. If you could keep the URL but change the page title, perhaps that would suffice? Jonathan |
Re: Documentation: 21.5. Default Roles
|
|
Re: Documentation: 21.5. Default Roles
|
|
| Free forum by Nabble | Edit this page |