Skip to content

P
Postgres FD Implementation
Commit c889c9c9 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Enhance the description of user and database management. Reduce the 

number of forward references in the admin guide.
parent 8a6fab41
Expand all Show whitespace changes
Inline Side-by-side
Showing with 221 additions and 326 deletions
doc/src/sgml/admin.sgml
View file @ c889c9c9
<!--
$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;
......
doc/src/sgml/filelist.sgml
View file @ c889c9c9
<!-- $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">
......
doc/src/sgml/manage-ag.sgml
View file @ c889c9c9
This diff is collapsed.
doc/src/sgml/manage.sgml deleted 100644 → 0
View file @ 8a6fab41
<!--
$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:
-->
doc/src/sgml/runtime.sgml
View file @ c889c9c9
<!--
$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>
......
doc/src/sgml/user-manag.sgml
View file @ c889c9c9
<!--
$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>
doc/src/sgml/user.sgml
View file @ c889c9c9
<!--
$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 -->
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment