diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index 957c53f5b41..a5d2717185b 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -110,4 +110,12 @@
+
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/ref/commands.sgml b/doc/src/sgml/ref/commands.sgml
index 77fcccf2528..475041b6280 100644
--- a/doc/src/sgml/ref/commands.sgml
+++ b/doc/src/sgml/ref/commands.sgml
@@ -58,6 +58,7 @@ commands supported by Postgres.
&set;
&show;
&update;
+&vacuum;
@@ -84,6 +85,14 @@ This is reference information for the
Postgres support utilities.
+&createdb;
+&createuser;
+&destroydb;
+&destroyuser;
+&initdb;
+&initlocation;
+&pgDump;
+&pgDumpall;
&psqlRef;
diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml
new file mode 100644
index 00000000000..090f68ccdf0
--- /dev/null
+++ b/doc/src/sgml/ref/createdb.sgml
@@ -0,0 +1,221 @@
+
+
+
+createdb
+
+Application
+
+
+
+createdb
+
+
+Create a new Postgres database
+
+
+
+1998-10-02
+
+
+createdb [ dbname ]
+createdb [ -h host ] [ -p port ]
+ [ -D datadir ]
+ [ -u ] [ dbname ]
+
+
+
+
+1998-10-02
+
+
+Inputs
+
+
+
+
+
+
+-h host
+
+
+
+Specifies the hostname of the machine on which the
+postmaster
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+
+
+-p port
+
+
+
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the postmaster
+is listening for connections. The port number defaults to 5432,
+ or the value of the PGPORT
+environment variable (if set).
+
+
+
+-u
+
+
+
+Use password authentication.
+Prompts for
+username
+ and password.
+
+
+
+-D datadir
+
+
+
+Specifies the alternate database location for this database installation.
+This is the location of the installation system tables, not the location
+of this specific database, which may be different.
+
+
+
+dbname
+
+
+
+Specifies the name of the database to be created. The name must be
+unique among all Postgres databases in this installation.
+dbname
+defaults to the value of the
+USER
+environment variable.
+
+
+
+
+
+1998-10-02
+
+
+Outputs
+
+
+createdb will create files in the
+PGDATA/dbname/
+data area for the new database.
+
+
+
+
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port 'port'?
+createdb: database creation failed on dbname.
+
+
+createdb could not attach to the
+postmaster
+process on the specified host and port. If you see this message,
+ensure that the postmaster
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+
+
+Connection to database 'template1' failed.
+FATAL 1: SetUserId: user 'username' is not in 'pg_shadow'
+createdb: database creation failed on dbname.
+
+
+You do not have a valid entry in the relation pg_shadow
+and and will not be allowed to access Postgres.
+Contact your Postgres administrator.
+
+
+
+ERROR: user 'username' is not allowed to create/destroy databases
+createdb: database creation failed on dbname.
+
+
+You do not have permission to create new databases.
+Contact your Postgres site administrator.
+
+
+
+ERROR: createdb: database 'dbname' already exists.
+createdb: database creation failed on dbname.
+
+
+The database already exists.
+
+
+
+createdb: database creation failed on dbname.
+
+
+An internal error occurred in psql
+or in the backend server. Ensure that your site administrator has
+properly installed Postgresand initialized the site with
+initdb.
+
+
+
+
+
+createdb internally runs
+CREATE DATABASE from psql
+while connected to the template1 database.
+
+
+
+
+1998-10-02
+
+
+Description
+
+
+createdb creates a new
+Postgres database.
+The person who executes this command becomes
+the database administrator, or DBA,
+ for this database and is the only
+person, other than the Postgres super-user,
+ who can destroy it.
+
+
+createdb is a shell script that invokes
+psql.
+Hence, a postmaster
+process must be running on the database server host before
+createdb
+is executed. The
+PGOPTION
+and
+PGREALM
+environment variables will be passed on to
+psql
+and processed as described in .
+
+
+
+1998-10-02
+
+
+Usage
+
+
+To create the database demo
+ using the postmaster on the local host, port 5432:
+
+createdb demo
+
+
+To create the database demo
+ using the postmaster on host eden, port 5000:
+
+createdb -p 5000 -h eden demo
+
+
+
diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
new file mode 100644
index 00000000000..f06b3c025bb
--- /dev/null
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -0,0 +1,237 @@
+
+
+
+createuser
+
+Application
+
+
+
+createuser
+
+
+Create a new Postgres user
+
+
+
+1998-10-02
+
+
+createuser [ username ]
+createuser [ -h host ] [ -p port ]
+ [ -i userid ]
+ [ -d | -D ] [ -u | -U ] [ username ]
+
+
+
+
+1998-10-02
+
+
+Inputs
+
+
+
+
+
+
+-h host
+
+
+
+Specifies the hostname of the machine on which the
+postmaster
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+
+
+-p port
+
+
+
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the postmaster
+is listening for connections. The port number defaults to 5432,
+ or the value of the PGPORT
+environment variable (if set).
+
+
+
+-d
+
+
+
+Allows the user to create databases.
+
+
+
+-D
+
+
+
+Forbids the user to create databases.
+
+
+
+-i userid
+
+
+
+Specifies the numeric identifier to be associated with this user.
+This identifier must be unique among all Postgres users, and is not required
+to match the operating system UID.
+You will be prompted for an identifier if none is specified on the command line,
+and it will suggest an identifier matching the UID.
+
+
+
+-u
+
+
+
+Allows the user to create other users.
+
+
+
+-U
+
+
+
+Forbids the user to create other users.
+
+
+
+username
+
+
+
+Specifies the name of the Postgres user to be created.
+This name must be unique among all Postgres users.
+You will be prompted for a name if none is specified on the command line.
+
+
+
+
+
+1998-10-02
+
+
+Outputs
+
+
+createuser will add an entry in the
+pg_user or pg_shadow system table.
+
+
+
+
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port 'port'?
+createuser: database access failed.
+
+
+createuser could not attach to the
+postmaster
+process on the specified host and port. If you see this message,
+ensure that the postmaster
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+
+
+Connection to database 'template1' failed.
+FATAL 1: SetUserId: user 'username' is not in 'pg_shadow'
+createuser: database access failed.
+
+
+You do not have a valid entry in the relation pg_shadow
+and and will not be allowed to access Postgres. Contact your
+Postgres administrator.
+
+
+
+createuser: username cannot create users.
+
+
+You do not have permission to create new users; contact your
+Postgres site administrator.
+
+
+
+createuser: user "username" already exists
+
+
+The user to be added already has an entry in the pg_shadow
+class.
+
+
+
+database access failed
+
+
+An internal error occurred in psql
+or in the backend server. Ensure that your site administrator has
+properly installed Postgresand initialized the site with
+initdb.
+
+
+
+
+
+createuser internally runs
+CREATE USER from psql
+while connected to the template1 database.
+
+
+
+
+1998-10-02
+
+
+Description
+
+
+createuser creates a
+new Postgres user.
+Only users with usesuper set in
+the pg_shadow class can create
+new Postgres users. As shipped,
+the user postgres can create users.
+
+
+createuser is a shell script that invokes
+psql.
+Hence, a postmaster
+process must be running on the database server host before
+createuser is executed.
+ The
+PGOPTION
+and
+PGREALM
+environment variables will be passed on to
+psql
+and processed as described in .
+
+Once invoked, createuser
+will ask a series of questions to obtain parameters not specified on
+the command line. The new user's database login name and a numeric
+user identifier must be specified.
+
+
+
+The Postgres user identifier
+does not need to be the same as the user's Unix UID. However, typically
+they are assigned to be the same.
+
+
+
+You must also describe the privileges of the new user for security purposes.
+Specifically, you will be asked whether the new user should be able to
+act as Postgres super-user,
+whether the new user may create new databases and whether the new user
+is allowed to create other new users.
+
+
diff --git a/doc/src/sgml/ref/destroydb.sgml b/doc/src/sgml/ref/destroydb.sgml
new file mode 100644
index 00000000000..547cfee8809
--- /dev/null
+++ b/doc/src/sgml/ref/destroydb.sgml
@@ -0,0 +1,224 @@
+
+
+
+destroydb
+
+Application
+
+
+
+destroydb
+
+
+Create a new Postgres database
+
+
+
+1998-10-02
+
+
+destroydb [ dbname ]
+destroydb [ -h host ] [ -p port ]
+ [ -i ] [ dbname ]
+
+
+
+
+1998-10-02
+
+
+Inputs
+
+
+
+
+
+
+-h host
+
+
+
+Specifies the hostname of the machine on which the
+postmaster
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+
+
+-p port
+
+
+
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the postmaster
+is listening for connections. The port number defaults to 5432,
+ or the value of the PGPORT
+environment variable (if set).
+
+
+
+-i
+
+
+
+Run in interactive mode.
+Prompts for confirmation before destroying a database.
+
+
+
+dbname
+
+
+
+Specifies the name of the database to be destroyed. The database
+must be one of the existing Postgres databases
+ in this installation.
+dbname
+defaults to the value of the
+USER
+environment variable.
+
+
+
+
+
+1998-10-02
+
+
+Outputs
+
+
+destroydb will remove files from the
+PGDATA/dbname/
+data area for the existing database.
+
+
+
+
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port 'port'?
+destroydb: database destroy failed on dbname.
+
+
+destroydb could not attach to the
+postmaster
+process on the specified host and port. If you see this message,
+ensure that the postmaster
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+
+
+Connection to database 'template1' failed.
+FATAL 1: SetUserId: user 'username' is not in 'pg_shadow'
+destroydb: database destroy failed on dbname.
+
+
+You do not have a valid entry in the relation pg_shadow
+and and will not be allowed to access Postgres.
+Contact your Postgres administrator.
+
+
+
+ERROR: user 'username' is not allowed to create/destroy databases
+destroydb: database destroy failed on dbname.
+
+
+You do not have permission to destroy (or create) databases.
+Contact your Postgres site administrator.
+
+
+
+ERROR: destroydb: database 'dbname' does not exist.
+destroydb: database destroy failed on dbname.
+
+
+The database to be removed does not have an entry in the
+pg_database class.
+
+
+
+ERROR: destroydb: database 'dbname' is not owned by you.
+destroydb: database destroy failed on dbname.
+
+
+You are not the Database Administrator (DBA) for the specified database.
+
+
+
+destroydb: database destroy failed on dbname.
+
+
+An internal error occurred in psql
+or in the backend server. Ensure that your site administrator has
+properly installed Postgresand initialized the site with
+initdb.
+
+
+
+
+
+destroydb internally runs
+DESTROY DATABASE from psql
+while connected to the template1 database.
+
+
+
+
+1998-10-02
+
+
+Description
+
+
+destroydb destroys an existing
+Postgres database.
+The person who executes this command must be
+the database administrator, or DBA,
+or must be the Postgres super-user.
+The program runs silently; no confirmation message will be displayed.
+After the database is destroyed, a Unix shell prompt will reappear.
+
+
+All references to
+the database are removed, including the directory containing this
+database and its associated files.
+
+
+destroydb is a shell script that invokes
+psql.
+Hence, a postmaster
+process must be running on the database server host before
+destroydb
+is executed. The
+PGOPTION
+and
+PGREALM
+environment variables will be passed on to
+psql
+and processed as described in .
+
+
+
+1998-10-02
+
+
+Usage
+
+
+To destroy the database demo
+ using the postmaster on the local host, port 5432:
+
+destroydb demo
+
+
+
+To destroy the database demo
+ using the postmaster on host eden, port 5000:
+
+destroydb -p 5000 -h eden demo
+
+
+
diff --git a/doc/src/sgml/ref/destroyuser.sgml b/doc/src/sgml/ref/destroyuser.sgml
new file mode 100644
index 00000000000..aeda6a560e0
--- /dev/null
+++ b/doc/src/sgml/ref/destroyuser.sgml
@@ -0,0 +1,200 @@
+
+
+
+destroyuser
+
+Application
+
+
+
+destroyuser
+
+
+Destroy a Postgres user and associated databases
+
+
+
+1998-10-02
+
+
+destroyuser [ username ]
+destroyuser [ -h host ] [ -p port ]
+ [ username ]
+
+
+
+
+1998-10-02
+
+
+Inputs
+
+
+
+
+
+
+-h host
+
+
+
+Specifies the hostname of the machine on which the
+postmaster
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+
+
+-p port
+
+
+
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the postmaster
+is listening for connections. The port number defaults to 5432,
+ or the value of the PGPORT
+environment variable (if set).
+
+
+
+username
+
+
+
+Specifies the name of the Postgres user to be removed.
+This name must exist in the Postgres installation.
+You will be prompted for a name if none is specified on the command line.
+
+
+
+
+
+1998-10-02
+
+
+Outputs
+
+
+destroyuser will remove an entry in the
+pg_user or pg_shadow system table,
+and will remove all databases for which that user is the administrator
+ (DBA).
+
+
+
+
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port 'port'?
+destroyuser: database access failed.
+
+
+destroyuser could not attach to the
+postmaster
+process on the specified host and port. If you see this message,
+ensure that the postmaster
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+
+
+Connection to database 'template1' failed.
+FATAL 1: SetUserId: user 'username' is not in 'pg_shadow'
+destroyuser: database access failed.
+
+
+You do not have a valid entry in the relation pg_shadow
+and and will not be allowed to access Postgres. Contact your
+Postgres administrator.
+
+
+
+destroyuser: username cannot delete users.
+
+
+You do not have permission to delete users; contact your
+Postgres site administrator.
+
+
+
+destroyuser: user "username" already exists
+
+
+The user to be added already has an entry in the pg_shadow
+class.
+
+
+
+database access failed
+
+
+An internal error occurred in psql
+or in the backend server. Ensure that your site administrator has
+properly installed Postgresand initialized the site with
+initdb.
+
+
+
+destroydb on dbname failed - exiting
+
+
+An internal error occurred in psql
+or in the backend server. There was possibly a Unix permissions problem with the
+specified database.
+
+
+
+
+delete of user username was UNSUCCESSFUL
+
+
+An internal error occurred in psql
+or in the backend server.
+
+
+
+
+
+destroyuser internally runs
+DROP USER from psql
+while connected to the template1 database.
+
+
+
+
+1998-10-02
+
+
+Description
+
+
+destroyuser removes an existing
+ Postgres user
+and the databases for which that user
+is database administrator.
+Only users with usesuper set in
+the pg_shadow class can destroy
+ Postgres users. As shipped,
+the user postgres can remove users.
+
+
+destroyuser is a shell script that invokes
+psql.
+Hence, a postmaster
+process must be running on the database server host before
+destroyuser is executed.
+ The
+PGOPTION
+and
+PGREALM
+environment variables will be passed on to
+psql
+and processed as described in .
+
+
+Once invoked, destroyuser
+will warn you about the databases that will be destroyed in the
+process and permit you to abort the removal of the user if desired.
+
+
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
new file mode 100644
index 00000000000..dbbed5958e9
--- /dev/null
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -0,0 +1,278 @@
+
+
+
+initdb
+
+Application
+
+
+
+initdb
+
+
+Create a new Postgres database installation
+
+
+
+1998-10-02
+
+
+initdb [ --pgdata=dbdir | -r dbdir ]
+ [ --pglib=libdir | -l libdir ]
+ [ --template=template | -t template ]
+ [ --username=name | -u name ]
+ [ --noclean | -n ] [ --debug | -d ]
+
+
+
+
+1998-10-02
+
+
+Inputs
+
+
+
+
+
+--pglib=libdir
+
+
+-l libdir
+
+
+PGLIB
+
+
+Where are the files that make up Postgres?
+ Apart from files that
+have to go in particular directories because of their function, the
+files that make up the Postgres software
+were installed in a directory
+called the libdir directory.
+An example of a file that will be found
+there that initdb
+needs is global1.bki.source,
+ which contains all the information that goes
+into the shared catalog tables.
+
+
+
+--pgdata=dbdir
+
+
+-r dbdir
+
+
+PGDATA
+
+
+
+Where in your Unix filesystem do you want the database data to go?
+The top level directory is called the PGDATA directory.
+
+
+
+--username=name
+
+
+-u name
+
+
+PGUSER
+
+
+
+Who will be the Postgres superuser
+ for this database system? The
+Postgres superuser is a Unix user
+who owns all files that store the database
+system and also owns the postmaster and backend processes that access them.
+Or just let it default to you (the Unix user who runs
+initdb).
+
+
+
+Only the Unix superuser can create a database system with a
+different user as Postgres superuser.
+
+
+
+
+
+Other, less commonly used, parameters are also available:
+
+
+
+
+--template=template
+
+
+-t template
+
+
+
+Replace the template1
+database in an existing database system, and don't touch anything else.
+This is useful when you need to upgrade your template1
+database using initdb
+from a newer release of Postgres,
+or when your template1
+database has become corrupted by some system problem. Normally the
+contents of template1
+remain constant throughout the life of the database system. You can't
+destroy anything by running initdb
+with the
+
+option.
+
+
+
+--noclean
+
+
+-n
+
+
+
+By default, when initdb
+determines that error prevent it from completely creating the database
+system, it removes any files it may have created before determining
+that it can't finish the job. That includes any core files left by
+the programs it invokes. This option inhibits any tidying-up and is
+thus useful for debugging.
+
+
+
+--debug
+
+
+-d
+
+
+
+Print debugging output from the bootstrap backend.
+The bootstrap backend is the program initdb
+uses to create the catalog tables. This option generates a tremendous
+amount of output. It also turns off the final vacuuming step.
+
+
+
+
+Files are also input to initdb:
+
+
+
+
+postconfig
+
+
+
+If appearing somewhere in the Unix command search path
+(defined by the PATH environment variable).
+ This is a program that specifies defaults for some of the
+command options. See below.
+
+
+
+PGLIB/global1.bki.source
+
+
+
+Contents for the shared catalog tables in the new database system. This
+file is part of the Postgres software.
+
+
+
+PGLIB/local1_template1.bki.source
+
+
+
+Contents for the template1 tables in the new database system. This
+file is part of the Postgres software.
+
+
+
+
+
+1998-09-26
+
+
+Outputs
+
+
+initdb will create files in the PGDATA
+data area which are the system tables and framework for a complete
+installation.
+
+
+
+1998-09-26
+
+
+Description
+
+
+initdb creates a new
+Postgres database system.
+A database system is a
+collection of databases that are all administered by the same Unix user
+and managed by a single postmaster.
+
+
+Creating a database system consists of creating the directories in which
+the database data will live, generating the shared catalog tables
+(tables that don't belong to any particular database), and
+creating the template1
+database. What is the template1
+database? When you create a database, Postgres
+does it by copying
+everything from the template1
+database. It contains catalog tables filled in for things like the
+builtin types.
+
+
+After initdb
+creates the database, it completes the initialization by running
+vacuum, which resets some optimization parameters.
+
+
+There are three ways to give parameters to initdb.
+
+First, you can use initdb command options.
+ Second, you can set environment
+variables before invoking initdb.
+Third, you can have a program called postconfig
+in your Unix command search path.
+initdb invokes that program and that program then writes
+initdb parameters to its standard output stream.
+This third option is not a common thing to do, however.
+
+
+Command options always override parameters specified any other way.
+The values returned by postconfig
+override any environment variables, but your
+postconfig
+program may base its output on the environment variables if you want
+their values to be used.
+
+
+The value that postconfig
+outputs must have the format
+
+ var1=value1var2=value2 ...
+
+
+It can output nothing if it doesn't want to supply any parameters.
+The var values are equal to
+the corresponding environment variable
+names. For example,
+
+PGDATA=/tmp/postgres_test
+
+has the
+same effect as invoking initdb
+with an environment variable called PGDATA whose value is
+/tmp/postgres_test.
+
+
diff --git a/doc/src/sgml/ref/initlocation.sgml b/doc/src/sgml/ref/initlocation.sgml
new file mode 100644
index 00000000000..7302118e866
--- /dev/null
+++ b/doc/src/sgml/ref/initlocation.sgml
@@ -0,0 +1,201 @@
+
+
+
+initlocation
+
+Application
+
+
+
+initlocation
+
+
+Create a secondary Postgres database storage area
+
+
+
+1998-10-02
+
+
+initlocation [ --location=altdir | -D altdir ]
+ [ --username=name | -u name ]
+ [ altdir ]
+
+
+
+
+1998-10-02
+
+
+Inputs
+
+
+
+
+
+
+--location=altdir
+
+
+-D altdir
+
+
+altdir
+
+
+
+Where in your Unix filesystem do you want alternate databases to go?
+The top level directory is called the PGDATA directory, so you
+might want to point your first alternate location at PGDATA2.
+
+
+
+--username=name
+
+
+-u name
+
+
+PGUSER
+
+
+
+Who will be the Unix filesystem owner of this database storage area?
+The
+Postgres superuser is a Unix user
+who owns all files that store the database
+system and also owns the postmaster and backend processes that access them.
+Usually, this is the user who should run initlocation
+and who will thus have ownership of the directories and files.
+
+
+
+Only the Unix superuser can create a database system with a
+different user as the Postgres superuser.
+Specifying a user other than the Postgres superuser
+may lead to database security and data integrity problems. Refer to the
+PostgreSQL Administrator's Guide
+ for more information.
+
+
+
+
+
+
+1998-09-26
+
+
+Outputs
+
+
+initlocation will create directories in
+the specified place.
+
+
+
+
+We are initializing the database area with username postgres (uid=500).
+This user will own all the files and must also own the server process.
+Creating Postgres database system directory altdir
+Creating Postgres database system directory altdir
+
+
+
+Successful completion.
+
+
+
+We are initializing the database area with username postgres (uid=500).
+This user will own all the files and must also own the server process.
+Creating Postgres database system directory /usr/local/src/testlocation
+mkdir: cannot make directory `altdir': Permission denied
+
+
+
+You do not have filesystem permission to write to the specified directory area.
+
+
+
+Valid username not given. You must specify the username for
+the Postgres superuser for the database system you are
+initializing, either with the --username option or by default
+to the USER environment variable.
+
+
+
+The username which you have specified is not the
+Postgres superuser.
+
+
+
+Can't tell what username to use. You don't have the USER
+environment variable set to your username and didn't specify the
+--username option
+
+
+
+Specify the command line option.
+
+
+
+
+
+1998-09-26
+
+
+Description
+
+
+initlocation
+creates a new Postgres secondary database storage area.
+A secondary storage area contains a required tree of directories with
+the correct file permissions on those directories.
+
+
+Creating a database storage area consists of creating the directories in which
+database data might live.
+
+
+There are two kinds of arguments for initlocation.
+First, you can specify an environment variable (e.g. PGDATA2).
+This environment variable should be known to the backend for later use in
+CREATE DATABASE/WITH LOCATION
+ or
+createdb -D altdir.
+However, the backend daemon must have this variable in it's
+environment for this to succeed.
+
+Second, you may be able to specify an explicit
+absolute path to the top directory of the storage area. However,this second
+option is possible only if explicitly enabled during the
+Postgres installation. It is usually disabled
+ to alleviate security and data integrity concerns.
+
+
+
+Postgres will add /base/
+to the specified path to create the storage area.
+
+
+The backend requires that any argument to which is
+in all uppercase and which has no path delimiters is an environment variable.
+
+
+
+
+1998-09-26
+
+
+Usage
+
+
+To create a database in an alternate location, using an environment variable:
+
+
+% setenv PGDATA2 /opt/postgres/data
+
+% initlocation PGDATA2
+% createdb -D PGDATA2
+
+
+
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
new file mode 100644
index 00000000000..89974eaa8da
--- /dev/null
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -0,0 +1,332 @@
+
+
+
+pg_dump
+
+Application
+
+
+
+pg_dump
+
+
+Extract a Postgres database into a script file
+
+
+
+1998-10-04
+
+
+pg_dump [ dbname ]
+pg_dump [ -h host ] [ -p port ]
+ [ -t table ]
+ [ -f outputfile ]
+ [ -a ] [ -d ] [ -D ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
+ [ dbname ]
+
+
+
+
+1998-10-04
+
+
+Inputs
+
+
+pg_dump accepts the following command line arguments:
+
+
+
+
+dbname
+
+
+
+Specifies the name of the database to be extracted.
+dbname
+defaults to the value of the
+USER
+environment variable.
+
+
+
+-a
+
+
+
+Dump out only the data, no schema (definitions).
+
+
+
+-d
+
+
+
+Dump data as proper insert strings.
+
+
+
+-D
+
+
+
+Dump data as inserts with attribute names
+
+
+
+-f filename
+
+
+
+Specifies the output file. Defaults to stdout.
+
+
+
+-n
+
+
+
+Suppress double quotes around identifiers unless absolutely necessary.
+This may cause trouble loading this dumped data if there are reserved words
+used for identifiers.
+
+
+
+-o
+
+
+
+Dump object identifiers (OIDs) for every table.
+
+
+
+-s
+
+
+
+Dump out only the schema (definitions), no data.
+
+
+
+-t table
+
+
+
+Dump data for table only.
+
+
+
+-u
+
+
+
+Use password authentication. Prompts for username and password.
+
+
+
+-v
+
+
+
+Specifies verbose mode
+
+
+
+-z
+
+
+
+Include ACLs (grant/revoke commands) and table ownership information.
+
+
+
+
+pg_dump also accepts
+the following command line arguments for connection parameters:
+
+
+
+
+-h host
+
+
+
+Specifies the hostname of the machine on which the
+postmaster
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+
+
+-p port
+
+
+
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the postmaster
+is listening for connections. The port number defaults to 5432,
+ or the value of the PGPORT
+environment variable (if set).
+
+
+
+-u
+
+
+
+Use password authentication.
+Prompts for
+username
+ and password.
+
+
+
+
+
+1998-10-04
+
+
+Outputs
+
+
+pg_dump will create a file or
+ write to stdout.
+
+
+
+
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port 'port'?
+
+
+pg_dump could not attach to the
+postmaster
+process on the specified host and port. If you see this message,
+ensure that the postmaster
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+
+
+Connection to database 'dbname' failed.
+FATAL 1: SetUserId: user 'username' is not in 'pg_shadow'
+
+
+You do not have a valid entry in the relation pg_shadow
+and and will not be allowed to access Postgres.
+Contact your Postgres administrator.
+
+
+
+dumpSequence(table): SELECT failed
+
+
+You do not have permission to read the database.
+Contact your Postgres site administrator.
+
+
+
+
+
+pg_dump internally executes
+SELECT statements. If you have problems running
+pg_dump,
+make sure you are able to select information from the database using, for
+example, psql.
+
+
+
+
+1998-10-04
+
+
+Description
+
+
+pg_dump is a utility for dumping out a
+Postgres database into a script file
+ containing query commands. The script
+files are in text format and can be used to reconstruct the database,
+even on other machines and other architectures.
+pg_dump
+will produce the queries necessary to re-generate all
+user-defined types, functions, tables, indices, aggregates, and
+operators. In addition, all the data is copied out in text format so
+that it can be readily copied in again, as well as imported into tools
+for editing.
+
+
+pg_dump
+is useful for dumping out the contents of a database to move from one
+Postgres installation to another. After running
+pg_dump,
+ one should examine the output script file for any warnings, especially
+in light of the limitations listed below.
+
+
+
+1998-10-04
+
+
+Notes
+
+
+pg_dump has a few limitations.
+The limitations mostly stem from
+difficulty in extracting certain meta-information from the system
+catalogs.
+
+
+
+
+rules and views
+
+
+pg_dump
+does not understand user-defined rules and views and
+will fail to dump them properly. (This is due to the fact that
+rules are stored as plans in the catalogs and not textually).
+
+
+
+partial indices
+
+
+pg_dump
+does not understand partial indices. The reason is
+the same as above; partial index predicates are stored as plans.
+
+
+
+large objects
+
+
+pg_dump does not handle large objects.
+Large objects are ignored and must be dealt with manually.
+
+
+
+
+
+1998-10-04
+
+
+Usage
+
+
+To dump a database of the same name as the user:
+
+
+% pg_dump > db.out
+
+
+
+To reload this database:
+
+
+psql -e database < db.out
+
+
+
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
new file mode 100644
index 00000000000..08932933427
--- /dev/null
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -0,0 +1,267 @@
+
+
+
+pg_dumpall
+
+Application
+
+
+
+pg_dumpall
+
+
+Extract all Postgres databases into a script file
+
+
+
+1998-10-04
+
+
+pg_dumpall
+pg_dumpall [ -h host ] [ -p port ]
+ [ -a ] [ -d ] [ -D ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
+
+
+
+
+1998-10-04
+
+
+Inputs
+
+
+pg_dumpall accepts the following command line arguments:
+
+
+
+
+-a
+
+
+
+Dump out only the data, no schema (definitions).
+
+
+
+-d
+
+
+
+Dump data as proper insert strings.
+
+
+
+-D
+
+
+
+Dump data as inserts with attribute names
+
+
+
+-n
+
+
+
+Suppress double quotes around identifiers unless absolutely necessary.
+This may cause trouble loading this dumped data if there are reserved words
+used for identifiers.
+
+
+
+-o
+
+
+
+Dump object identifiers (OIDs) for every table.
+
+
+
+-s
+
+
+
+Dump out only the schema (definitions), no data.
+
+
+
+-u
+
+
+
+Use password authentication. Prompts for username and password.
+
+
+
+-v
+
+
+
+Specifies verbose mode
+
+
+
+-z
+
+
+
+Include ACLs (grant/revoke commands) and table ownership information.
+
+
+
+
+pg_dumpall also accepts
+the following command line arguments for connection parameters:
+
+
+
+
+-h host
+
+
+
+Specifies the hostname of the machine on which the
+postmaster
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+
+
+-p port
+
+
+
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the postmaster
+is listening for connections. The port number defaults to 5432,
+ or the value of the PGPORT
+environment variable (if set).
+
+
+
+-u
+
+
+
+Use password authentication.
+Prompts for
+username
+ and password.
+
+
+
+
+
+1998-10-04
+
+
+Outputs
+
+
+pg_dumpall will create a file or
+ write to stdout.
+
+
+
+
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port 'port'?
+
+
+pg_dumpall could not attach to the
+postmaster
+process on the specified host and port. If you see this message,
+ensure that the postmaster
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+
+
+Connection to database 'dbname' failed.
+FATAL 1: SetUserId: user 'username' is not in 'pg_shadow'
+
+
+You do not have a valid entry in the relation pg_shadow
+and and will not be allowed to access Postgres.
+Contact your Postgres administrator.
+
+
+
+dumpSequence(table): SELECT failed
+
+
+You do not have permission to read the database.
+Contact your Postgres site administrator.
+
+
+
+
+
+pg_dumpall internally executes
+SELECT statements. If you have problems running
+pg_dumpall,
+make sure you are able to select information from the database using, for
+example, psql.
+
+
+
+
+1998-10-04
+
+
+Description
+
+
+pg_dumpall
+is a utility for dumping out all Postgres databases into one file.
+It also dumps the pg_shadow table, which is global to all databases.
+pg_dumpall includes in this file the proper commands
+to automatically create each dumped database before loading.
+
+
+pg_dumpall takes all pg_dump
+ options, but , and
+dbname
+should be omitted.
+
+
+Refer to
+
+ for more information on this capability.
+
+
+
+1998-10-04
+
+
+Usage
+
+
+To dump all databases:
+
+
+% pg_dumpall -o > db.out
+
+
+
+
+You can use most pg_dump options
+for pg_dumpall.
+
+
+
+To reload this database:
+
+
+psql -e template1 < db.out
+
+
+
+
+You can use most psql options
+when reloading.
+
+
+
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 863a2a82db2..95832a7e4ec 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -6,7 +6,7 @@
Application
-
+psql
@@ -177,7 +177,6 @@ any reason.
Description
-
psql is a character-based front-end to
Postgres.
It enables you to
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
new file mode 100644
index 00000000000..bc5d7e7d5b6
--- /dev/null
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -0,0 +1,217 @@
+
+
+
+VACUUM
+
+SQL - Language Statements
+
+
+
+VACUUM
+
+
+Clean and analyze a Postgres database
+
+
+
+1998-10-04
+
+
+VACUUM [ VERBOSE ] [ ANALYZE ] [ table ]
+VACUUM [ VERBOSE ] ANALYZE [ table [ (column [, ...] ) ] ]
+
+
+
+
+1998-10-04
+
+
+Inputs
+
+
+
+
+
+
+VERBOSE
+
+
+Prints a detailed vacuum activity report for each table.
+
+
+
+ANALYZE
+
+
+Updates column statistics used by the optimizer to
+determine the most efficient way to execute a query.
+The statistics represent the disbursion of the data in each column.
+This information is valuable when several execution paths are possible.
+
+
+
+table
+
+
+The name of a specific table to vacuum. Defaults to all tables.
+
+
+
+column
+
+
+The name of a specific column to analyze. Defaults to all columns.
+
+
+
+
+
+
+
+1998-10-04
+
+
+Outputs
+
+
+
+
+
+
+VACUUM
+
+
+
+The command has been accepted and the database is being cleaned.
+
+
+
+NOTICE: --Relation table--
+
+
+The report header for table.
+
+
+
+NOTICE: Pages 98: Changed 25, Reapped 74, Empty 0, New 0;
+ Tup 1000: Vac 3000, Crash 0, UnUsed 0, MinLen 188, MaxLen 188;
+ Re-using: Free/Avail. Space 586952/586952; EndEmpty/Avail. Pages 0/74.
+ Elapsed 0/0 sec.
+
+
+The analysis for table itself.
+
+
+
+NOTICE: Index index: Pages 28;
+ Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
+
+
+The analysis for an index on the target table.
+
+
+
+
+
+
+
+
+1998-10-04
+
+
+Description
+
+
+VACUUM serves two purposes in
+Postgres as both a means to reclaim storage and
+also a means to collect information for the optimizer.
+
+
+VACUUM opens every class in the database,
+cleans out records from rolled back transactions, and updates statistics in the
+system catalogs. The statistics maintained include the number of
+tuples and number of pages stored in all classes.
+
+Running VACUUM
+periodically will increase the speed of the database in processing user queries.
+
+
+
+1998-10-04
+
+
+Notes
+
+
+The open database is target for VACUUM.
+
+
+We recommend that active production databases be cleaned nightly, in order
+to keep statistics relatively current. The VACUUM
+query may be executed at any time, however. In particular, after
+copying a large class into Postgres
+or after deleting a large number of
+records, it may be a good idea to issue a VACUUM
+query. This will update the system catalogs with the results of all
+recent changes, and allow the Postgres
+query optimizer to make better choices in planning user queries.
+
+
+If the server crashes during a VACUUM command,
+chances are it will leave a lock file hanging around.
+Attempts to re-run the VACUUM command
+result in an error message about the creation of a lock file. If you
+are sure VACUUM is not running,
+remove the pg_vlock file in your
+database directory
+(i.e. PGDATA/base/dbname/pg_vlock).
+
+
+
+
+
+
+Usage
+
+
+The following is an example from running VACUUM on a table
+in the regression database:
+
+
+regression=> vacuum verbose analyze onek;
+NOTICE: --Relation onek--
+NOTICE: Pages 98: Changed 25, Reapped 74, Empty 0, New 0;
+ Tup 1000: Vac 3000, Crash 0, UnUsed 0, MinLen 188, MaxLen 188;
+ Re-using: Free/Avail. Space 586952/586952; EndEmpty/Avail. Pages 0/74.
+ Elapsed 0/0 sec.
+NOTICE: Index onek_stringu1: Pages 28; Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
+NOTICE: Index onek_hundred: Pages 12; Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
+NOTICE: Index onek_unique2: Pages 19; Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
+NOTICE: Index onek_unique1: Pages 17; Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
+NOTICE: Rel onek: Pages: 98 --> 25; Tuple(s) moved: 1000. Elapsed 0/1 sec.
+NOTICE: Index onek_stringu1: Pages 28; Tuples 1000: Deleted 1000. Elapsed 0/0 sec.
+NOTICE: Index onek_hundred: Pages 12; Tuples 1000: Deleted 1000. Elapsed 0/0 sec.
+NOTICE: Index onek_unique2: Pages 19; Tuples 1000: Deleted 1000. Elapsed 0/0 sec.
+NOTICE: Index onek_unique1: Pages 17; Tuples 1000: Deleted 1000. Elapsed 0/0 sec.
+VACUUM
+
+
+
+
+
+
+Compatibility
+
+
+
+
+
+1998-10-04
+
+
+SQL92
+
+
+There is no VACUUM statement in SQL92.
+
+