Subject: Documentation: 21.5. Default Roles

From: PG Doc comments form <[email-masked]>
Date: Fri, 27 Dec 2019 05:44:10 +0000

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.

THE EXISTING 1st Paragraph:

PostgreSQL provides a set of default roles which provide access to certain,
commonly needed, privileged capabilities and information. Administrators can
GRANT these roles to users and/or other roles in their environment,
providing those users with access to the specified capabilities and
information.

A possible replacement:

PostgreSQL provides predefined roles which allow access to various actions
and information  otherwise reserved to superusers.
 Administrators can GRANT these roles like any other role,  but these roles
are also special for allowing abilities not  defined by any standard. 

Additionally:  "commonly"  above is confusing because the "administrative" 
context has not been introduced.

In the paragraph  following the table, the 2nd sentence starts:

They grant a set of common privileges allowing the role to read various
useful configuration settings,

is better:

They grant a set of privileges allowing the role to read various
configuration settings,

"Common" and "useful"  are just noise at best.

 Everywhere in the section "default roles"  should be "predefined roles".   
Though  a note of the old title could  be helpful to some searchers.

Thank you.

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 27 Dec 2019 12:16:54 -0500

> clarity over all  and removing any need to explain why postgres is not in

Good points.  I have developed the attached documentation patch which
includes your ideas.

-- 
  Bruce Momjian  <[email-masked]>        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 +
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index dcb58115af..136778cb8a 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -277,7 +277,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
    existence of a session and its general properties such as its sessions user
    and database are visible to all users.  Superusers and members of the
    built-in role <literal>pg_read_all_stats</literal> (see also <xref
-   linkend="default-roles"/>) can see all the information about all sessions.
+   linkend="predefined-roles"/>) can see all the information about all sessions.
   </para>
 
   <table id="monitoring-stats-dynamic-views-table">
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 66f162703d..4432ee266b 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -483,30 +483,30 @@ DROP ROLE doomed_role;
   </para>
  </sect1>
 
- <sect1 id="default-roles">
-  <title>Default Roles</title>
+ <sect1 id="predefined-roles">
+  <title>Predefined Roles</title>
 
-  <indexterm zone="default-roles">
+  <indexterm zone="predefined-roles">
    <primary>role</primary>
   </indexterm>
 
   <para>
-   <productname>PostgreSQL</productname> provides a set of default roles
-   which provide access to certain, commonly needed, privileged capabilities
-   and information.  Administrators can GRANT these roles to users and/or
-   other roles in their environment, providing those users with access to
-   the specified capabilities and information.
+   <productname>PostgreSQL</productname> provides a set of predefined
+   roles which allow access to privileged capabilities and information.
+   Administrators can GRANT these roles to login and non-login roles,
+   providing those roles with access to the specified capabilities and
+   information.
   </para>
 
   <para>
-   The default roles are described in <xref linkend="default-roles-table"/>.
-   Note that the specific permissions for each of the default roles may
+   The predefined roles are described in <xref linkend="predefined-roles-table"/>.
+   Note that the specific permissions for each of the predefined roles may
    change in the future as additional capabilities are added.  Administrators
    should monitor the release notes for changes.
   </para>
 
-   <table tocentry="1" id="default-roles-table">
-    <title>Default Roles</title>
+   <table tocentry="1" id="predefined-roles-table">
+    <title>Predefined Roles</title>
     <tgroup cols="2">
      <thead>
       <row>
@@ -565,8 +565,8 @@ DROP ROLE doomed_role;
   <literal>pg_read_all_stats</literal> and <literal>pg_stat_scan_tables</literal>
   roles are intended to allow administrators to easily configure a role for the
   purpose of monitoring the database server. They grant a set of common privileges
-  allowing the role to read various useful configuration settings, statistics and
-  other system information normally restricted to superusers.
+  allowing the role to read configuration settings, statistics, and other
+  system information normally restricted to superusers.
   </para>
 
   <para>

---

From: Stephen Frost <[email-masked]>
Date: Fri, 27 Dec 2019 12:29:33 -0500

Greetings,

> clarity over all  and removing any need to explain why postgres is not in

"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.

> 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

---

From: Laurenz Albe <[email-masked]>
Date: Tue, 07 Jan 2020 11:46:31 +0100

> Good points.  I have developed the attached documentation patch which

+1

I think that "predefined role" is better than "default role".

Yours,
Laurenz Albe
-- 
Cybertec | https://www.cybertec-postgresql.com

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 14 Jan 2020 13:13:31 -0500

