sharpetronics/PostgreSQL
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-31 00:01:57 -04:00
Code Issues Projects Releases Wiki Activity

Enhance the description of user and database management. Reduce the

Browse Source 
number of forward references in the admin guide.
This commit is contained in:
Peter Eisentraut 2002-09-25 21:16:10 +00:00
parent 8a6fab412e
commit c889c9c901
7 changed files with 221 additions and 326 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/src/sgml/admin.sgml
View File

@ -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"> <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; &installation;
&installw; &installw;
&runtime; &runtime;
&user-manag;
&manage-ag;
&client-auth; &client-auth;
&charset; &charset;
&manage-ag;
&user-manag;
&maintenance; &maintenance;
&backup; &backup;
&monitoring; &monitoring;

3
doc/src/sgml/filelist.sgml
View File

@ -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 history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml"> <!entity info SYSTEM "info.sgml">
@ -29,7 +29,6 @@
<!entity func SYSTEM "func.sgml"> <!entity func SYSTEM "func.sgml">
<!entity indices SYSTEM "indices.sgml"> <!entity indices SYSTEM "indices.sgml">
<!entity keywords SYSTEM "keywords.sgml"> <!entity keywords SYSTEM "keywords.sgml">
<!entity manage SYSTEM "manage.sgml">
<!entity mvcc SYSTEM "mvcc.sgml"> <!entity mvcc SYSTEM "mvcc.sgml">
<!entity perform SYSTEM "perform.sgml"> <!entity perform SYSTEM "perform.sgml">
<!entity queries SYSTEM "queries.sgml"> <!entity queries SYSTEM "queries.sgml">

198
doc/src/sgml/manage-ag.sgml
View File

