diff --git a/doc/src/sgml/manage.sgml b/doc/src/sgml/manage.sgml index 22c0a91839..c450f522ec 100644 --- a/doc/src/sgml/manage.sgml +++ b/doc/src/sgml/manage.sgml @@ -11,12 +11,14 @@ This section is currently a thinly disguised copy of the Tutorial. Needs to be a -Although the site administrator is responsible for overall management of the -Postgres installation, some databases within the -installation may be managed by another person, designated the database administrator. -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 task within Postgres, but will +Although the site administrator is responsible for overall management +of the Postgres installation, some databases within the +installation may be managed by another person, +designated the database administrator. +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 task +within Postgres, but will not by default have the same operating system privileges as the site administrator. @@ -82,18 +84,27 @@ occurs through the database backend, so that any location specified must be accessible by the backend. - Either an absolute path name or an environment variable -may be specified as a location. -Any environment variable specifying an alternate location must have -been defined before the backend was started. + Alternate database locations are created and referenced by an environment variable +which gives the absolute path to the intended storage location. +This environment variable must have been defined before the backend was started +and the location it points to must be writable by the postgres administrator account. Consult with the site administrator -regarding preconfigured alternate database locations. +regarding preconfigured alternate database locations. +Any valid environment variable name may be used to reference an alternate location, +although using variable names with a prefix of PGDATA is recommended +to avoid confusion +and conflict with other variables. - The environment variable style of specification + In previous versions of Postgres, +it was also permissable to use an absolute path name to specify +an alternate storage location. +Although the environment variable style of specification is to be preferred since it allows the site administrator more flexibility in -managing disk storage. +managing disk storage, it is also possible to use an absolute path +to specify an alternate location. +The administrator's guide discusses how to enable this feature. @@ -103,45 +114,29 @@ any path or environment variable specified has some additional path fields appended. -Alternate database locations must be prepared by running initlocation. +Alternate database locations must be prepared by running +initlocation. -To create a data storage area in /alt/postgres/data, ensure -that /alt/postgres already exists. -From the command line, type - -% initlocation /alt/postgres/data -Creating Postgres database system directory /alt/postgres/data - -Creating Postgres database system directory /alt/postgres/data/base - - - - -To do the same using an environment variable PGDATA2, type +To create a data storage area using the environment variable +PGDATA2 (for this example set to /alt/postgres), +ensure that /alt/postgres already exists and is writable by +the Postgres administrator account. +Then, from the command line, type % initlocation $PGDATA2 Creating Postgres database system directory /alt/postgres/data - Creating Postgres database system directory /alt/postgres/data/base - -To create a database in the alternate storage area /alt/postgres/data -from the command line, -type - -% createdb -D /alt/postgres/data mydb - - -or - +To create a database in the alternate storage area PGDATA2 +from the command line, use the following command: % createdb -D PGDATA2 mydb -and to do the same from within psql type +To do the same from within psql type * CREATE DATABASE mydb WITH LOCATION = 'PGDATA2'; @@ -195,7 +190,8 @@ running the Postgres terminal monitor programs (e -You might want to start up psql, to try out the examples in this manual. +You might want to start up psql, +to try out the examples in this manual. It can be activated for the mydb database by typing the command: @@ -237,7 +233,8 @@ mydb=> \g This tells the server to process the query. If you terminate your query with a semicolon, the \g is not - necessary. psql will automatically process semicolon terminated queries. + necessary. +psql will automatically process semicolon terminated queries. To read queries from a file, say myFile, instead of entering them interactively, type: diff --git a/doc/src/sgml/start-ag.sgml b/doc/src/sgml/start-ag.sgml index 49c37a3a8c..caa2cb6eec 100644 --- a/doc/src/sgml/start-ag.sgml +++ b/doc/src/sgml/start-ag.sgml @@ -75,16 +75,32 @@ occurs through the database backend, so that any location specified must be accessible by the backend. - Either an absolute path name or an environment variable -may be specified as a location. Note that for security and integrity reasons, -all paths and environment variables so specified have some -additional path fields appended. + Alternate database locations are created and referenced by an environment variable + which gives the absolute path to the intended storage location. +This environment variable must have been defined before the backend was started +and must be writable by the postgres administrator account. +Any valid environment variable name may be used to reference an alternate +location, although using variable name with a prefix of PGDATA is recommended +to avoid confusion and conflict with other variables. - The environment variable style of specification + In previous versions of Postgres, +it was also permissable to use an absolute path name to specify an alternate storage location. +The environment variable style of specification is to be preferred since it allows the site administrator more flexibility in managing disk storage. +If you prefer using absolute paths, you may do so by defining +"ALLOW_ABSOLUTE_DBPATHS" and recompiling Postgres + To do this, either add this line + +#define ALLOW_ABSOLUTE_DBPATHS 1 + +to the file src/include/config.h, or by specifying + + CFLAGS+= -DALLOW_ABSOLUTE_DBPATHS + +in your Makefile.custom. @@ -92,24 +108,29 @@ managing disk storage. Remember that database creation is actually performed by the database backend. Therefore, any environment variable specifying an alternate location must have been defined before the backend was started. To define an alternate location -PGDATA2 pointing to /home/postgres/data, type +PGDATA2 pointing to /home/postgres/data, first type % setenv PGDATA2 /home/postgres/data - - +to define the environment variable to be used with subsequent commands. Usually, you will want to define this variable in the Postgres superuser's .profile or .cshrc -initialization file to ensure that it is defined upon system startup. +initialization file to ensure that it is defined upon system startup. +Any environment variable can be used to reference alternate location, +although it is preferred that the variables be prefixed with "PGDATA" +to eliminate confusion and the possibility of conflicting with or +overwriting other variables. -To create a data storage area in /home/postgres/data, ensure -that /home/postgres already exists and is writable. -From the command line, type +To create a data storage area in PGDATA2, ensure +that /home/postgres already exists and is writable +by the postgres administrator. +Then from the command line, type +% setenv PGDATA2 /home/postgres/data % initlocation $PGDATA2 Creating Postgres database system directory /home/postgres/data @@ -132,8 +153,7 @@ To test the new location, create a database test by typing Assuming that your site administrator has properly started the postmaster process -and authorized you to - use the database, you (as a user) may begin to start up +and authorized you to use the database, you (as a user) may begin to start up applications. As previously mentioned, you should add /usr/local/pgsql/bin to your shell search path. In most cases, this is all you should have to do in @@ -147,7 +167,7 @@ and authorized you to connectDB() failed: Is the postmaster running at 'localhost' on port '5432'? - it is usually because either the postmaster is not running, + it is usually because either the postmaster is not running, or you are attempting to connect to the wrong server host. If you get the following error message: