database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-04-24 10:47:04 +03:00
Code

Add new information for utility commands.

Browse Source 
Haven't yet done cleardbdir, ipcclean, pg_passwd, and pg_upgrade.
Add reference info for the SQL VACUUM command (oops, forgot it earlier).
This commit is contained in:
Thomas G. Lockhart 1998-10-05 02:54:45 +00:00
parent a54ba52101
commit 37d2f76ef7
12 changed files with 2195 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/src/sgml/ref/allfiles.sgml
View File

@ -110,4 +110,12 @@
<!entity vacuum system "vacuum.sgml">
<!-- these are in the "utilities" reference chapter -->
<!entity createdb system "createdb.sgml">
<!entity createuser system "createuser.sgml">
<!entity destroydb system "destroydb.sgml">
<!entity destroyuser system "destroyuser.sgml">
<!entity initdb system "initdb.sgml">
<!entity initlocation system "initlocation.sgml">
<!entity pgDump system "pg_dump.sgml">
<!entity pgDumpall system "pg_dumpall.sgml">
<!entity psqlRef system "psql-ref.sgml">

9
doc/src/sgml/ref/commands.sgml
View File

@ -58,6 +58,7 @@ commands supported by <productname>Postgres</productname>.
&set;
&show;
&update;
&vacuum;
</Chapter>
@ -84,6 +85,14 @@ This is reference information for the
<productname>Postgres</productname> support utilities.
</para>
&createdb;
&createuser;
&destroydb;
&destroyuser;
&initdb;
&initlocation;
&pgDump;
&pgDumpall;
&psqlRef;
</chapter>

221
doc/src/sgml/ref/createdb.sgml Normal file
View File

