From c889c9c90151229baad4af205f42f6b81d7b02f4 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Wed, 25 Sep 2002 21:16:10 +0000
Subject: [PATCH] Enhance the description of user and database management.
Reduce the number of forward references in the admin guide.
---
doc/src/sgml/admin.sgml | 6 +-
doc/src/sgml/filelist.sgml | 3 +-
doc/src/sgml/manage-ag.sgml | 198 +++++++++++++++++++++---------
doc/src/sgml/manage.sgml | 228 -----------------------------------
doc/src/sgml/runtime.sgml | 12 +-
doc/src/sgml/user-manag.sgml | 97 ++++++++++-----
doc/src/sgml/user.sgml | 3 +-
7 files changed, 221 insertions(+), 326 deletions(-)
delete mode 100644 doc/src/sgml/manage.sgml
diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml
index 24a770d3685..75227bf1823 100644
--- a/doc/src/sgml/admin.sgml
+++ b/doc/src/sgml/admin.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.37 2002/06/13 05:15:22 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.38 2002/09/25 21:16:10 petere Exp $
-->
<book id="admin">
@@ -25,10 +25,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.37 2002/06/13 05:15:22
&installation;
&installw;
&runtime;
+ &user-manag;
+ &manage-ag;
&client-auth;
&charset;
- &manage-ag;
- &user-manag;
&maintenance;
&backup;
&monitoring;
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index b520e466adb..cbdd3bf5f18 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.22 2002/08/22 03:17:37 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.23 2002/09/25 21:16:10 petere Exp $ -->
<!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml">
@@ -29,7 +29,6 @@
<!entity func SYSTEM "func.sgml">
<!entity indices SYSTEM "indices.sgml">
<!entity keywords SYSTEM "keywords.sgml">
-<!entity manage SYSTEM "manage.sgml">
<!entity mvcc SYSTEM "mvcc.sgml">
<!entity perform SYSTEM "perform.sgml">
<!entity queries SYSTEM "queries.sgml">
diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index 15ece75a398..e37864f79ee 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.20 2001/11/28 20:49:10 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.21 2002/09/25 21:16:10 petere Exp $
-->
<chapter id="managing-databases">
@@ -8,36 +8,65 @@ $Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.20 2001/11/28 20:49:10 p
<indexterm zone="managing-databases"><primary>database</></>
<para>
- A database is a named collection of SQL objects (<quote>database
- objects</quote>). Generally, every database object (tables, functions,
- etc.) belongs to one and only one database. (But there are a few system
- catalogs, for example <literal>pg_database</>, that belong to a whole
- installation and are accessible from each database within the
- installation.)
- An application that connects
- to the database server specifies 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. (But an application
- is not restricted in the number of connections it opens to the same
- or other databases.)
+ Every instance of a running PostgreSQL server manages one or more
+ databases. Databases are therefore the topmost hierarchical level
+ for organizing SQL objects (<quote>database objects</quote>). This
+ chapter describes the properties of databases, and how to create,
+ manage, and destroy them.
</para>
- <note>
+ <sect1>
+ <title>Overview</title>
+
<para>
- <acronym>SQL</> calls databases <quote>catalogs</>, but there is no
- difference in practice.
+ A database is a named collection of SQL objects (<quote>database
+ objects</quote>). Generally, every database object (tables,
+ functions, etc.) belongs to one and only one database. (But there
+ are a few system catalogs, for example <literal>pg_database</>,
+ that belong to a whole installation and are accessible from each
+ database within the installation.) More accurately, a database is
+ a collection of schemas and the schemas contain the tables,
+ functions, etc. So the full hierarchy is:
+ server-database-schema-table (or something else instead of a
+ table).
</para>
- </note>
- <para>
- In order to create or drop databases, the <productname>PostgreSQL</>
- <application>postmaster</> must be up and running (see <xref
- linkend="postmaster-start">).
- </para>
+ <para>
+ An application that connects to the database server specifies 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. (But an application is not restricted in the number of
+ connections it opens to the same or other databases.) It is
+ possible, however, to access more than one schema from the same
+ connection. Schemas are a purely logical structure and who can
+ access what is managed by the privilege system. Databases are
+ physically separated and access control is managed at the
+ connection level. If one PostgreSQL server instance is to house
+ projects or users that should be separate and for the most part
+ unaware of each other, it is therefore recommendable 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 databases but possibly into separate schemas. More
+ information about managing schemas is in &cite-user;.
+ </para>
+
+ <note>
+ <para>
+ <acronym>SQL</> calls databases <quote>catalogs</>, but there is no
+ difference in practice.
+ </para>
+ </note>
+ </sect1>
<sect1 id="manage-ag-createdb">
<title>Creating a Database</title>
+ <para>
+ In order to create a databases, the <productname>PostgreSQL</>
+ server must be up and running (see <xref
+ linkend="postmaster-start">).
+ </para>
+
<para>
Databases are created with the query language command
<command>CREATE DATABASE</command>:
@@ -56,20 +85,17 @@ CREATE DATABASE <replaceable>name</>
linkend="user-attributes"> for how to grant permission.
</para>
- <formalpara>
- <title>Bootstrapping:</title>
- <para>
- Since you need to be connected to the database server in order to
- execute the <command>CREATE DATABASE</command> command, the
- question remains how the <emphasis>first</> database at any given
- site can be created. The first database is always created by the
- <command>initdb</> command when the data storage area is
- initialized. (See <xref linkend="creating-cluster">.) By convention
- this database is called <literal>template1</>. So
- to create the first <quote>real</> database you can connect to
- <literal>template1</>.
- </para>
- </formalpara>
+ <para>
+ Since you need to be connected to the database server in order to
+ execute the <command>CREATE DATABASE</command> command, the
+ question remains how the <emphasis>first</> database at any given
+ site can be created. The first database is always created by the
+ <command>initdb</> command when the data storage area is
+ initialized. (See <xref linkend="creating-cluster">.) By convention
+ this database is called <literal>template1</>. So to create the
+ first <quote>real</> database you can connect to
+ <literal>template1</>.
+ </para>
<para>
The name <quote>template1</quote> is no accident: When a new
@@ -77,14 +103,14 @@ CREATE DATABASE <replaceable>name</>
This means that any changes you make in <literal>template1</> are
propagated to all subsequently created databases. This implies that
you should not use the template database for real work, but when
- used judiciously this feature can be convenient. More details appear
- below.
+ used judiciously this feature can be convenient. More details
+ appear in <xref linkend="manage-ag-templatedbs">.
</para>
<para>
As an extra convenience, there is also a program that you can
execute from the shell to create new databases,
- <filename>createdb</>.
+ <command>createdb</>.
<synopsis>
createdb <replaceable class="parameter">dbname</replaceable>
@@ -99,8 +125,32 @@ createdb <replaceable class="parameter">dbname</replaceable>
you want.
</para>
- <sect2 id="manage-ag-templatedbs">
- <title>Template Databases</title>
+ <note>
+ <para>
+ <xref linkend="client-authentication"> contains information about
+ how to restrict who can connect to a given database.
+ </para>
+ </note>
+
+ <para>
+ Sometimes you want to create a database for someone else. That
+ user should become the owner of the new database, so he can
+ configure and manage it himself. To achieve that, use one of the
+ following commands:
+<programlisting>
+CREATE DATABASE <replaceable>dbname</> OWNER <replaceable>username</>;
+</programlisting>
+ from the SQL environment, or
+<programlisting>
+createdb -O <replaceable>username</> <replaceable>dbname</>
+</programlisting>
+ You must be a superuser to be allowed to create a database for
+ someone else.
+ </para>
+ </sect1>
+
+ <sect1 id="manage-ag-templatedbs">
+ <title>Template Databases</title>
<para>
<command>CREATE DATABASE</> actually works by copying an existing
@@ -111,7 +161,7 @@ createdb <replaceable class="parameter">dbname</replaceable>
will be copied into subsequently created user databases. This
behavior allows site-local modifications to the standard set of
objects in databases. For example, if you install the procedural
- language <literal>plpgsql</> in <literal>template1</>, it will
+ language <application>PL/pgSQL</> in <literal>template1</>, it will
automatically be available in user databases without any extra action
being taken when those databases are made.
</para>
@@ -132,12 +182,24 @@ createdb <replaceable class="parameter">dbname</replaceable>
additions that may now be present in <literal>template1</>.
</para>
+ <para>
+ To create a database by copying <literal>template0</literal>, use
+<programlisting>
+CREATE DATABASE <replaceable>dbname</> TEMPLATE template0;
+</programlisting>
+ from the SQL environment, or
+<programlisting>
+createdb -T template0 <replaceable>dbname</>
+</programlisting>
+ from the shell.
+ </para>
+
<para>
It is possible to create additional template databases, and indeed
one might copy any database in an installation by specifying its name
as the template for <command>CREATE DATABASE</>. It is important to
understand, however, that this is not (yet) intended as
- a general-purpose <quote>COPY DATABASE</quote> facility. In particular, it is
+ a general-purpose <quote><command>COPY DATABASE</command></quote> facility. In particular, it is
essential that the source database be idle (no data-altering transactions
in progress)
for the duration of the copying operation. <command>CREATE DATABASE</>
@@ -151,7 +213,7 @@ createdb <replaceable class="parameter">dbname</replaceable>
<para>
Two useful flags exist in <literal>pg_database</literal> for each
- database: <literal>datistemplate</literal> and
+ database: the columns <literal>datistemplate</literal> and
<literal>datallowconn</literal>. <literal>datistemplate</literal>
may be set to indicate that a database is intended as a template for
<command>CREATE DATABASE</>. If this flag is set, the database may be
@@ -187,18 +249,47 @@ createdb <replaceable class="parameter">dbname</replaceable>
<literal>template1</> and <literal>template0</> do not have any special
status beyond the fact that the name <literal>template1</> is the default
source database name for <command>CREATE DATABASE</> and the default
- database-to-connect-to for various scripts such as <literal>createdb</>.
+ database-to-connect-to for various programs such as <command>createdb</>.
For example, one could drop <literal>template1</> and recreate it from
<literal>template0</> without any ill effects. This course of action
might be advisable if one has carelessly added a bunch of junk in
<literal>template1</>.
</para>
</note>
+ </sect1>
+
+ <sect1 id="manage-ag-config">
+ <title>Database Configuration</title>
+
+ <para>
+ Recall from <xref linkend="runtime-config"> that the PostgreSQL
+ server provides a large number of run-time configuration variables.
+ You can set database-specific default values for many of these
+ settings.
+ </para>
- </sect2>
+ <para>
+ For example, if for some reason you want to disable the
+ <acronym>GEQO</acronym> optimizer for a given database, you'd
+ ordinarily have to either disable it for all databases or make sure
+ that every connecting client is careful to issue <literal>SET geqo
+ TO off;</literal>. To make this setting the default you can
+ execute the command
+<programlisting>
+ALTER DATABASE mydb SET geqo TO off;
+</programlisting>
+ This will save the setting (but not set it immediately) and in
+ subsequent connections it will appear as though <literal>SET geqo
+ TO off;</literal> had been called right before the session started.
+ Note that users can still alter this setting during the session; it
+ will only be the default. To undo any such setting, use
+ <literal>ALTER DATABASE <replaceable>dbname</> RESET
+ <replaceable>varname</>;</literal>.
+ </para>
+ </sect1>
- <sect2 id="manage-ag-alternate-locs">
- <title>Alternative Locations</title>
+ <sect1 id="manage-ag-alternate-locs">
+ <title>Alternative Locations</title>
<para>
It is possible to create a database in a location other than the
@@ -227,18 +318,14 @@ createdb <replaceable class="parameter">dbname</replaceable>
initialize the data area, and finally restart the server. (See
<xref linkend="postmaster-shutdown"> and <xref
linkend="postmaster-start">.) To set an environment variable, type
- <informalexample>
<programlisting>
PGDATA2=/home/postgres/data
export PGDATA2
</programlisting>
- </informalexample>
in Bourne shells, or
- <informalexample>
<programlisting>
setenv PGDATA2 /home/postgres/data
</programlisting>
- </informalexample>
in <application>csh</> or <application>tcsh</>. You have to make sure that this environment
variable is always defined in the server environment, otherwise
you won't be able to access that database. Therefore you probably
@@ -253,12 +340,11 @@ setenv PGDATA2 /home/postgres/data
already exists and is writable
by the user account that runs the server (see <xref
linkend="postgres-user">). Then from the command line, type
- <informalexample>
<programlisting>
initlocation PGDATA2
</programlisting>
- </informalexample>
- Then you can restart the server.
+ (<emphasis>not</emphasis> <literal>initlocation
+ $PGDATA2</literal>). Then you can restart the server.
</para>
<para>
@@ -290,8 +376,6 @@ gmake CPPFLAGS=-DALLOW_ABSOLUTE_DBPATHS all
</programlisting>
</para>
</note>
-
- </sect2>
</sect1>
<sect1 id="manage-ag-dropdb">
diff --git a/doc/src/sgml/manage.sgml b/doc/src/sgml/manage.sgml
deleted file mode 100644
index 1850b7481ea..00000000000
--- a/doc/src/sgml/manage.sgml
+++ /dev/null
@@ -1,228 +0,0 @@
-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.23 2002/08/13 20:40:43 momjian Exp $
--->
-
- <Chapter Id="manage">
- <Title>Managing a Database</Title>
-
- <comment>
- This section is currently a thinly disguised copy of the
- Tutorial. Needs to be augmented.
- - thomas 1998-01-12
- </comment>
-
- <Para>
- Although the <FirstTerm>site administrator</FirstTerm> is responsible for overall management
- of the <ProductName>PostgreSQL</ProductName> installation, some databases within the
- installation may be managed by another person,
- designated the <FirstTerm>database administrator</FirstTerm>.
- This assignment of responsibilities occurs when a database is created.
- A user may be assigned explicit privileges to create databases and/or to create new users.
- A user assigned both privileges can perform most administrative tasks
- within <ProductName>PostgreSQL</ProductName>, but will
- not by default have the same operating system privileges as the site administrator.
- </Para>
-
- <Para>
- The <citetitle>Administrator's Guide</> covers these topics in
- more detail.
- </Para>
-
- <Sect1 id="db-creation">
- <Title>Database Creation</Title>
-
- <Para>
- Databases are created by the <Command>CREATE DATABASE</Command>
- command issued from within
- <ProductName>PostgreSQL</ProductName>. <Application>createdb</Application>
- is a shell script provided to give the same functionality from the
- Unix command line.
- </Para>
-
- <Para>
- The <ProductName>PostgreSQL</ProductName> backend must be running for either method
- to succeed, and the user issuing the command must be the <ProductName>PostgreSQL</ProductName>
- <FirstTerm>superuser</FirstTerm> or have been assigned database creation privileges by the
- superuser.
- </Para>
-
- <Para>
- To create a new database named <literal>mydb</literal> from the command line, type
-<ProgramListing>
-% createdb mydb
-</ProgramListing>
-
- and to do the same from within <Application>psql</Application> type
-<ProgramListing>
-=> CREATE DATABASE mydb;
-</ProgramListing>
- </Para>
-
- <Para>
- If you do not have the privileges required to create a database, you will see
- the following:
-<ProgramListing>
-ERROR: CREATE DATABASE: Permission denied.
-</ProgramListing>
- </Para>
-
- <Para>
- You automatically become the
- database administrator of the database you just created.
- Database names must have an alphabetic first
- character and are limited to 63 characters in length.
- <ProductName>PostgreSQL</ProductName> allows you to create any number of
- databases at a given site.
- </Para>
-
- <Para>
- The <citetitle>Administrator's Guide</> discusses database creation
- in more detail, including advanced options of the <command>CREATE
- DATABASE</> command.
- </Para>
-
- </Sect1>
-
-<Sect1 id="db-accessing">
-<Title>Accessing a Database</Title>
-
-<Para>
- Once you have constructed a database, you can access it
- by:
-
- <itemizedlist spacing="compact" mark="bullet">
- <listitem>
- <para>
- Running the <productname>PostgreSQL</productname> interactive
- terminal program, called <application>psql</application>, which allows you
- to interactively enter, edit, and execute
- <acronym>SQL</acronym> commands.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Using an existing graphical frontend tool like
- <application>PgAccess</application> or
- <application>ApplixWare</application> (via
- <acronym>ODBC</acronym>) to create and manipulate a database.
- These possibilities are not covered in this tutorial.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Writing a custom application, using one of the several
- available language bindings. These possibilities are discussed
- further in <citetitle>The PostgreSQL Programmer's
- Guide</citetitle>.
- </para>
- </listitem>
- </itemizedlist>
-
-You probably want to start up <Application>psql</Application>,
-to try out the examples in this manual.
- It can be activated for the <Database>mydb</Database>
- database by typing the command:
-<ProgramListing>
-% psql mydb
-</ProgramListing>
-
- You will be greeted with the following message:
-<ProgramListing>
-Welcome to psql &version;, the PostgreSQL interactive terminal.
-
-Type: \copyright for distribution terms
- \h for help with SQL commands
- \? for help on internal slash commands
- \g or terminate with semicolon to execute query
- \q to quit
-
-mydb=>
-</ProgramListing>
-</Para>
-
-<Para>
-This prompt indicates that <command>psql</command> is listening
- to you and that you can type <Acronym>SQL</Acronym> queries into a
- work space maintained by the terminal monitor.
-The <Application>psql</Application> program itself responds to special
-commands that begin
- with the backslash character, <literal>\</literal>. For example, you
- can get help on the syntax of various
- <ProductName>PostgreSQL</ProductName> <Acronym>SQL</Acronym> commands by typing:
-<ProgramListing>
-mydb=> \h
-</ProgramListing>
-
- Once you have finished entering your queries into the
- work space, you can pass the contents of the work space
- to the <ProductName>PostgreSQL</ProductName> server by typing:
-<ProgramListing>
-mydb=> \g
-</ProgramListing>
-
- This tells the server to process the query. If you
- terminate your query with a semicolon, the <literal>\g</literal> is not
- necessary.
-<Application>psql</Application> will automatically process semicolon terminated queries.
- To read queries from a file, say <filename>myFile</filename>, instead of
- entering them interactively, type:
-<ProgramListing>
-mydb=> \i myFile
-</ProgramListing>
-
- To get out of <Application>psql</Application> and return to Unix, type
-<ProgramListing>
-mydb=> \q
-</ProgramListing>
-
- and <Application>psql</Application> will quit and return you to your command
- shell. (For more escape codes, type <Command>\?</Command> at the <command>psql</command>
- prompt.)
- White space (i.e., spaces, tabs and newlines) may be
- used freely in <Acronym>SQL</Acronym> queries. Single-line comments are denoted by
- <literal>--</literal>. Everything after the dashes up to the end of the
- line is ignored. Multiple-line comments, and comments within a line,
- are denoted by <literal>/* ... */</literal>.
-</Para>
-
-</Sect1>
-
-<Sect1 id="db-destroy">
-<Title>Destroying a Database</Title>
-
-<Para>
- If you are the owner of the database
- <Database>mydb</Database>, you can destroy it using the SQL command
-<ProgramListing>
-=> DROP DATABASE mydb;
-</ProgramListing>
- or the Unix shell script
-<ProgramListing>
-% dropdb mydb
-</ProgramListing>
- This action physically removes all of the Unix files
- associated with the database and cannot be undone, so
- this should only be done with a great deal of forethought.
-</Para>
-</Sect1>
-
-</Chapter>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode:sgml
-sgml-omittag:nil
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"./reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:("/usr/lib/sgml/catalog")
-sgml-local-ecat-files:nil
-End:
--->
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 7265896eaba..753d084b355 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.138 2002/09/21 18:32:53 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.139 2002/09/25 21:16:10 petere Exp $
-->
<Chapter Id="runtime">
@@ -57,7 +57,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.138 2002/09/21 18:32:53 pe
database cluster will contain a database named
<literal>template1</literal>. As the name suggests, this will be used
as a template for subsequently created databases; it should not be
- used for actual work.
+ used for actual work. (See <xref linkend="managing-databases"> for information
+ about creating databases.)
</para>
<para>
@@ -120,18 +121,17 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
<para>
However, while the directory contents are secure, the default
- <filename>pg_hba.conf</filename> authentication method of
- <literal>trust</literal> allows any local user to connect to the
+ client authentication setup allows any local user to connect to the
database and even become the database superuser. If you don't trust
other local users, we recommend you use <command>initdb</command>'s
<option>-W</option> or <option>--pwprompt</option> option to assign a
password to the database superuser. After <command>initdb</command>,
- modify <filename>pg_hba.conf</filename> to use <literal>md5</> or
+ modify the <filename>pg_hba.conf</filename> file to use <literal>md5</> or
<literal>password</> instead of <literal>trust</> authentication
<emphasis>before</> you start the server for the first time. (Other,
approaches include using <literal>ident</literal> authentication or
file system permissions to restrict connections. See <xref
- linkend="client-authentication"> for more information.
+ linkend="client-authentication"> for more information.)
</para>
<para>
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 70a4aba94bf..aad8d93100e 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -1,14 +1,23 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.15 2002/09/12 22:05:36 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/user-manag.sgml,v 1.16 2002/09/25 21:16:10 petere Exp $
-->
<chapter id="user-manag">
- <title>Database Users and Permissions</title>
+ <title>Database Users and Privileges</title>
<para>
- Managing database users and their privileges is in concept similar
- to managing the users of a Unix operating system, but the details
- are not identical.
+ Every database cluster contains a set of database users. Those
+ users are separate from the users managed by the operating system on
+ which the server runs. Users own database objects (for example,
+ tables) and can assign privileges on those objects to other users to
+ control who has access to which object.
+ </para>
+
+ <para>
+ This chapter describes how to create and manage users and introduces
+ the privilege system. More information about the various types of
+ database objects and the effects of privileges can be found in
+ &cite-user;.
</para>
<sect1 id="database-users">
@@ -27,19 +36,27 @@ CREATE USER <replaceable>name</replaceable>
<replaceable>name</replaceable> follows the rules for SQL
identifiers: either unadorned without special characters, or
double-quoted. To remove an existing user, use the analogous
- <command>DROP USER</command> command.
+ <command>DROP USER</command> command:
+<synopsis>
+DROP USER <replaceable>name</replaceable>
+</synopsis>
</para>
<para>
- For convenience, the shell scripts <application>createuser</application>
- and <application>dropuser</application> are provided as wrappers around these SQL
- commands.
+ For convenience, the programs <application>createuser</application>
+ and <application>dropuser</application> are provided as wrappers
+ around these SQL commands that can be called from the shell command
+ line:
+<synopsis>
+createuser <replaceable>name</replaceable>
+dropuser <replaceable>name</replaceable>
+</synopsis>
</para>
<para>
In order to bootstrap the database system, a freshly initialized
system always contains one predefined user. This user will have the
- fixed id 1, and by default (unless altered when running
+ fixed ID 1, and by default (unless altered when running
<application>initdb</application>) it will have the same name as
the operating system user that initialized the database
cluster. Customarily, this user will be named
@@ -48,21 +65,34 @@ CREATE USER <replaceable>name</replaceable>
</para>
<para>
- The user name to use for a particular database connection is
- indicated by the client that is initiating the connection request
- in an application-specific fashion. For example, the
- <application>psql</application> program uses the <option>-U</option>
- command line option to indicate the user to connect as. The set of
- database users a given client connection may connect as is
- determined by the client authentication setup, as explained in
+ Exactly one user identity is active for a connection to the
+ database server. The user name to use for a particular database
+ connection is indicated by the client that is initiating the
+ connection request in an application-specific fashion. For example,
+ the <application>psql</application> program uses the
+ <option>-U</option> command line option to indicate the user to
+ connect as. Many applications assume the name of the current
+ operating system user by default (including
+ <application>createuser</> and <application>psql</>). Therefore it
+ is convenient to maintain a naming correspondence between the two
+ user sets.
+ </para>
+
+ <para>
+ The set of database users a given client connection may connect as
+ is determined by the client authentication setup, as explained in
<xref linkend="client-authentication">. (Thus, a client is not
necessarily limited to connect as the user with the same name as
its operating system user, in the same way a person is not
- constrained in its login name by her real name.)
+ constrained in its login name by her real name.) Since the user
+ identity determines the set of privileges available to a connected
+ client, it is important to carefully configure this when setting up
+ a multiuser environment.
</para>
+ </sect1>
- <sect2 id="user-attributes">
- <title>User attributes</title>
+ <sect1 id="user-attributes">
+ <title>User Attributes</title>
<para>
A database user may have a number of attributes that define its
@@ -115,7 +145,23 @@ CREATE USER <replaceable>name</replaceable>
See the reference pages for <command>CREATE USER</command> and
<command>ALTER USER</command> for details.
</para>
- </sect2>
+
+ <para>
+ A user can also set personal defaults for many of the run-time
+ configuration settings described in <xref
+ linkend="runtime-config">. For example, if for some reason you
+ want to disable index scans (hint: not a good idea) anytime you
+ connect, you can use
+<programlisting>
+ALTER USER myname SET enable_indexscan TO off;
+</programlisting>
+ This will save the setting (but not set it immediately) and in
+ subsequent connections it will appear as though <literal>SET geqo
+ TO off;</literal> had been called right before the session started.
+ You can still alter this setting during the session; it will only
+ be the default. To undo any such setting, use <literal>ALTER USER
+ <replaceable>username</> RESET <replaceable>varname</>;</literal>.
+ </para>
</sect1>
<sect1 id="groups">
@@ -123,7 +169,7 @@ CREATE USER <replaceable>name</replaceable>
<para>
As in Unix, groups are a way of logically grouping users to ease
- management of permissions: permissions can be granted to, or revoked
+ management of privileges: privileges can be granted to, or revoked
from, a group as a whole. To create a group, use
<synopsis>
CREATE GROUP <replaceable>name</replaceable>
@@ -203,11 +249,7 @@ REVOKE ALL ON accounts FROM PUBLIC;
server that other users may execute without knowing it. Hence, both
mechanisms permit users to <firstterm>Trojan horse</firstterm>
others with relative impunity. The only real protection is tight
- control over who can define functions (e.g., write to relations
- with SQL fields) and triggers. Audit trails and alerters on the
- system catalogs <literal>pg_class</literal>,
- <literal>pg_shadow</literal> and <literal>pg_group</literal> are also
- possible.
+ control over who can define functions.
</para>
<para>
@@ -219,7 +261,6 @@ REVOKE ALL ON accounts FROM PUBLIC;
system access controls. This is an inherent problem with
user-defined C functions.
</para>
-
</sect1>
</chapter>
diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml
index 22127be7556..f7ed4448add 100644
--- a/doc/src/sgml/user.sgml
+++ b/doc/src/sgml/user.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.31 2002/08/05 19:43:31 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.32 2002/09/25 21:16:10 petere Exp $
-->
<book id="user">
@@ -24,7 +24,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.31 2002/08/05 19:43:31
&typeconv;
&indices;
&mvcc;
- &manage;
&perform;
<!-- appendices -->
--
GitLab