@ -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"> <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</></> <indexterm zone="managing-databases"><primary>database</></>
<para> <para>
A database is a named collection of SQL objects (<quote>database Every instance of a running PostgreSQL server manages one or more
objects</quote>). Generally, every database object (tables, functions, databases. Databases are therefore the topmost hierarchical level
etc.) belongs to one and only one database. (But there are a few system for organizing SQL objects (<quote>database objects</quote>). This
catalogs, for example <literal>pg_database</>, that belong to a whole chapter describes the properties of databases, and how to create,
installation and are accessible from each database within the manage, and destroy them.
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.)
</para> </para>
<note> <sect1>
<title>Overview</title>
<para> <para>
<acronym>SQL</> calls databases <quote>catalogs</>, but there is no A database is a named collection of SQL objects (<quote>database
difference in practice. 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> </para>
</note>
<para> <para>
In order to create or drop databases, the <productname>PostgreSQL</> An application that connects to the database server specifies in
<application>postmaster</> must be up and running (see <xref its connection request the name of the database it wants to connect
linkend="postmaster-start">). to. It is not possible to access more than one database per
</para> 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"> <sect1 id="manage-ag-createdb">
<title>Creating a Database</title> <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> <para>
Databases are created with the query language command Databases are created with the query language command
<command>CREATE DATABASE</command>: <command>CREATE DATABASE</command>:
@ -56,20 +85,17 @@ CREATE DATABASE <replaceable>name</>
linkend="user-attributes"> for how to grant permission. linkend="user-attributes"> for how to grant permission.
</para> </para>
<formalpara> <para>
<title>Bootstrapping:</title> Since you need to be connected to the database server in order to
<para> execute the <command>CREATE DATABASE</command> command, the
Since you need to be connected to the database server in order to question remains how the <emphasis>first</> database at any given
execute the <command>CREATE DATABASE</command> command, the site can be created. The first database is always created by the
question remains how the <emphasis>first</> database at any given <command>initdb</> command when the data storage area is
site can be created. The first database is always created by the initialized. (See <xref linkend="creating-cluster">.) By convention
<command>initdb</> command when the data storage area is this database is called <literal>template1</>. So to create the
initialized. (See <xref linkend="creating-cluster">.) By convention first <quote>real</> database you can connect to
this database is called <literal>template1</>. So <literal>template1</>.
to create the first <quote>real</> database you can connect to </para>
<literal>template1</>.
</para>
</formalpara>
<para> <para>
The name <quote>template1</quote> is no accident: When a new 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 This means that any changes you make in <literal>template1</> are
propagated to all subsequently created databases. This implies that propagated to all subsequently created databases. This implies that
you should not use the template database for real work, but when you should not use the template database for real work, but when
used judiciously this feature can be convenient. More details appear used judiciously this feature can be convenient. More details
below. appear in <xref linkend="manage-ag-templatedbs">.
</para> </para>
<para> <para>
As an extra convenience, there is also a program that you can As an extra convenience, there is also a program that you can
execute from the shell to create new databases, execute from the shell to create new databases,
<filename>createdb</>. <command>createdb</>.
<synopsis> <synopsis>
createdb <replaceable class="parameter">dbname</replaceable> createdb <replaceable class="parameter">dbname</replaceable>
@ -99,8 +125,32 @@ createdb <replaceable class="parameter">dbname</replaceable>
you want. you want.
</para> </para>
<sect2 id="manage-ag-templatedbs"> <note>
<title>Template Databases</title> <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> <para>
<command>CREATE DATABASE</> actually works by copying an existing <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 will be copied into subsequently created user databases. This
behavior allows site-local modifications to the standard set of behavior allows site-local modifications to the standard set of
objects in databases. For example, if you install the procedural 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 automatically be available in user databases without any extra action
being taken when those databases are made. being taken when those databases are made.
</para> </para>
@ -132,12 +182,24 @@ createdb <replaceable class="parameter">dbname</replaceable>
additions that may now be present in <literal>template1</>. additions that may now be present in <literal>template1</>.
</para> </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> <para>
It is possible to create additional template databases, and indeed It is possible to create additional template databases, and indeed
one might copy any database in an installation by specifying its name one might copy any database in an installation by specifying its name
as the template for <command>CREATE DATABASE</>. It is important to as the template for <command>CREATE DATABASE</>. It is important to
understand, however, that this is not (yet) intended as 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 essential that the source database be idle (no data-altering transactions
in progress) in progress)
for the duration of the copying operation. <command>CREATE DATABASE</> for the duration of the copying operation. <command>CREATE DATABASE</>
@ -151,7 +213,7 @@ createdb <replaceable class="parameter">dbname</replaceable>
<para> <para>
Two useful flags exist in <literal>pg_database</literal> for each 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> <literal>datallowconn</literal>. <literal>datistemplate</literal>
may be set to indicate that a database is intended as a template for 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 <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 <literal>template1</> and <literal>template0</> do not have any special
status beyond the fact that the name <literal>template1</> is the default status beyond the fact that the name <literal>template1</> is the default
source database name for <command>CREATE DATABASE</> and 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 For example, one could drop <literal>template1</> and recreate it from
<literal>template0</> without any ill effects. This course of action <literal>template0</> without any ill effects. This course of action
might be advisable if one has carelessly added a bunch of junk in might be advisable if one has carelessly added a bunch of junk in
<literal>template1</>. <literal>template1</>.
</para> </para>
</note> </note>
</sect1>
</sect2> <sect1 id="manage-ag-config">
<title>Database Configuration</title>
<sect2 id="manage-ag-alternate-locs"> <para>
<title>Alternative Locations</title> 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>
<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>
<sect1 id="manage-ag-alternate-locs">
<title>Alternative Locations</title>
<para> <para>
It is possible to create a database in a location other than the 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 initialize the data area, and finally restart the server. (See
<xref linkend="postmaster-shutdown"> and <xref <xref linkend="postmaster-shutdown"> and <xref
linkend="postmaster-start">.) To set an environment variable, type linkend="postmaster-start">.) To set an environment variable, type
<informalexample>
<programlisting> <programlisting>
PGDATA2=/home/postgres/data PGDATA2=/home/postgres/data
export PGDATA2 export PGDATA2
</programlisting> </programlisting>
</informalexample>
in Bourne shells, or in Bourne shells, or
<informalexample>
<programlisting> <programlisting>
setenv PGDATA2 /home/postgres/data setenv PGDATA2 /home/postgres/data
</programlisting> </programlisting>
</informalexample>
in <application>csh</> or <application>tcsh</>. You have to make sure that this environment in <application>csh</> or <application>tcsh</>. You have to make sure that this environment
variable is always defined in the server environment, otherwise variable is always defined in the server environment, otherwise
you won't be able to access that database. Therefore you probably 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 already exists and is writable
by the user account that runs the server (see <xref by the user account that runs the server (see <xref
linkend="postgres-user">). Then from the command line, type linkend="postgres-user">). Then from the command line, type
<informalexample>
<programlisting> <programlisting>
initlocation PGDATA2 initlocation PGDATA2
</programlisting> </programlisting>
</informalexample> (<emphasis>not</emphasis> <literal>initlocation
Then you can restart the server. $PGDATA2</literal>). Then you can restart the server.
</para> </para>
<para> <para>
@ -290,8 +376,6 @@ gmake CPPFLAGS=-DALLOW_ABSOLUTE_DBPATHS all
</programlisting> </programlisting>
</para> </para>
</note> </note>
</sect2>
</sect1> </sect1>
<sect1 id="manage-ag-dropdb"> <sect1 id="manage-ag-dropdb">

228
doc/src/sgml/manage.sgml
View File

@ -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:
-->

12
doc/src/sgml/runtime.sgml
View File

