Subject: Documentation tweaks: ALTER USER, statement-based middleware

From: Greg Smith <[email-masked]>
Date: Fri, 29 Apr 2011 23:46:28 -0400

Two small patches attached, based on recent documentation comments 
suggested on the web site.

First alters a few places that ALTER USER is suggested, mainly in the 
context of changing per-user settings.  If you're reading the HTML 
documentation, and you click on ALTER USER, it takes you to a slim page 
that tells you what you really wanted was ALTER ROLE.  That's kind of 
wasteful, and thus the idea to go directly there.  Original doc 
suggestion from Grzegorz Szpetkowski, I found a few more places to tweak 
when assembling the patch.

Wording may be a bit weird in spots though, so I'm not sure this is 
necessarily an improvement in all cases.  Right now the description 
around these says things like "debugging could be enabled for all 
sessions under a given user name by setting this parameter with ALTER 
USER SET".  Making that ALTER ROLE instead saves that page redirect 
shuffle for document readers, but is it as clear to people who may not 
know user==role?  Hard to say.

Second doc patch is more straightforward, and based on an observation by 
James Bruce.  The description of how read/write traffic can be scaled 
with statement-based middleware was so terse that it was hard to 
understand.  His suggested rewording shows he didn't follow the idea it 
was trying to communicate at all.  The updated wording I'm providing is 
more explicit and shouldn't be as confusing.  While in there, I also 
fixed the obsolete mention of Sequoia with the current Continuent 
project name of Tungsten; 
http://joomla.aws.continuent.com/community/lab-projects/sequoia 
documents the name change.

-- 
Greg Smith   2ndQuadrant US    [email-masked]   Baltimore, MD
PostgreSQL Training, Services, and 24x7 Support  www.2ndQuadrant.us

diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml
index 44e1f47..633feff 100644
--- a/doc/src/sgml/client-auth.sgml
+++ b/doc/src/sgml/client-auth.sgml
@@ -786,7 +786,7 @@ omicron         bryanh                  guest1
     each database user is stored in the <literal>pg_authid</> system
     catalog. Passwords can be managed with the SQL commands
     <xref linkend="sql-createuser"> and
-    <xref linkend="sql-alteruser">,
+    <xref linkend="sql-alterrole">,
     e.g., <userinput>CREATE USER foo WITH PASSWORD 'secret'</userinput>.
     If no password has been set up for a user, the stored password
     is null and password authentication will always fail for that user.
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 1b8e5a5..7c91a09 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -135,7 +135,7 @@ env PGOPTIONS='-c geqo=off' psql
     Furthermore, it is possible to assign a set of parameter settings to
     a user or a database.  Whenever a session is started, the default
     settings for the user and database involved are loaded.  The
-    commands <xref linkend="sql-alteruser">
+    commands <xref linkend="sql-alterrole">
     and <xref linkend="sql-alterdatabase">,
     respectively, are used to configure these settings.  Per-database
     settings override anything received from the
@@ -702,7 +702,7 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
         When a password is specified in <xref
         linkend="sql-createuser"> or
-        <xref linkend="sql-alteruser">
+        <xref linkend="sql-alterrole">
         without writing either <literal>ENCRYPTED</> or
         <literal>UNENCRYPTED</>, this parameter determines whether the
         password is to be encrypted. The default is <literal>on</>
@@ -4959,7 +4959,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
         libraries to be loaded into specific sessions without an explicit
         <command>LOAD</> command being given.  For example, debugging could
         be enabled for all sessions under a given user name by setting
-        this parameter with <command>ALTER USER SET</>.
+        this parameter with <command>ALTER ROLE SET</>.
        </para>
 
        <para>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index f53702c..6e9e42c 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -6168,7 +6168,7 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
   <para>
    The following environment variables can be used to specify default
    behavior for each <productname>PostgreSQL</productname> session.  (See
-   also the <xref linkend="sql-alteruser">
+   also the <xref linkend="sql-alterrole">
    and <xref linkend="sql-alterdatabase">
    commands for ways to set default behavior on a per-user or per-database
    basis.)
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index 74684f7..cfb8a2b 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -188,9 +188,10 @@ protocol to make nodes agree on a serializable transactional order.
     <para>
      With statement-based replication middleware, a program intercepts
      every SQL query and sends it to one or all servers.  Each server
-     operates independently.  Read-write queries are sent to all servers,
-     while read-only queries can be sent to just one server, allowing
-     the read workload to be distributed.
+     operates independently.  Read-write queries must be sent to all servers,
+     so that every server receives any changes.  But read-only queries can be
+     sent to just one server, allowing the read workload to be distributed
+     among them.
     </para>
 
     <para>
@@ -209,8 +210,8 @@ protocol to make nodes agree on a serializable transactional order.
      transactions either commit or abort on all servers, perhaps
      using two-phase commit (<xref linkend="sql-prepare-transaction">
      and <xref linkend="sql-commit-prepared">.
-     <productname>Pgpool-II</> and <productname>Sequoia</> are examples of
-     this type of replication.
+     <productname>Pgpool-II</> and <productname>Continuent Tungsten</>
+     are examples of this type of replication.
     </para>
    </listitem>
   </varlistentry>

---

From: Alvaro Herrera <[email-masked]>
Date: Mon, 02 May 2011 13:47:01 -0300

> when assembling the patch.

I applied this bit.  I am unsure about the CREATE USER mentions that
appear just before each ALTER USER spot that got modified; should those
be updated to CREATE ROLE as well?  The only difference is that CREATE
USER adds the LOGIN privileges automatically, but the CREATE USER as as
skinny as ALTER USER.  Thoughts?

-- 
Álvaro Herrera <[email-masked]>
The PostgreSQL Company - Command Prompt, Inc.
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

---

From: Alvaro Herrera <[email-masked]>
Date: Tue, 03 May 2011 11:38:12 -0300

> documents the name change.

Applied, thanks