diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/admin.sgml | 6 | ||||
| -rw-r--r-- | doc/src/sgml/filelist.sgml | 3 | ||||
| -rw-r--r-- | doc/src/sgml/manage-ag.sgml | 198 | ||||
| -rw-r--r-- | doc/src/sgml/manage.sgml | 228 | ||||
| -rw-r--r-- | doc/src/sgml/runtime.sgml | 12 | ||||
| -rw-r--r-- | doc/src/sgml/user-manag.sgml | 97 | ||||
| -rw-r--r-- | doc/src/sgml/user.sgml | 3 |
7 files changed, 221 insertions, 326 deletions
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,37 +8,66 @@ $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>: <synopsis> @@ -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> @@ -133,11 +183,23 @@ createdb <replaceable class="parameter">dbname</replaceable> </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 --> |