> I think that "predefined role" is better than "default role".

Thanks, patch applied through 9.6.

---

From: Stephen Frost <[email-masked]>
Date: Tue, 14 Jan 2020 14:45:02 -0500

Greetings,

> Thanks, patch applied through 9.6.

Erm, I didn't agree with this and pointed to reasons why it was based,
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

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 14 Jan 2020 22:56:14 -0500

> which will now be broken, like from here?:

I talked to Stephen on the phone and he is going to fix the doc areas I
missed, and add some C comments.  :-)  Thanks.

---

From: R Ransbottom <[email-masked]>
Date: Sat, 18 Jan 2020 22:56:48 -0500

Hi,

> for starters, on a misunderstanding and further wasn't a particularly

I went to the documentation for clarity.  I read a section that was not
pertinent to my issue because it is poorly titled.  These roles
are not defaults in any sense.

> https://paquier.xyz/postgresql-2/postgres-11-new-system-roles/

I would hope to find correct documentation somewhere--that somewhere
should be Postgresql's own documentation.

> things like 'DEFAULT_ROLE_WRITE_SERVER_FILES' in the code vs. the

No doubt, there is more documentation needing fixing.  I am impressed
by the quality of Pg's documentation overall.

> doing so in master and

It is incorrect to suppose that I am trying to "make PG look ... like
Oracle".  I don't know what Oracle looks like; I've only used msql (not
mysql) and Pg.

"Only .. in master" is a future far away.  Less so for you.

Stephen, thank you.
Rob

---

From: Ian Barwick <[email-masked]>
Date: Mon, 20 Jan 2020 12:23:48 +0900

> should be Postgresql's own documentation.

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.

Regards

Ian Barwick

-- 
Ian Barwick                   https://www.2ndQuadrant.com/
  PostgreSQL Development, 24x7 Support, Training & Services

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 20 Jan 2020 11:02:58 -0500

> thought of as "prefined roles", and note they will be called this from Pg13.

Usually when I apply "wording" doc patches to head only, someone
complains that it should be backpatched, so I did that in this case.  If
we want to change that idea, we need to agree on the criteria.

---

From: Simon Riggs <[email-masked]>
Date: Mon, 20 Jan 2020 18:45:16 +0000

> we want to change that idea, we need to agree on the criteria.

True, but it's not a wording patch, you're entirely renaming a feature.

I agree with the change of default to predefined, but it shouldn't be
backpatched.

There should be a comment in there that it was previously known as "default
roles", with indexed terms for both.

-- 
Simon Riggs                http://www.2ndQuadrant.com/
<http://www.2ndquadrant.com/>
PostgreSQL Solutions for the Enterprise

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 20 Jan 2020 17:13:57 -0500

> roles", with indexed terms for both.

Well, I am renaming the documentation label for the feature.  Is that
different than wording?  I guess I can see that.  If everyone agrees I
can revert the backpatch, but I don't want to do that if other people
are going to say this should be backpatched.

---

From: Laurenz Albe <[email-masked]>
Date: Tue, 21 Jan 2020 10:06:43 +0100

> are going to say this should be backpatched.

I for one think that it should be backpatched, as long as the
old link keeps working.

Yours,
Laurenz Albe

---

From: Bruce Momjian <[email-masked]>
Date: Tue, 21 Jan 2020 10:09:22 -0500

> I for one think that it should be backpatched, as long as the

I looked at that option.  If the section was a hash reference,
"#section_name", we could just add another hash, but in this case the
section name is part of the file name:

	https://www.postgresql.org/docs/12/default-roles.html

We can make that work in a backward-compatible way by changing the
displayed section title, but not the file name.  I am not sure if that
would confuse people though.  We could also add a redirect at the web
server level, but then you have to start to wonder whether the entire
rename clarification is worth it for back branches.

---

From: Tom Lane <[email-masked]>
Date: Tue, 21 Jan 2020 10:49:21 -0500

> 	https://www.postgresql.org/docs/12/default-roles.html

Yeah, <sect1> IDs propagate into HTML page names.

> would confuse people though.

I think that's a really bad idea.

> We could also add a redirect at the web

Well, this is a question for the www list not here.  It might be a lot
easier for them to support a redirect that works the same across all
branches ... or then again, maybe not.  But we have to have a redirect,
else external links pointing at this page will be broken.

We have done page renames with redirects in the past, if memory serves,
so it's possible.  But I don't know details.

			regards, tom lane

