docs: improve description of how to handle multiple databases

This is a redesign of the intro to the managing databases chapter.

Discussion: https://postgr.es/m/159586122762.680.1361378513036616007@wrigleys.postgresql.org

Author: David G. Johnston

Backpatch-through: 9.5

diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index 01453e6dae72e1577fc3d0b218c59616f2fd55d2..74055a4706557ff3c6f33b7b116d5a28b58371b4 100644 (file)
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -33,21 +33,41 @@
   </para>
 
   <para>
-   When connecting to the database server, a client must specify in
-   its connection request the name of the database it wants to connect
-   to. It is not possible to access more than one database per
-   connection. However, an application is not restricted in the number of
-   connections it opens to the same or other databases.  Databases are
-   physically separated and access control is managed at the
-   connection level.  If one <productname>PostgreSQL</productname> server
-   instance is to house projects or users that should be separate and
-   for the most part unaware of each other, it is therefore
-   recommended to put them into separate databases.  If the projects
-   or users are interrelated and should be able to use each other's
-   resources, they should be put in the same database but possibly
-   into separate schemas.  Schemas are a purely logical structure and who can
-   access what is managed by the privilege system.  More information about
-   managing schemas is in <xref linkend="ddl-schemas"/>.
+   When connecting to the database server, a client must specify the
+   database name in its connection request.
+   It is not possible to access more than one database per
+   connection. However, clients can open multiple connections to
+   the same database, or different databases.
+   Database-level security has two components: access control
+   (see <xref linkend="auth-pg-hba-conf"/>), managed at the
+   connection level, and authorization control
+   (see <xref linkend="ddl-priv"/>), managed via the grant system.
+   Foreign data wrappers (see <xref linkend="postgres-fdw"/>)
+   allow for objects within one database to act as proxies for objects in
+   other database or clusters.
+   The older dblink module (see <xref linkend="dblink"/>) provides a similar capability.
+   By default, all users can connect to all databases using all connection methods.
+  </para>
+
+  <para>
+   If one <productname>PostgreSQL</productname> server cluster is planned to contain
+   unrelated projects or users that should be, for the most part, unaware
+   of each other, it is recommended to put them into separate databases and
+   adjust authorizations and access controls accordingly.
+   If the projects or users are interrelated, and thus should be able to use
+   each other's resources, they should be put in the same database but probably
+   into separate schemas;  this provides a modular structure with namespace
+   isolation and authorization control.
+   More information about managing schemas is in <xref linkend="ddl-schemas"/>.
+  </para>
+
+  <para>
+   While multiple databases can be created within a single cluster, it is advised
+   to consider carefully whether the benefits outweigh the risks and limitations.
+   In particular, the impact that having a shared WAL (see <xref linkend="wal"/>)
+   has on backup and recovery options. While individual databases in the cluster
+   are isolated when considered from the user's perspective, they are closely bound
+   from the database administrator's point-of-view.
   </para>
 
   <para>