</Para>
<Para>
-Although the <FirstTerm>site administrator</FirstTerm> is responsible for overall management of the
-<ProductName>Postgres</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 task within <ProductName>Postgres</ProductName>, but will
+Although the <FirstTerm>site administrator</FirstTerm> is responsible for overall management
+of the <ProductName>Postgres</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 task
+within <ProductName>Postgres</ProductName>, but will
not by default have the same operating system privileges as the site administrator.
</Para>
be accessible by the backend.
<Para>
- 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 <quote>PGDATA</quote> is recommended
+to avoid confusion
+and conflict with other variables.
<Note>
<Para>
- The environment variable style of specification
+ In previous versions of <ProductName>Postgres</ProductName>,
+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.
</Para>
</Note>
additional path fields appended.
<Para>
-Alternate database locations must be prepared by running <Application>initlocation</Application>.
+Alternate database locations must be prepared by running
+<Application>initlocation</Application>.
<Para>
-To create a data storage area in <FileName>/alt/postgres/data</FileName>, ensure
-that <FileName>/alt/postgres</FileName> already exists.
-From the command line, type
-<ProgramListing>
-% initlocation /alt/postgres/data
-Creating Postgres database system directory /alt/postgres/data
-
-Creating Postgres database system directory /alt/postgres/data/base
-
-</ProgramListing>
-
-<Para>
-To do the same using an environment variable PGDATA2, type
+To create a data storage area using the environment variable
+<envar>PGDATA2</envar> (for this example set to <filename>/alt/postgres</filename>),
+ensure that <FileName>/alt/postgres</FileName> already exists and is writable by
+the Postgres administrator account.
+Then, from the command line, type
<ProgramListing>
% initlocation $PGDATA2
Creating Postgres database system directory /alt/postgres/data
-
Creating Postgres database system directory /alt/postgres/data/base
-
</ProgramListing>
<Para>
-To create a database in the alternate storage area <FileName>/alt/postgres/data</FileName>
-from the command line,
-type
-<ProgramListing>
-% createdb -D /alt/postgres/data mydb
-</ProgramListing>
-
-or
-
+To create a database in the alternate storage area <envar>PGDATA2<envar>
+from the command line, use the following command:
<ProgramListing>
% createdb -D PGDATA2 mydb
</ProgramListing>
-and to do the same from within <Application>psql</Application> type
+To do the same from within <Application>psql</Application> type
<ProgramListing>
* CREATE DATABASE mydb WITH LOCATION = 'PGDATA2';
</ProgramListing>
</ListItem>
</ItemizedList>
-You might want to start up <Application>psql</Application>, to try out the examples in this manual.
+You might 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>
This tells the server to process the query. If you
terminate your query with a semicolon, the <Quote>\g</Quote> is not
- necessary. <Application>psql</Application> will automatically process semicolon terminated queries.
+ necessary.
+<Application>psql</Application> will automatically process semicolon terminated queries.
To read queries from a file, say myFile, instead of
entering them interactively, type:
<ProgramListing>
be accessible by the backend.
<Para>
- 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.
<Note>
<Para>
- The environment variable style of specification
+ In previous versions of <ProductName>Postgres</ProductName>,
+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 <ProductName>Postgres</ProductName>
+ To do this, either add this line
+<ProgramListing>
+#define ALLOW_ABSOLUTE_DBPATHS 1
+</ProgramListing>
+to the file <filename>src/include/config.h</filename>, or by specifying
+<ProgramListing>
+ CFLAGS+= -DALLOW_ABSOLUTE_DBPATHS
+</ProgramListing>
+in your <filename>Makefile.custom</filename>.
</Para>
</Note>
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 <filename>/home/postgres/data</filename>, type
+PGDATA2 pointing to <filename>/home/postgres/data</filename>, first type
<ProgramListing>
% setenv PGDATA2 /home/postgres/data
</ProgramListing>
-
-<Para>
+to define the environment variable to be used with subsequent commands.
Usually, you will want to define this variable in the
<ProductName>Postgres</ProductName> superuser's
<filename>.profile</filename>
or
<filename>.cshrc</filename>
-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.
<Para>
-To create a data storage area in <filename>/home/postgres/data</filename>, ensure
-that <filename>/home/postgres</filename> already exists and is writable.
-From the command line, type
+To create a data storage area in PGDATA2, ensure
+that <filename>/home/postgres</filename> already exists and is writable
+by the postgres administrator.
+Then from the command line, type
<ProgramListing>
+% setenv PGDATA2 /home/postgres/data
% initlocation $PGDATA2
Creating Postgres database system directory /home/postgres/data
<Para>
Assuming that your site administrator has properly
started the <Application>postmaster</Application> 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
<filename>/usr/local/pgsql/bin</filename> to your shell search path.
In most cases, this is all you should have to do in
<ProgramListing>
connectDB() failed: Is the postmaster running at 'localhost' on port '5432'?
</ProgramListing>
- it is usually because either the <Application>postmaster</Application> is not running,
+ it is usually because either the <Application>postmaster</Application> is not running,
or you are attempting to connect to the wrong server host.
If you get the following error message:
<ProgramListing>