---

From: R Ransbottom <[email-masked]>
Date: Thu, 23 Jan 2020 19:12:08 -0500

> 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.

Thanks all.
Rob

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 3 Feb 2020 15:42:44 -0500

> in 12.X.  That could allow the deprecation and misinformation to end one

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.

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Mon, 3 Feb 2020 15:59:11 -0500

> documentation title is better, but we don't want to break things or add

Sorry, I missed the original comment on the "web redirects"

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

---

From: Alvaro Herrera <[email-masked]>
Date: Mon, 3 Feb 2020 18:25:10 -0300

> if we had a redirect in place, I'd want us to do it well.

I +1 changing the title and +1 having the redirect.  That said, I think
people landing in a page titled "predefined roles" when they're looking
for a page titled "default roles" would be quite confused for a while
and perhaps continue to search for the page they think they're looking
for.  (I know, it has happened to me.)  I suggest we add a very short
paragraph --maybe a <note>-- to the effect that feature-X used to be
called feature-Y, immediately following the section title.

-- 
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

---

From: Magnus Hagander <[email-masked]>
Date: Tue, 4 Feb 2020 09:34:37 +0100

> Sorry, I missed the original comment on the "web redirects"

Same here. It was buried a little too deep in an existing therad.

> if we had a redirect in place, I'd want us to do it well.

We have something close to it in commit
496416ceda9c1015d9e7a6ef4b4fb18dae8a8d4e. But that doesn't actually
generate redirects when requests are coming in from the outside -- it
just makes sure our *internal* links can survive the rename of a file
between branches.

So it may not be exactly what's being looked for here, but it might be
a starting point. Probably the same underlying mapping table could be
used, but I haven't investigated that closely enough to say if it's
doable at this point, just that it's a starting point.

Using this feature to handle the rename of a file *between* major
versions, thus leaving the changes in master, should be safe (as long
as we add an entry to that table in pgweb).

As for back branches, I think we have to say that it's too close to
the minor release to safely have something done in pgweb before then.

-- 
 Magnus Hagander
 Me: https://www.hagander.net/
 Work: https://www.redpill-linpro.com/

---

From: Stephen Frost <[email-masked]>
Date: Tue, 4 Feb 2020 11:23:36 -0500

Greetings,

> called feature-Y, immediately following the section title.

I'm a bit confused as it sounded like having the redirect wouldn't be
easy to do..  I also agree that keeping the URL the same as today but
changing that URL to be talking about 'predefined roles' would be quite
confusing.

Having some kind of landing page with the existing URL that had a link
for people to click on to get to the new URL seems like it would
possibly work.  I'd be happier with having that done in master and
keeping the back-branches as-is, since I don't really like the idea that
we're retroactively renaming a feature in our existing releases.

That said, if we at least have the landing page then at least people
will be less likely to be confused.

Thanks,

Stephen

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Tue, 4 Feb 2020 11:31:19 -0500

> just makes sure our *internal* links can survive the rename of a file

Ah cool, didn't realize we had this feature :)

> doable at this point, just that it's a starting point.

Yeah. It could be as simple as having a flag on it to say it should
redirect if the old file (presumably "file2" in the model) is hit. I'm
saying this without diving into the mechanics of the code.

> the minor release to safely have something done in pgweb before then.

This part I agree on, but let's sync offline to see if there is
something within reason, with a preference to *not* rush if we're
worried about breaking something right before release.

Jonathan

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 6 Feb 2020 00:11:31 -0500

> worried about breaking something right before release.

Folks, is it Thursday.  Can we revert this and return to it when we are
not rushed?  Alternatively, can someone who controls all the moving
parts, like  redirects and Stephen's patch additions take ownership of
this issue, with authority to revert the patch if things are too close?

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Thu, 6 Feb 2020 10:59:09 -0500

> this issue, with authority to revert the patch if things are too close?

Magnus and I briefly discussed what it would take, but the probability
of having the redirects ready on pgweb before the release is
slim-to-none, as we'd like to thoroughly test.

We can start experimenting with it now, and commit a fix after the release.

I don't have the power to revert changes directly to the documentation
in core, so I cannot take ownership of that part. However, I am happy to
own the completion of the redirect feature.

Thanks,

Jonathan

---

From: Stephen Frost <[email-masked]>
Date: Thu, 6 Feb 2020 11:05:04 -0500

Greetings,

> own the completion of the redirect feature.

