diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index 957c53f5b41f75bf6d0d154cc5aa11a57b337bf0..a5d2717185bd266f166df5602be1366d820c8662 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -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"> diff --git a/doc/src/sgml/ref/commands.sgml b/doc/src/sgml/ref/commands.sgml index 77fcccf2528432be86e0c9bd80bcf4b5f6e9b2e5..475041b628045deb6bad236fcb0eafa905ab8e8d 100644 --- a/doc/src/sgml/ref/commands.sgml +++ b/doc/src/sgml/ref/commands.sgml @@ -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> diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml new file mode 100644 index 0000000000000000000000000000000000000000..090f68ccdf0cbd66626d939f5809076f87b8fc33 --- /dev/null +++ b/doc/src/sgml/ref/createdb.sgml @@ -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> diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml new file mode 100644 index 0000000000000000000000000000000000000000..f06b3c025bb0b9f951a529eb7a73b6b4812be55b --- /dev/null +++ b/doc/src/sgml/ref/createuser.sgml @@ -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> diff --git a/doc/src/sgml/ref/destroydb.sgml b/doc/src/sgml/ref/destroydb.sgml new file mode 100644 index 0000000000000000000000000000000000000000..547cfee8809bbbea47443166d383a6012a3050c7 --- /dev/null +++ b/doc/src/sgml/ref/destroydb.sgml @@ -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> diff --git a/doc/src/sgml/ref/destroyuser.sgml b/doc/src/sgml/ref/destroyuser.sgml new file mode 100644 index 0000000000000000000000000000000000000000..aeda6a560e09367b8ebedf9c43cef7ead3ee8682 --- /dev/null +++ b/doc/src/sgml/ref/destroyuser.sgml @@ -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> diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml new file mode 100644 index 0000000000000000000000000000000000000000..dbbed5958e9794dd1c8de2b49774d19bf76ae44f --- /dev/null +++ b/doc/src/sgml/ref/initdb.sgml @@ -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> diff --git a/doc/src/sgml/ref/initlocation.sgml b/doc/src/sgml/ref/initlocation.sgml new file mode 100644 index 0000000000000000000000000000000000000000..7302118e86646a60b4e93b76d73c9a0c05122c36 --- /dev/null +++ b/doc/src/sgml/ref/initlocation.sgml @@ -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> diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml new file mode 100644 index 0000000000000000000000000000000000000000..89974eaa8da59b35129ef7ee45dc34ad3492f3fe --- /dev/null +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -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> diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml new file mode 100644 index 0000000000000000000000000000000000000000..089329334278415ba6e26a234b2d3203eceaa435 --- /dev/null +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -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> diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 863a2a82db2f4a13182d953950cdbc4de0501e6b..95832a7e4ec7a20cf86dd4dd7e1abe729ea75bec 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -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 diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml new file mode 100644 index 0000000000000000000000000000000000000000..bc5d7e7d5b6d88c63fea94ffda44ffce7e2dc062 --- /dev/null +++ b/doc/src/sgml/ref/vacuum.sgml @@ -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>