@ -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"> <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 database cluster will contain a database named
<literal>template1</literal>. As the name suggests, this will be used <literal>template1</literal>. As the name suggests, this will be used
as a template for subsequently created databases; it should not be 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>
<para> <para>
@ -120,18 +121,17 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
<para> <para>
However, while the directory contents are secure, the default However, while the directory contents are secure, the default
<filename>pg_hba.conf</filename> authentication method of client authentication setup allows any local user to connect to the
<literal>trust</literal> allows any local user to connect to the
database and even become the database superuser. If you don't trust database and even become the database superuser. If you don't trust
other local users, we recommend you use <command>initdb</command>'s other local users, we recommend you use <command>initdb</command>'s
<option>-W</option> or <option>--pwprompt</option> option to assign a <option>-W</option> or <option>--pwprompt</option> option to assign a
password to the database superuser. After <command>initdb</command>, 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 <literal>password</> instead of <literal>trust</> authentication
<emphasis>before</> you start the server for the first time. (Other, <emphasis>before</> you start the server for the first time. (Other,
approaches include using <literal>ident</literal> authentication or approaches include using <literal>ident</literal> authentication or
file system permissions to restrict connections. See <xref file system permissions to restrict connections. See <xref
linkend="client-authentication"> for more information. linkend="client-authentication"> for more information.)
</para> </para>
<para> <para>

97
doc/src/sgml/user-manag.sgml
View File

@ -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"> <chapter id="user-manag">
<title>Database Users and Permissions</title> <title>Database Users and Privileges</title>
<para> <para>
Managing database users and their privileges is in concept similar Every database cluster contains a set of database users. Those
to managing the users of a Unix operating system, but the details users are separate from the users managed by the operating system on
are not identical. 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> </para>
<sect1 id="database-users"> <sect1 id="database-users">
@ -27,19 +36,27 @@ CREATE USER <replaceable>name</replaceable>
<replaceable>name</replaceable> follows the rules for SQL <replaceable>name</replaceable> follows the rules for SQL
identifiers: either unadorned without special characters, or identifiers: either unadorned without special characters, or
double-quoted. To remove an existing user, use the analogous 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>
<para> <para>
For convenience, the shell scripts <application>createuser</application> For convenience, the programs <application>createuser</application>
and <application>dropuser</application> are provided as wrappers around these SQL and <application>dropuser</application> are provided as wrappers
commands. 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>
<para> <para>
In order to bootstrap the database system, a freshly initialized In order to bootstrap the database system, a freshly initialized
system always contains one predefined user. This user will have the 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 <application>initdb</application>) it will have the same name as
the operating system user that initialized the database the operating system user that initialized the database
cluster. Customarily, this user will be named cluster. Customarily, this user will be named
@ -48,21 +65,34 @@ CREATE USER <replaceable>name</replaceable>
</para> </para>
<para> <para>
The user name to use for a particular database connection is Exactly one user identity is active for a connection to the
indicated by the client that is initiating the connection request database server. The user name to use for a particular database
in an application-specific fashion. For example, the connection is indicated by the client that is initiating the
<application>psql</application> program uses the <option>-U</option> connection request in an application-specific fashion. For example,
command line option to indicate the user to connect as. The set of the <application>psql</application> program uses the
database users a given client connection may connect as is <option>-U</option> command line option to indicate the user to
determined by the client authentication setup, as explained in 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 <xref linkend="client-authentication">. (Thus, a client is not
necessarily limited to connect as the user with the same name as necessarily limited to connect as the user with the same name as
its operating system user, in the same way a person is not 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> </para>
</sect1>
<sect2 id="user-attributes"> <sect1 id="user-attributes">
<title>User attributes</title> <title>User Attributes</title>
<para> <para>
A database user may have a number of attributes that define its 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 See the reference pages for <command>CREATE USER</command> and
<command>ALTER USER</command> for details. <command>ALTER USER</command> for details.
</para> </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>
<sect1 id="groups"> <sect1 id="groups">
@ -123,7 +169,7 @@ CREATE USER <replaceable>name</replaceable>
<para> <para>
As in Unix, groups are a way of logically grouping users to ease 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 from, a group as a whole. To create a group, use
<synopsis> <synopsis>
CREATE GROUP <replaceable>name</replaceable> 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 server that other users may execute without knowing it. Hence, both
mechanisms permit users to <firstterm>Trojan horse</firstterm> mechanisms permit users to <firstterm>Trojan horse</firstterm>
others with relative impunity. The only real protection is tight others with relative impunity. The only real protection is tight
control over who can define functions (e.g., write to relations control over who can define functions.
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.
</para> </para>
<para> <para>
@ -219,7 +261,6 @@ REVOKE ALL ON accounts FROM PUBLIC;
system access controls. This is an inherent problem with system access controls. This is an inherent problem with
user-defined C functions. user-defined C functions.
</para> </para>
</sect1> </sect1>
</chapter> </chapter>

3
doc/src/sgml/user.sgml
View File

@ -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"> <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; &typeconv;
&indices; &indices;
&mvcc; &mvcc;
&manage;
&perform; &perform;
<!-- appendices --> <!-- appendices -->