I can own the core bits, since you've offered to take on the web pieces.
:)

Given the discussion, barring objections, I'll revert the changes
tomorrow and then work with Jonathan and Magnus to try and get the
website redirect stuff working so that we can make this change in a
future release.

Thanks,

Stephen

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 6 Feb 2020 13:01:57 -0500

> website redirect stuff working so that we can make this change in a

OK, thanks everyone.

---

From: Tom Lane <[email-masked]>
Date: Sun, 09 Feb 2020 14:24:05 -0500

> website redirect stuff working so that we can make this change in a

It's Sunday afternoon, and nothing has happened, so I took it on
myself to revert this.

			regards, tom lane

---

From: Stephen Frost <[email-masked]>
Date: Sun, 9 Feb 2020 14:25:59 -0500

Greetings,

> It's Sunday afternoon, and nothing has happened, so I took it on

Ah, thanks, Friday got away from me and it’s been a busy weekend, I had
figured on tonight but glad you took care of it.

Thanks again,

Stephen

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 9 Apr 2020 16:57:16 -0400

> own the completion of the redirect feature.

Jonathan, Stephen, with the minor release done, can we focus on adding
the URL redirect and completing the patch to rename this feature in the
docs?  Thanks.

-- 
  Bruce Momjian  <[email-masked]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Thu, 9 Apr 2020 20:47:56 -0400

> the URL redirect and completing the patch to rename this feature in the

Yes, I have a prototype for this ready, which I had scrambled together
before the release. I am happy to make it committable in the coming days.

Jonathan

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 9 Apr 2020 23:45:23 -0400

> before the release. I am happy to make it committable in the coming days.

Thanks.  Once that is done Stephen can apply my patch with his
additions.

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Fri, 24 Apr 2020 19:37:45 -0400

> Thanks.  Once that is done Stephen can apply my patch with his

Please see attached patch for pgweb that allows for the documentation to
be redirected from a page that is removed to a newer page. The way it works:

- Checks to see if a page is found. If it is, great!
- Now if a page 404s, we first check to see if there is a forwarding
address, i.e. the new page. If it is, we issue a 301 (permanent redirecTt).
- If it's still not found, we abort.

I believe this gives us the desired behavior.

Thoughts on the patch?

Thanks,

Jonathan
From e2120f0a80697d13dc6d951f363d01feb60c9b9d Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" <[email-masked]>
Date: Tue, 11 Feb 2020 14:41:46 -0500
Subject: [PATCH] Introduce documentation redirects for doc pages that are
 renamed

The web documentation used to suffer from a problem that if a
documentation page were renamed in a newer version, any references
pointing to said documentation would be lost. For example, the feature
known as "Default Roles" was renamed to "Privileged Roles" but caused
a change in the URL.

This patch introduces the ability to create a "DocPageRedirect" by
specifying the previous name of the documentation page (e.g.
"default-roles.html") and the new name (e.g. "privileged-roles.html")
such that the continuity is preserved between versions.
---
 pgweb/docs/admin.py                           |  3 ++-
 pgweb/docs/migrations/0004_docpageredirect.py | 24 +++++++++++++++++++
 pgweb/docs/models.py                          | 11 +++++++++
 pgweb/docs/views.py                           | 15 ++++++++++--
 4 files changed, 50 insertions(+), 3 deletions(-)
 create mode 100644 pgweb/docs/migrations/0004_docpageredirect.py

diff --git a/pgweb/docs/admin.py b/pgweb/docs/admin.py
index d2f2590..79f1d12 100644
--- a/pgweb/docs/admin.py
+++ b/pgweb/docs/admin.py
@@ -1,5 +1,6 @@
 from django.contrib import admin
 
-from .models import DocPageAlias
+from .models import DocPageAlias, DocPageRedirect
 
 admin.site.register(DocPageAlias)
+admin.site.register(DocPageRedirect)
diff --git a/pgweb/docs/migrations/0004_docpageredirect.py b/pgweb/docs/migrations/0004_docpageredirect.py
new file mode 100644
index 0000000..d19f959
--- /dev/null
+++ b/pgweb/docs/migrations/0004_docpageredirect.py
@@ -0,0 +1,24 @@
+# Generated by Django 2.2.12 on 2020-04-24 23:16
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('docs', '0003_docs_alias'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='DocPageRedirect',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('redirect_from', models.CharField(max_length=64, unique=True, help_text='Page to redirect from, e.g. "old_page.html"')),
+                ('redirect_to', models.CharField(max_length=64, unique=True, help_text='Page to redirect to, e.g. "new_page.html"')),
+            ],
+            options={
+                'verbose_name_plural': 'Doc page redirects',
+            },
+        ),
+    ]
diff --git a/pgweb/docs/models.py b/pgweb/docs/models.py
index 87afe1c..a4558a6 100644
--- a/pgweb/docs/models.py
+++ b/pgweb/docs/models.py
@@ -33,3 +33,14 @@ class DocPageAlias(models.Model):
     class Meta:
         db_table = 'docsalias'
         verbose_name_plural = 'Doc page aliases'