@ -0,0 +1,221 @@
<REFENTRY ID="APP-CREATEDB">
<REFMETA>
<REFENTRYTITLE>
<application>createdb</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>createdb</application>
</REFNAME>
<REFPURPOSE>
Create a new <productname>Postgres</productname> database
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
createdb [ <replaceable class="parameter">dbname</replaceable> ]
createdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
[ -D <replaceable class="parameter">datadir</replaceable> ]
[ -u ] [ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-CREATEDB-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
<varlistentry>
<term>
-D <replaceable class="parameter">datadir</replaceable>
</term>
<listitem>
<para>
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.
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be created. The name must be
unique among all <productname>Postgres</productname> databases in this installation.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.
</variablelist>
<REFSECT2 ID="R2-APP-CREATEDB-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>createdb</application> will create files in the
<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
data area for the new database.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
<application>createdb</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
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.
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
<varlistentry>
<term>
ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You do not have permission to create new databases.
Contact your <productname>Postgres</productname> site administrator.
<varlistentry>
<term>
ERROR: createdb: database '<replaceable class="parameter">dbname</replaceable>' already exists.
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
The database already exists.
<varlistentry>
<term>
createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</variablelist>
<note>
<para>
<application>createdb</application> internally runs
CREATE DATABASE from <application>psql</application>
while connected to the <literal>template1</literal> database.
</note>
<REFSECT1 ID="R1-APP-CREATEDB-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>createdb</application> creates a new
<productname>Postgres</productname> database.
The person who executes this command becomes
the database administrator, or <acronym>DBA</acronym>,
for this database and is the only
person, other than the <productname>Postgres</productname> super-user,
who can destroy it.
<para>
<application>createdb</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>createdb</application>
is executed. The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
<REFSECT1 ID="R1-APP-CREATEDB-2">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To create the database <literal>demo</literal>
using the postmaster on the local host, port 5432:
<programlisting>
createdb demo
</programlisting>
To create the database <literal>demo</literal>
using the postmaster on host eden, port 5000:
<programlisting>
createdb -p 5000 -h eden demo
</programlisting>
</REFENTRY>

237
doc/src/sgml/ref/createuser.sgml Normal file
View File

@ -0,0 +1,237 @@
<REFENTRY ID="APP-CREATEUSER">
<REFMETA>
<REFENTRYTITLE>
<application>createuser</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>createuser</application>
</REFNAME>
<REFPURPOSE>
Create a new <productname>Postgres</productname> user
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
createuser [ <replaceable class="parameter">username</replaceable> ]
createuser [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
[ -i <replaceable class="parameter">userid</replaceable> ]
[ -d | -D ] [ -u | -U ] [ <replaceable class="parameter">username</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-CREATEUSER-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
-d
</term>
<listitem>
<para>
Allows the user to create databases.
<varlistentry>
<term>
-D
</term>
<listitem>
<para>
Forbids the user to create databases.
<varlistentry>
<term>
-i <replaceable class="parameter">userid</replaceable>
</term>
<listitem>
<para>
Specifies the numeric identifier to be associated with this user.
This identifier must be unique among all <productname>Postgres</productname> 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.
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Allows the user to create other users.
<varlistentry>
<term>
-U
</term>
<listitem>
<para>
Forbids the user to create other users.
<varlistentry>
<term>
<replaceable class="parameter">username</replaceable>
</term>
<listitem>
<para>
Specifies the name of the <productname>Postgres</productname> user to be created.
This name must be unique among all <productname>Postgres</productname> users.
You will be prompted for a name if none is specified on the command line.
</variablelist>
<REFSECT2 ID="R2-APP-CREATEUSER-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>createuser</application> will add an entry in the
<literal>pg_user</literal> or <literal>pg_shadow</literal> system table.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
createuser: database access failed.
<listitem>
<para>
<application>createuser</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
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.
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
createuser: database access failed.
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>. Contact your
<productname>Postgres</productname> administrator.
<varlistentry>
<term>
createuser: <replaceable class="parameter">username</replaceable> cannot create users.
<listitem>
<para>
You do not have permission to create new users; contact your
<productname>Postgres</productname> site administrator.
<varlistentry>
<term>
createuser: user "<replaceable class="parameter">username</replaceable>" already exists
<listitem>
<para>
The user to be added already has an entry in the <literal>pg_shadow</literal>
class.
<varlistentry>
<term>
database access failed
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</variablelist>
<note>
<para>
<application>createuser</application> internally runs
CREATE USER from <application>psql</application>
while connected to the <literal>template1</literal> database.
</note>
<REFSECT1 ID="R1-APP-CREATEUSER-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>createuser</application> creates a
new <productname>Postgres</productname> user.
Only users with <literal>usesuper</literal> set in
the <literal>pg_shadow</literal> class can create
new <productname>Postgres</productname> users. As shipped,
the user <literal>postgres</literal> can create users.
<para>
<application>createuser</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>createuser</application> is executed.
The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="app-psql">.
Once invoked, <application>createuser</application>
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.
<note>
<para>
The <productname>Postgres</productname> user identifier
does not need to be the same as the user's Unix UID. However, typically
they are assigned to be the same.
</note>
<para>
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 <productname>Postgres</productname> super-user,
whether the new user may create new databases and whether the new user
is allowed to create other new users.
</REFENTRY>

224
doc/src/sgml/ref/destroydb.sgml Normal file
View File

@ -0,0 +1,224 @@
<REFENTRY ID="APP-DESTROYDB">
<REFMETA>
<REFENTRYTITLE>
<application>destroydb</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>destroydb</application>
</REFNAME>
<REFPURPOSE>
Create a new <productname>Postgres</productname> database
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
destroydb [ <replaceable class="parameter">dbname</replaceable> ]
destroydb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
[ -i ] [ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-DESTROYDB-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
-i
</term>
<listitem>
<para>
Run in interactive mode.
Prompts for confirmation before destroying a database.
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be destroyed. The database
must be one of the existing <productname>Postgres</productname> databases
in this installation.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.
</variablelist>
<REFSECT2 ID="R2-APP-DESTROYDB-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>destroydb</application> will remove files from the
<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
data area for the existing database.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
<application>destroydb</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
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.
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
<varlistentry>
<term>
ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You do not have permission to destroy (or create) databases.
Contact your <productname>Postgres</productname> site administrator.
<varlistentry>
<term>
ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' does not exist.
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
The database to be removed does not have an entry in the
<literal>pg_database</literal> class.
<varlistentry>
<term>
ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' is not owned by you.
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
You are not the Database Administrator (DBA) for the specified database.
<varlistentry>
<term>
destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
</variablelist>
<note>
<para>
<application>destroydb</application> internally runs
<command>DESTROY DATABASE</command> from <application>psql</application>
while connected to the <literal>template1</literal> database.
</note>
<REFSECT1 ID="R1-APP-DESTROYDB-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>destroydb</application> destroys an existing
<productname>Postgres</productname> database.
The person who executes this command must be
the database administrator, or <acronym>DBA</acronym>,
or must be the <productname>Postgres</productname> super-user.
The program runs silently; no confirmation message will be displayed.
After the database is destroyed, a Unix shell prompt will reappear.
<para>
All references to
the database are removed, including the directory containing this
database and its associated files.
<para>
<application>destroydb</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>destroydb</application>
is executed. The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
<REFSECT1 ID="R1-APP-DESTROYDB-2">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To destroy the database <literal>demo</literal>
using the postmaster on the local host, port 5432:
<programlisting>
destroydb demo
</programlisting>
<para>
To destroy the database <literal>demo</literal>
using the postmaster on host eden, port 5000:
<programlisting>
destroydb -p 5000 -h eden demo
</programlisting>
</REFENTRY>

200
doc/src/sgml/ref/destroyuser.sgml Normal file
View File

@ -0,0 +1,200 @@
<REFENTRY ID="APP-DESTROYUSER">
<REFMETA>
<REFENTRYTITLE>
<application>destroyuser</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>destroyuser</application>
</REFNAME>
<REFPURPOSE>
Destroy a <productname>Postgres</productname> user and associated databases
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
destroyuser [ <replaceable class="parameter">username</replaceable> ]
destroyuser [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
[ <replaceable class="parameter">username</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-DESTROYUSER-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
<replaceable class="parameter">username</replaceable>
</term>
<listitem>
<para>
Specifies the name of the <productname>Postgres</productname> user to be removed.
This name must exist in the <productname>Postgres</productname> installation.
You will be prompted for a name if none is specified on the command line.
</variablelist>
<REFSECT2 ID="R2-APP-DESTROYUSER-2">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>destroyuser</application> will remove an entry in the
<literal>pg_user</literal> or <literal>pg_shadow</literal> system table,
and will remove all databases for which that user is the administrator
(<acronym>DBA</acronym>).
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
destroyuser: database access failed.
<listitem>
<para>
<application>destroyuser</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
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.
<varlistentry>
<term>
Connection to database 'template1' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
destroyuser: database access failed.
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>. Contact your
<productname>Postgres</productname> administrator.
<varlistentry>
<term>
destroyuser: <replaceable class="parameter">username</replaceable> cannot delete users.
<listitem>
<para>
You do not have permission to delete users; contact your
<productname>Postgres</productname> site administrator.
<varlistentry>
<term>
destroyuser: user "<replaceable class="parameter">username</replaceable>" already exists
<listitem>
<para>
The user to be added already has an entry in the <literal>pg_shadow</literal>
class.
<varlistentry>
<term>
database access failed
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. Ensure that your site administrator has
properly installed <productname>Postgres</productname>and initialized the site with
<application>initdb</application>.
<varlistentry>
<term>
destroydb on <replaceable class="parameter">dbname</replaceable> failed - exiting
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server. There was possibly a Unix permissions problem with the
specified database.
<varlistentry>
<term>
delete of user <replaceable class="parameter">username</replaceable> was UNSUCCESSFUL
<listitem>
<para>
An internal error occurred in <application>psql</application>
or in the backend server.
</variablelist>
<note>
<para>
<application>destroyuser</application> internally runs
DROP USER from <application>psql</application>
while connected to the <literal>template1</literal> database.
</note>
<REFSECT1 ID="R1-APP-DESTROYUSER-1">
<REFSECT1INFO>
<DATE>1998-10-02</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>destroyuser</application> removes an existing
<productname>Postgres</productname> user
and the databases for which that user
is database administrator.
Only users with <literal>usesuper</literal> set in
the <literal>pg_shadow</literal> class can destroy
<productname>Postgres</productname> users. As shipped,
the user <literal>postgres</literal> can remove users.
<para>
<application>destroyuser</application> is a shell script that invokes
<application>psql</application>.
Hence, a <application>postmaster</application>
process must be running on the database server host before
<application>destroyuser</application> is executed.
The
<envar>PGOPTION</envar>
and
<envar>PGREALM</envar>
environment variables will be passed on to
<application>psql</application>
and processed as described in <xref linkend="app-psql" endterm="app-psql">.
<para>
Once invoked, <application>destroyuser</application>
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.
</REFENTRY>

278
doc/src/sgml/ref/initdb.sgml Normal file
View File

@ -0,0 +1,278 @@
<REFENTRY ID="APP-INITDB">
<REFMETA>
<REFENTRYTITLE>
<application>initdb</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>initdb</application>
</REFNAME>
<REFPURPOSE>
Create a new <productname>Postgres</productname> database installation
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
initdb [ --pgdata=<replaceable class="parameter">dbdir</replaceable> | -r <replaceable class="parameter">dbdir</replaceable> ]
[ --pglib=<replaceable class="parameter">libdir</replaceable> | -l <replaceable class="parameter">libdir</replaceable> ]
[ --template=<replaceable class="parameter">template</replaceable> | -t <replaceable class="parameter">template</replaceable> ]
[ --username=<replaceable class="parameter">name</replaceable> | -u <replaceable class="parameter">name</replaceable> ]
[ --noclean | -n ] [ --debug | -d ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-INITDB-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
--pglib=<replaceable class="parameter">libdir</replaceable>
</term>
<term>
-l <replaceable class="parameter">libdir</replaceable>
</term>
<term>
<envar>PGLIB</envar>
<listitem>
<para>
Where are the files that make up <productname>Postgres</productname>?
Apart from files that
have to go in particular directories because of their function, the
files that make up the <productname>Postgres</productname> software
were installed in a directory
called the <replaceable class="parameter">libdir</replaceable> directory.
An example of a file that will be found
there that <application>initdb</application>
needs is <filename>global1.bki.source</filename>,
which contains all the information that goes
into the shared catalog tables.
<varlistentry>
<term>
--pgdata=<replaceable class="parameter">dbdir</replaceable>
</term>
<term>
-r <replaceable class="parameter">dbdir</replaceable>
</term>
<term>
<envar>PGDATA</envar>
</term>
<listitem>
<para>
Where in your Unix filesystem do you want the database data to go?
The top level directory is called the <envar>PGDATA</envar> directory.
<varlistentry>
<term>
--username=<replaceable class="parameter">name</replaceable>
</term>
<term>
-u <replaceable class="parameter">name</replaceable>
</term>
<term>
<envar>PGUSER</envar>
</term>
<listitem>
<para>
Who will be the <productname>Postgres</productname> superuser
for this database system? The
<productname>Postgres</productname> 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
<application>initdb</application>).
<note>
<para>
Only the Unix superuser can create a database system with a
different user as <productname>Postgres</productname> superuser.
</note>
</variablelist>
<para>
Other, less commonly used, parameters are also available:
<variablelist>
<varlistentry>
<term>
--template=<replaceable class="parameter">template</replaceable>
</term>
<term>
-t <replaceable class="parameter">template</replaceable>
</term>
<listitem>
<para>
Replace the <literal>template1</literal>
database in an existing database system, and don't touch anything else.
This is useful when you need to upgrade your <literal>template1</literal>
database using <application>initdb</application>
from a newer release of <productname>Postgres</productname>,
or when your <literal>template1</literal>
database has become corrupted by some system problem. Normally the
contents of <literal>template1</literal>
remain constant throughout the life of the database system. You can't
destroy anything by running <application>initdb</application>
with the
<option>--template</option>
option.
<varlistentry>
<term>
--noclean
</term>
<term>
-n
</term>
<listitem>
<para>
By default, when <application>initdb</application>
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.
<varlistentry>
<term>
--debug
</term>
<term>
-d
</term>
<listitem>
<para>
Print debugging output from the bootstrap backend.
The bootstrap backend is the program <application>initdb</application>
uses to create the catalog tables. This option generates a tremendous
amount of output. It also turns off the final vacuuming step.
</variablelist>
<para>
Files are also input to <application>initdb</application>:
<variablelist>
<varlistentry>
<term>
<application>postconfig</application>
</term>
<listitem>
<para>
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.
<varlistentry>
<term>
<filename><envar>PGLIB</envar>/global1.bki.source</filename>
</term>
<listitem>
<para>
Contents for the shared catalog tables in the new database system. This
file is part of the <productname>Postgres</productname> software.
<varlistentry>
<term>
<filename><envar>PGLIB</envar>/local1_template1.bki.source</filename>
</term>
<listitem>
<para>
Contents for the template1 tables in the new database system. This
file is part of the <productname>Postgres</productname> software.
</variablelist>
<REFSECT2 ID="R2-APP-INITDB-2">
<REFSECT2INFO>
<DATE>1998-09-26</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>initdb</application> will create files in the <envar>PGDATA</envar>
data area which are the system tables and framework for a complete
installation.
<REFSECT1 ID="R1-APP-INITDB-1">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>initdb</application> creates a new
<productname>Postgres</productname> 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.
<para>
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 <literal>template1</literal>
database. What is the <literal>template1</literal>
database? When you create a database, <productname>Postgres</productname>
does it by copying
everything from the <literal>template1</literal>
database. It contains catalog tables filled in for things like the
builtin types.
<para>
After <application>initdb</application>
creates the database, it completes the initialization by running
<application>vacuum</application>, which resets some optimization parameters.
<para>
There are three ways to give parameters to <application>initdb</application>.
First, you can use <application>initdb</application> command options.
Second, you can set environment
variables before invoking <application>initdb</application>.
Third, you can have a program called <application>postconfig</application>
in your Unix command search path.
<application>initdb</application> invokes that program and that program then writes
<application>initdb</application> parameters to its standard output stream.
This third option is not a common thing to do, however.
<para>
Command options always override parameters specified any other way.
The values returned by <application>postconfig</application>
override any environment variables, but your
<application>postconfig</application>
program may base its output on the environment variables if you want
their values to be used.
<para>
The value that <application>postconfig</application>
outputs must have the format
<programlisting>
<replaceable>var1</replaceable>=<replaceable class="parameter">value1</replaceable> <replaceable>var2</replaceable>=<replaceable class="parameter">value2</replaceable> ...
</programlisting>
It can output nothing if it doesn't want to supply any parameters.
The <replaceable>var</replaceable> values are equal to
the corresponding environment variable
names. For example,
<programlisting>
PGDATA=/tmp/postgres_test
</programlisting>
has the
same effect as invoking <application>initdb</application>
with an environment variable called <envar>PGDATA</envar> whose value is
<filename>/tmp/postgres_test</filename>.
</REFENTRY>

201
doc/src/sgml/ref/initlocation.sgml Normal file
View File

@ -0,0 +1,201 @@
<REFENTRY ID="APP-INITLOCATION">
<REFMETA>
<REFENTRYTITLE>
<application>initlocation</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>initlocation</application>
</REFNAME>
<REFPURPOSE>
Create a secondary <productname>Postgres</productname> database storage area
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
initlocation [ --location=<replaceable class="parameter">altdir</replaceable> | -D <replaceable class="parameter">altdir</replaceable> ]
[ --username=<replaceable class="parameter">name</replaceable> | -u <replaceable class="parameter">name</replaceable> ]
[ <replaceable class="parameter">altdir</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-INITLOCATION-1">
<REFSECT2INFO>
<DATE>1998-10-02</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<variablelist>
<varlistentry>
<term>
--location=<replaceable class="parameter">altdir</replaceable>
</term>
<term>
-D <replaceable class="parameter">altdir</replaceable>
</term>
<term>
<replaceable class="parameter">altdir</replaceable>
</term>
<listitem>
<para>
Where in your Unix filesystem do you want alternate databases to go?
The top level directory is called the <envar>PGDATA</envar> directory, so you
might want to point your first alternate location at <envar>PGDATA2</envar>.
<varlistentry>
<term>
--username=<replaceable class="parameter">name</replaceable>
</term>
<term>
-u <replaceable class="parameter">name</replaceable>
</term>
<term>
<envar>PGUSER</envar>
</term>
<listitem>
<para>
Who will be the Unix filesystem owner of this database storage area?
The
<productname>Postgres</productname> 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 <application>initlocation</application>
and who will thus have ownership of the directories and files.
<note>
<para>
Only the Unix superuser can create a database system with a
different user as the <productname>Postgres</productname> superuser.
Specifying a user other than the <productname>Postgres</productname> superuser
may lead to database security and data integrity problems. Refer to the
<citetitle><productname>PostgreSQL</productname> Administrator's Guide</citetitle>
for more information.
</note>
</variablelist>
<REFSECT2 ID="R2-APP-INITLOCATION-2">
<REFSECT2INFO>
<DATE>1998-09-26</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>initlocation</application> will create directories in
the specified place.
<variablelist>
<varlistentry>
<term>
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 <replaceable class="parameter">altdir</replaceable>
Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
</term>
<listitem>
<para>
Successful completion.
<varlistentry>
<term>
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 `<replaceable class="parameter">altdir</replaceable>': Permission denied
</term>
<listitem>
<para>
You do not have filesystem permission to write to the specified directory area.
<varlistentry>
<term>
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.
</term>
<listitem>
<para>
The username which you have specified is not the
<productname>Postgres</productname> superuser.
<varlistentry>
<term>
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
</term>
<listitem>
<para>
Specify the <option>--username</option> command line option.
</variablelist>
<REFSECT1 ID="R1-APP-INITLOCATION-1">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>initlocation</application>
creates a new <productname>Postgres</productname> secondary database storage area.
A secondary storage area contains a required tree of directories with
the correct file permissions on those directories.
<para>
Creating a database storage area consists of creating the directories in which
database data might live.
<para>
There are two kinds of arguments for <application>initlocation</application>.
First, you can specify an environment variable (e.g. <envar>PGDATA2</envar>).
This environment variable should be known to the backend for later use in
<command>CREATE DATABASE/WITH LOCATION</command>
or
<command>createdb -D <replaceable class="parameter">altdir</replaceable></command>.
However, <emphasis>the backend daemon must have this variable in it's
environment</emphasis> 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
<productname>Postgres</productname> installation. It is usually disabled
to alleviate security and data integrity concerns.
<note>
<para>
<productname>Postgres</productname> will add <filename>/base/</filename>
to the specified path to create the storage area.
<para>
The backend requires that any argument to <option>WITH LOCATION</option> which is
in all uppercase and which has no path delimiters is an environment variable.
</note>
<REFSECT1 ID="R1-APP-INITLOCATION-2">
<REFSECT1INFO>
<DATE>1998-09-26</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To create a database in an alternate location, using an environment variable:
<programlisting>
% setenv PGDATA2 /opt/postgres/data
% initlocation PGDATA2
% createdb -D PGDATA2
</programlisting>
</REFENTRY>

332
doc/src/sgml/ref/pg_dump.sgml Normal file
View File

@ -0,0 +1,332 @@
<REFENTRY ID="APP-PG-DUMP">
<REFMETA>
<REFENTRYTITLE>
<application>pg_dump</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME id="pg-dump">
<application>pg_dump</application>
</REFNAME>
<REFPURPOSE>
Extract a <productname>Postgres</productname> database into a script file
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-04</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_dump [ <replaceable class="parameter">dbname</replaceable> ]
pg_dump [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
[ -t <replaceable class="parameter">table</replaceable> ]
[ -f <replaceable class="parameter">outputfile</replaceable> ]
[ -a ] [ -d ] [ -D ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
[ <replaceable class="parameter">dbname</replaceable> ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-PG-DUMP-1">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<application>pg_dump</application> accepts the following command line arguments:
<variablelist>
<varlistentry>
<term>
<replaceable class="parameter">dbname</replaceable>
</term>
<listitem>
<para>
Specifies the name of the database to be extracted.
<replaceable class="parameter">dbname</replaceable>
defaults to the value of the
<envar>USER</envar>
environment variable.
<varlistentry>
<term>
-a
</term>
<listitem>
<para>
Dump out only the data, no schema (definitions).
<varlistentry>
<term>
-d
</term>
<listitem>
<para>
Dump data as proper insert strings.
<varlistentry>
<term>
-D
</term>
<listitem>
<para>
Dump data as inserts with attribute names
<varlistentry>
<term>
-f <replaceable class="parameter">filename</replaceable>
</term>
<listitem>
<para>
Specifies the output file. Defaults to <filename>stdout</filename>.
<varlistentry>
<term>
-n
</term>
<listitem>
<para>
Suppress double quotes around identifiers unless absolutely necessary.
This may cause trouble loading this dumped data if there are reserved words
used for identifiers.
<varlistentry>
<term>
-o
</term>
<listitem>
<para>
Dump object identifiers (<acronym>OID</acronym>s) for every table.
<varlistentry>
<term>
-s
</term>
<listitem>
<para>
Dump out only the schema (definitions), no data.
<varlistentry>
<term>
-t <replaceable class="parameter">table</replaceable>
</term>
<listitem>
<para>
Dump data for <replaceable class="parameter">table</replaceable> only.
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication. Prompts for username and password.
<varlistentry>
<term>
-v
</term>
<listitem>
<para>
Specifies verbose mode
<varlistentry>
<term>
-z
</term>
<listitem>
<para>
Include ACLs (grant/revoke commands) and table ownership information.
</variablelist>
<para>
<application>pg_dump</application> also accepts
the following command line arguments for connection parameters:
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
</variablelist>
<REFSECT2 ID="R2-APP-PG-DUMP-2">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>pg_dump</application> will create a file or
write to <filename>stdout</filename>.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
<listitem>
<para>
<application>pg_dump</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
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.
<varlistentry>
<term>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
<varlistentry>
<term>
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
<listitem>
<para>
You do not have permission to read the database.
Contact your <productname>Postgres</productname> site administrator.
</variablelist>
<note>
<para>
<application>pg_dump</application> internally executes
<command>SELECT</command> statements. If you have problems running
<application>pg_dump</application>,
make sure you are able to select information from the database using, for
example, <application>psql</application>.
</note>
<REFSECT1 ID="R1-APP-PG-DUMP-1">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>pg_dump</application> is a utility for dumping out a
<productname>Postgres</productname> 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.
<application>pg_dump</application>
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.
<para>
<application>pg_dump</application>
is useful for dumping out the contents of a database to move from one
<productname>Postgres</productname> installation to another. After running
<application>pg_dump</application>,
one should examine the output script file for any warnings, especially
in light of the limitations listed below.
<REFSECT1 ID="R1-APP-PG-DUMP-2">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Notes
</TITLE>
<PARA>
<application>pg_dump</application> has a few limitations.
The limitations mostly stem from
difficulty in extracting certain meta-information from the system
catalogs.
<variablelist>
<varlistentry>
<term>
rules and views
<listitem>
<para>
<application>pg_dump</application>
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).
<varlistentry>
<term>
partial indices
<listitem>
<para>
<application>pg_dump</application>
does not understand partial indices. The reason is
the same as above; partial index predicates are stored as plans.
<varlistentry>
<term>
large objects
<listitem>
<para>
<application>pg_dump</application> does not handle large objects.
Large objects are ignored and must be dealt with manually.
</variablelist>
<REFSECT1 ID="R1-APP-PG-DUMP-3">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To dump a database of the same name as the user:
<programlisting>
% pg_dump > db.out
</programlisting>
<para>
To reload this database:
<programlisting>
psql -e database < db.out
</programlisting>
</REFENTRY>

267
doc/src/sgml/ref/pg_dumpall.sgml Normal file
View File

@ -0,0 +1,267 @@
<REFENTRY ID="APP-PG-DUMPALL">
<REFMETA>
<REFENTRYTITLE>
<application>pg_dumpall</application>
</REFENTRYTITLE>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<application>pg_dumpall</application>
</REFNAME>
<REFPURPOSE>
Extract all <productname>Postgres</productname> databases into a script file
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-04</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_dumpall
pg_dumpall [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
[ -a ] [ -d ] [ -D ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
</SYNOPSIS>
<REFSECT2 ID="R2-APP-PG-DUMPALL-1">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<application>pg_dumpall</application> accepts the following command line arguments:
<variablelist>
<varlistentry>
<term>
-a
</term>
<listitem>
<para>
Dump out only the data, no schema (definitions).
<varlistentry>
<term>
-d
</term>
<listitem>
<para>
Dump data as proper insert strings.
<varlistentry>
<term>
-D
</term>
<listitem>
<para>
Dump data as inserts with attribute names
<varlistentry>
<term>
-n
</term>
<listitem>
<para>
Suppress double quotes around identifiers unless absolutely necessary.
This may cause trouble loading this dumped data if there are reserved words
used for identifiers.
<varlistentry>
<term>
-o
</term>
<listitem>
<para>
Dump object identifiers (<acronym>OID</acronym>s) for every table.
<varlistentry>
<term>
-s
</term>
<listitem>
<para>
Dump out only the schema (definitions), no data.
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication. Prompts for username and password.
<varlistentry>
<term>
-v
</term>
<listitem>
<para>
Specifies verbose mode
<varlistentry>
<term>
-z
</term>
<listitem>
<para>
Include ACLs (grant/revoke commands) and table ownership information.
</variablelist>
<para>
<application>pg_dumpall</application> also accepts
the following command line arguments for connection parameters:
<variablelist>
<varlistentry>
<term>
-h <replaceable class="parameter">host</replaceable>
</term>
<listitem>
<para>
Specifies the hostname of the machine on which the
<application>postmaster</application>
is running. Defaults to using a local Unix domain socket
rather than an IP connection..
<varlistentry>
<term>
-p <replaceable class="parameter">port</replaceable>
</term>
<listitem>
<para>
Specifies the Internet TCP/IP port or local Unix domain socket file
extension on which the <application>postmaster</application>
is listening for connections. The port number defaults to 5432,
or the value of the <envar>PGPORT</envar>
environment variable (if set).
<varlistentry>
<term>
-u
</term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
</variablelist>
<REFSECT2 ID="R2-APP-PG-DUMPALL-2">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<application>pg_dumpall</application> will create a file or
write to <filename>stdout</filename>.
<variablelist>
<varlistentry>
<term>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
<listitem>
<para>
<application>pg_dumpall</application> could not attach to the
<application>postmaster</application>
process on the specified host and port. If you see this message,
ensure that the <application>postmaster</application>
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.
<varlistentry>
<term>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
<listitem>
<para>
You do not have a valid entry in the relation <literal>pg_shadow</literal>
and and will not be allowed to access <productname>Postgres</productname>.
Contact your <productname>Postgres</productname> administrator.
<varlistentry>
<term>
dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
<listitem>
<para>
You do not have permission to read the database.
Contact your <productname>Postgres</productname> site administrator.
</variablelist>
<note>
<para>
<application>pg_dumpall</application> internally executes
<command>SELECT</command> statements. If you have problems running
<application>pg_dumpall</application>,
make sure you are able to select information from the database using, for
example, <application>psql</application>.
</note>
<REFSECT1 ID="R1-APP-PG-DUMPALL-1">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<application>pg_dumpall</application>
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.
<application>pg_dumpall</application> includes in this file the proper commands
to automatically create each dumped database before loading.
<para>
<application>pg_dumpall</application> takes all <application>pg_dump</application>
options, but <option>-f</option>, <option>-t</option> and
<replaceable class="parameter">dbname</replaceable>
should be omitted.
<para>
Refer to
<xref linkend="app-pg-dump" endterm="pg-dump">
for more information on this capability.
<REFSECT1 ID="R1-APP-PG-DUMPALL-2">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Usage
</TITLE>
<PARA>
To dump all databases:
<programlisting>
% pg_dumpall -o > db.out
</programlisting>
<tip>
<para>
You can use most <application>pg_dump</application> options
for <application>pg_dumpall</application>.
</tip>
<para>
To reload this database:
<programlisting>
psql -e template1 < db.out
</programlisting>
<tip>
<para>
You can use most <application>psql</application> options
when reloading.
</tip>
</REFENTRY>

3
doc/src/sgml/ref/psql-ref.sgml
View File

@ -6,7 +6,7 @@
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
<REFNAME id="psql-ref">
<application>psql</application>
</REFNAME>
<REFPURPOSE>
@ -177,7 +177,6 @@ any reason.
Description
</TITLE>
<PARA>
<application>psql</application> is a character-based front-end to
<productname>Postgres</productname>.
It enables you to

217
doc/src/sgml/ref/vacuum.sgml Normal file
View File

@ -0,0 +1,217 @@
<REFENTRY ID="SQL-VACUUM-1">
<REFMETA>
<REFENTRYTITLE>
VACUUM
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
VACUUM
</REFNAME>
<REFPURPOSE>
Clean and analyze a <productname>Postgres</productname> database
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-04</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
VACUUM [ VERBOSE ] [ ANALYZE ] [ <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ]
VACUUM [ VERBOSE ] ANALYZE [ <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [ (<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ] ]
</SYNOPSIS>
<REFSECT2 ID="R2-SQL-VACUUM-1">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
VERBOSE
<LISTITEM>
<PARA>
Prints a detailed vacuum activity report for each table.
<VARLISTENTRY>
<TERM>
ANALYZE
<LISTITEM>
<PARA>
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.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
<LISTITEM>
<PARA>
The name of a specific table to vacuum. Defaults to all tables.
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
<LISTITEM>
<PARA>
The name of a specific column to analyze. Defaults to all columns.
</VARIABLELIST>
</REFSECT2>
<REFSECT2 ID="R2-SQL-VACUUM-2">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<ReturnValue>VACUUM</ReturnValue>
</TERM>
<LISTITEM>
<PARA>
The command has been accepted and the database is being cleaned.
<VARLISTENTRY>
<TERM>
NOTICE: --Relation <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>--
<LISTITEM>
<PARA>
The report header for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>.
<VARLISTENTRY>
<TERM>
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.
<LISTITEM>
<PARA>
The analysis for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> itself.
<VARLISTENTRY>
<TERM>
NOTICE: Index <REPLACEABLE CLASS="PARAMETER">index</REPLACEABLE>: Pages 28;
Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
<LISTITEM>
<PARA>
The analysis for an index on the target table.
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>
<REFSECT1 ID="R1-SQL-VACUUM-1">
<REFSECT1INFO>
<DATE>1998-10-04</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
<command>VACUUM</command> serves two purposes in
<productname>Postgres</productname> as both a means to reclaim storage and
also a means to collect information for the optimizer.
<para>
<command>VACUUM</command> 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 <command>VACUUM</command>
periodically will increase the speed of the database in processing user queries.
<REFSECT2 ID="R2-SQL-VACUUM-3">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
The open database is target for <command>VACUUM</command>.
<para>
We recommend that active production databases be cleaned nightly, in order
to keep statistics relatively current. The <command>VACUUM</command>
query may be executed at any time, however. In particular, after
copying a large class into <productname>Postgres</productname>
or after deleting a large number of
records, it may be a good idea to issue a <command>VACUUM</command>
query. This will update the system catalogs with the results of all
recent changes, and allow the <productname>Postgres</productname>
query optimizer to make better choices in planning user queries.
<para>
If the server crashes during a <command>VACUUM</command> command,
chances are it will leave a lock file hanging around.
Attempts to re-run the <command>VACUUM</command> command
result in an error message about the creation of a lock file. If you
are sure <command>VACUUM</command> is not running,
remove the <filename>pg_vlock</filename> file in your
database directory
(i.e. <filename><envar>PGDATA</envar>/base/dbname/pg_vlock</filename>).
</PARA>
</REFSECT2>
<REFSECT1 ID="R1-SQL-VACUUM-2">
<TITLE>
Usage
</TITLE>
<PARA>
The following is an example from running <command>VACUUM</command> on a table
in the regression database:
<ProgramListing>
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
</ProgramListing>
</REFSECT1>
<REFSECT1 ID="R1-SQL-VACUUM-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
<REFSECT2 ID="R2-SQL-VACUUM-4">
<REFSECT2INFO>
<DATE>1998-10-04</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
There is no <COMMAND>VACUUM</COMMAND> statement in SQL92.
</REFENTRY>