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