+
+
+class DocPageRedirect(models.Model):
+    """DocPageRedirect offers the ability to redirect from a page that has been
+    completely removed from the PostgreSQL documentation
+    """
+    redirect_from = models.CharField(max_length=64, null=False, blank=False, unique=True, help_text='Page to redirect from, e.g. "old_page.html"')
+    redirect_to = models.CharField(max_length=64, null=False, blank=False, unique=True, help_text='Page to redirect from, e.g. "new_page.html"')
+
+    class Meta:
+        verbose_name_plural = "Doc page redirects"
diff --git a/pgweb/docs/views.py b/pgweb/docs/views.py
index 0566129..6763795 100644
--- a/pgweb/docs/views.py
+++ b/pgweb/docs/views.py
@@ -16,7 +16,7 @@ from pgweb.util.misc import send_template_mail
 from pgweb.core.models import Version
 from pgweb.util.db import exec_to_dict
 
-from .models import DocPage
+from .models import DocPage, DocPageRedirect
 from .forms import DocCommentForm

@@ -94,7 +94,18 @@ def docpage(request, version, filename):
                 url += "{}/{}".format(release_version, fullname)
             return HttpResponsePermanentRedirect(url)
 
-    page = get_object_or_404(DocPage, version=ver, file=fullname)
+    # try to get the page outright. If it's not found, check to see if it's a
+    # doc alias with a redirect, and if so, redirect to that page
+    try:
+        page = DocPage.objects.get(version=ver, file=fullname)
+    except DocPage.DoesNotExist:
+        # if the page does not exist but there is a special pgae redirect, check
+        # for the existence of that. if that does not exist, then we're really
+        # done and can 404
+        page_redirect = get_object_or_404(DocPageRedirect, redirect_from=fullname)
+        url = "/docs/{}/{}".format(version, page_redirect.redirect_to)
+        return HttpResponsePermanentRedirect(url)
+
     versions = DocPage.objects.extra(
         where=["file=%s OR file IN (SELECT file2 FROM docsalias WHERE file1=%s) OR file IN (SELECT file1 FROM docsalias WHERE file2=%s)"],
         params=[fullname, fullname, fullname],
-- 
2.21.1 (Apple Git-122.3)

---

From: Magnus Hagander <[email-masked]>
Date: Tue, 28 Apr 2020 20:19:06 +0200

> I believe this gives us the desired behavior.

 Looks good to me. Go for it.

//Magnus

---

From: Stephen Frost <[email-masked]>
Date: Tue, 28 Apr 2020 14:20:22 -0400

Greetings,

>  Looks good to me. Go for it.

What's the plan for how to maintain it going forward?  Just email -docs
and ask someone to perform the update whenever a release is going out..?
Or do we have some kind of better process in mind?

Thanks!

Stephen

---

From: Magnus Hagander <[email-masked]>
Date: Tue, 28 Apr 2020 20:25:39 +0200

> Or do we have some kind of better process in mind?
GIven how seldom this happens, I think that's perfectly fine. Same as we
already do with the page aliases.

//Magnus

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Tue, 28 Apr 2020 16:02:25 -0400

On 4/28/20 2:19 PM, Magnus Hagander wrote:
> On Sat, Apr 25, 2020 at 1:38 AM Jonathan S. Katz <[email-masked]
> <mailto:[email-masked]>> wrote:
> 

This is deployed. Ready for the patch in core.

Thanks!

Jonathan

---

From: Peter Eisentraut <[email-masked]>
Date: Wed, 29 Apr 2020 21:08:24 +0200

> Thanks.  Once that is done Stephen can apply my patch with his

I think we should leave the backbranches alone.  The feature shipped 
with the name as it did, and users know it as such.  If we start 
retroactively renaming all functionality when we change our mind, it 
will create complete madness.  New ideas belong into the master branch.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 5 Oct 2020 16:31:12 -0400

> This is deployed. Ready for the patch in core.

OK, Stephen, I believe you have a more comprehensive patch to make this
change.  When can you complete it?  The above email is from April.

  The usefulness of a cup is in its emptiness, Bruce Lee

---

From: Stephen Frost <[email-masked]>
Date: Fri, 23 Oct 2020 17:40:37 -0400

Greetings,

> change.  When can you complete it?  The above email is from April.

Having gone back through this thread (again) to figure out where we are
on this, and chatting with Jonathan about the options that are available
through the web system, and trying to sort out my own feelings on what
makes the most sense here, I'd like to bring up a few points and a
proposal regarding the rename:

- General agreement that 'predefined' is better than 'default'
- Unclear on back-patching:
  Voices in favor: Rob, Laurenz, Bruce
  Voices against: Ian, Simon, Peter, Stephen 

Having understood now a bit better what is possible with the web system,
many thanks to Jonathan for chatting with me about it, I'll try to
explain here what the options are:

- Change the back-branches and use the new feature ("doc page
  redirects") to redirect old links to default-roles to
  predefined-roles.

- Change the feature's name in v14, but create a "doc page alias" to
  allow users viewing v13's "default roles" to see a v14 link which
  would take them to "predefined roles".

I'll note that we've got a number of examples of "doc page aliases"
being used to handle name changes:

	catalog-pg-replication-slots.html <-> view-pg-replication-slots.html
	pgxlogdump.html <-> pgwaldump.html
	app-pgresetxlog.html <-> app-pgresetwal.html
	legalnotice.html <-> LEGALNOTICE.html
	app-pgreceivexlog.html <-> app-pgreceivewal.html

I've also been thinking about the code change impact from this, as I do
think we should have the code and the documentation and general feature
naming be consistent, but that implies changing things like
DEFAULT_ROLE_MONITOR to be PREDEFINED_ROLE_MONITOR, potentially breaking
compilation of extensions that use those #define's (such as even our own
extensions like file_fdw do) in a minor version update, which doesn't
seem terribly nice to do.

Therefore, on the whole, the proposal that I would put out there is:

- Rename everything (code, docs, etc) to 'predefined roles' for v14+
- Update the documentation (only) in back-branches to mention that the
  feature was renamed in v14 to 'predefined roles'
- Use the 'doc page alias' feature to make the documentation page for
  'default roles' on the older versions link to 'predefined roles' in
  the newer versions, and vice-versa

Thoughts?

Thanks,

Stephen

---

From: Bruce Momjian <[email-masked]>
Date: Mon, 26 Oct 2020 12:56:53 -0400

>   the newer versions, and vice-versa

Sure, that works for me.  If it was only docs, backpatch makes more
sense, but once you showed the renaming in those other areas,
master-only makes more sense.  Thanks for working on this.

---

From: Stephen Frost <[email-masked]>
Date: Mon, 23 Nov 2020 12:47:57 -0500

Greetings,

> master-only makes more sense.  Thanks for working on this.

I've written a patch to begin to make this change and sent it into
-hackers for comments, thread is here:

https://postgr.es/m/[email-masked]

Naturally, it won't make sense to make a change to the back branches
until the change has been agreed to and committed for v14.

Thanks,

Stephen

---

From: Stephen Frost <[email-masked]>
Date: Thu, 1 Apr 2021 15:34:42 -0400

Greetings,

> https://postgr.es/m/[email-masked]

Just to wrap this up- this change has now been committed for v14.

Thanks,

Stephen

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Fri, 2 Apr 2021 08:40:54 -0400

> Just to wrap this up- this change has now been committed for v14.

Thanks Stephen! Do we have any additional follow up on the pgweb side?

Thanks,

Jonathan

---

From: Stephen Frost <[email-masked]>
Date: Fri, 2 Apr 2021 09:11:11 -0400

Greetings,

> Thanks Stephen! Do we have any additional follow up on the pgweb side?

Yes and no. :)

Once the next set of minor releases is pushed out, I'll double-check
that everything is working properly (the 'obsolete' pages should start
showing up instead of the redirects, since we'll no longer be going
through the "page not found" code path) and will then go remove the
alias/redirects from the pages that no longer need them.

Thanks!

Stephen

---

From: "Jonathan S. Katz" <[email-masked]>
Date: Fri, 2 Apr 2021 09:12:01 -0400

> alias/redirects from the pages that no longer need them.

Great -- thanks for confirming.

Thanks,

Jonathan