diff options
Diffstat (limited to 'doc/src/sgml/man1')
35 files changed, 20019 insertions, 0 deletions
diff --git a/doc/src/sgml/man1/clusterdb.1 b/doc/src/sgml/man1/clusterdb.1 new file mode 100644 index 0000000..4e12348 --- /dev/null +++ b/doc/src/sgml/man1/clusterdb.1 @@ -0,0 +1,252 @@ +'\" t +.\" Title: clusterdb +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "CLUSTERDB" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +clusterdb \- cluster a PostgreSQL database +.SH "SYNOPSIS" +.HP \w'\fBclusterdb\fR\ 'u +\fBclusterdb\fR [\fIconnection\-option\fR...] [\fB\-\-verbose\fR | \fB\-v\fR] [\ \fB\-\-table\fR\ |\ \fB\-t\fR\ \fItable\fR\ ]... [\fIdbname\fR] +.HP \w'\fBclusterdb\fR\ 'u +\fBclusterdb\fR [\fIconnection\-option\fR...] [\fB\-\-verbose\fR | \fB\-v\fR] \fB\-\-all\fR | \fB\-a\fR +.SH "DESCRIPTION" +.PP +clusterdb +is a utility for reclustering tables in a +PostgreSQL +database\&. It finds tables that have previously been clustered, and clusters them again on the same index that was last used\&. Tables that have never been clustered are not affected\&. +.PP +clusterdb +is a wrapper around the SQL command +\fBCLUSTER\fR(7)\&. There is no effective difference between clustering databases via this utility and via other methods for accessing the server\&. +.SH "OPTIONS" +.PP +clusterdb +accepts the following command\-line arguments: +.PP +\fB\-a\fR +.br +\fB\-\-all\fR +.RS 4 +Cluster all databases\&. +.RE +.PP +\fB[\-d]\fR\fB \fR\fB\fIdbname\fR\fR +.br +\fB[\-\-dbname=]\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to be clustered, when +\fB\-a\fR/\fB\-\-all\fR +is not used\&. If this is not specified, the database name is read from the environment variable +\fBPGDATABASE\fR\&. If that is not set, the user name specified for the connection is used\&. The +\fIdbname\fR +can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. +.RE +.PP +\fB\-e\fR +.br +\fB\-\-echo\fR +.RS 4 +Echo the commands that +clusterdb +generates and sends to the server\&. +.RE +.PP +\fB\-q\fR +.br +\fB\-\-quiet\fR +.RS 4 +Do not display progress messages\&. +.RE +.PP +\fB\-t \fR\fB\fItable\fR\fR +.br +\fB\-\-table=\fR\fB\fItable\fR\fR +.RS 4 +Cluster +\fItable\fR +only\&. Multiple tables can be clustered by writing multiple +\fB\-t\fR +switches\&. +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Print detailed information during processing\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +clusterdb +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +clusterdb +command line arguments, and exit\&. +.RE +.PP +clusterdb +also accepts the following command\-line arguments for connection parameters: +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +clusterdb +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +clusterdb +will automatically prompt for a password if the server demands password authentication\&. However, +clusterdb +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +\fB\-\-maintenance\-db=\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to connect to to discover which databases should be clustered, when +\fB\-a\fR/\fB\-\-all\fR +is used\&. If not specified, the +postgres +database will be used, or if that does not exist, +template1 +will be used\&. This can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. Also, connection string parameters other than the database name itself will be re\-used when connecting to other databases\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGDATABASE\fR +.br +\fBPGHOST\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "DIAGNOSTICS" +.PP +In case of difficulty, see +\fBCLUSTER\fR(7) +and +\fBpsql\fR(1) +for discussions of potential problems and error messages\&. The database server must be running at the targeted host\&. Also, any default connection settings and environment variables used by the +libpq +front\-end library will apply\&. +.SH "EXAMPLES" +.PP +To cluster the database +test: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBclusterdb test\fR +.fi +.if n \{\ +.RE +.\} +.PP +To cluster a single table +foo +in a database named +xyzzy: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBclusterdb \-\-table=foo xyzzy\fR +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBCLUSTER\fR(7) diff --git a/doc/src/sgml/man1/createdb.1 b/doc/src/sgml/man1/createdb.1 new file mode 100644 index 0000000..c99a8b6 --- /dev/null +++ b/doc/src/sgml/man1/createdb.1 @@ -0,0 +1,310 @@ +'\" t +.\" Title: createdb +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "CREATEDB" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +createdb \- create a new PostgreSQL database +.SH "SYNOPSIS" +.HP \w'\fBcreatedb\fR\ 'u +\fBcreatedb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\fIdbname\fR\ [\fIdescription\fR]] +.SH "DESCRIPTION" +.PP +createdb +creates a new +PostgreSQL +database\&. +.PP +Normally, the database user who executes this command becomes the owner of the new database\&. However, a different owner can be specified via the +\fB\-O\fR +option, if the executing user has appropriate privileges\&. +.PP +createdb +is a wrapper around the +SQL +command +\fBCREATE DATABASE\fR\&. There is no effective difference between creating databases via this utility and via other methods for accessing the server\&. +.SH "OPTIONS" +.PP +createdb +accepts the following command\-line arguments: +.PP +\fIdbname\fR +.RS 4 +Specifies the name of the database to be created\&. The name must be unique among all +PostgreSQL +databases in this cluster\&. The default is to create a database with the same name as the current system user\&. +.RE +.PP +\fIdescription\fR +.RS 4 +Specifies a comment to be associated with the newly created database\&. +.RE +.PP +\fB\-D \fR\fB\fItablespace\fR\fR +.br +\fB\-\-tablespace=\fR\fB\fItablespace\fR\fR +.RS 4 +Specifies the default tablespace for the database\&. (This name is processed as a double\-quoted identifier\&.) +.RE +.PP +\fB\-e\fR +.br +\fB\-\-echo\fR +.RS 4 +Echo the commands that +createdb +generates and sends to the server\&. +.RE +.PP +\fB\-E \fR\fB\fIencoding\fR\fR +.br +\fB\-\-encoding=\fR\fB\fIencoding\fR\fR +.RS 4 +Specifies the character encoding scheme to be used in this database\&. The character sets supported by the +PostgreSQL +server are described in +Section\ \&24.3.1\&. +.RE +.PP +\fB\-l \fR\fB\fIlocale\fR\fR +.br +\fB\-\-locale=\fR\fB\fIlocale\fR\fR +.RS 4 +Specifies the locale to be used in this database\&. This is equivalent to specifying both +\fB\-\-lc\-collate\fR +and +\fB\-\-lc\-ctype\fR\&. +.RE +.PP +\fB\-\-lc\-collate=\fR\fB\fIlocale\fR\fR +.RS 4 +Specifies the LC_COLLATE setting to be used in this database\&. +.RE +.PP +\fB\-\-lc\-ctype=\fR\fB\fIlocale\fR\fR +.RS 4 +Specifies the LC_CTYPE setting to be used in this database\&. +.RE +.PP +\fB\-\-icu\-locale=\fR\fB\fIlocale\fR\fR +.RS 4 +Specifies the ICU locale ID to be used in this database, if the ICU locale provider is selected\&. +.RE +.PP +\fB\-\-locale\-provider={\fR\fBlibc\fR\fB|\fR\fBicu\fR\fB}\fR +.RS 4 +Specifies the locale provider for the database\*(Aqs default collation\&. +.RE +.PP +\fB\-O \fR\fB\fIowner\fR\fR +.br +\fB\-\-owner=\fR\fB\fIowner\fR\fR +.RS 4 +Specifies the database user who will own the new database\&. (This name is processed as a double\-quoted identifier\&.) +.RE +.PP +\fB\-S \fR\fB\fItemplate\fR\fR +.br +\fB\-\-strategy=\fR\fB\fIstrategy\fR\fR +.RS 4 +Specifies the database creation strategy\&. See +CREATE DATABASE STRATEGY +for more details\&. +.RE +.PP +\fB\-T \fR\fB\fItemplate\fR\fR +.br +\fB\-\-template=\fR\fB\fItemplate\fR\fR +.RS 4 +Specifies the template database from which to build this database\&. (This name is processed as a double\-quoted identifier\&.) +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +createdb +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +createdb +command line arguments, and exit\&. +.RE +.PP +The options +\fB\-D\fR, +\fB\-l\fR, +\fB\-E\fR, +\fB\-O\fR, and +\fB\-T\fR +correspond to options of the underlying SQL command +\fBCREATE DATABASE\fR; see there for more information about them\&. +.PP +createdb +also accepts the following command\-line arguments for connection parameters: +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or the local Unix domain socket file extension on which the server is listening for connections\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +createdb +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +createdb +will automatically prompt for a password if the server demands password authentication\&. However, +createdb +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +\fB\-\-maintenance\-db=\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to connect to when creating the new database\&. If not specified, the +postgres +database will be used; if that does not exist (or if it is the name of the new database being created), +template1 +will be used\&. This can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGDATABASE\fR +.RS 4 +If set, the name of the database to create, unless overridden on the command line\&. +.RE +.PP +\fBPGHOST\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters\&. +\fBPGUSER\fR +also determines the name of the database to create, if it is not specified on the command line or by +\fBPGDATABASE\fR\&. +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "DIAGNOSTICS" +.PP +In case of difficulty, see +CREATE DATABASE (\fBCREATE_DATABASE\fR(7)) +and +\fBpsql\fR(1) +for discussions of potential problems and error messages\&. The database server must be running at the targeted host\&. Also, any default connection settings and environment variables used by the +libpq +front\-end library will apply\&. +.SH "EXAMPLES" +.PP +To create the database +demo +using the default database server: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBcreatedb demo\fR +.fi +.if n \{\ +.RE +.\} +.PP +To create the database +demo +using the server on host +eden, port 5000, using the +template0 +template database, here is the command\-line command and the underlying SQL command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBcreatedb \-p 5000 \-h eden \-T template0 \-e demo\fR +CREATE DATABASE demo TEMPLATE template0; +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBdropdb\fR(1), CREATE DATABASE (\fBCREATE_DATABASE\fR(7)) diff --git a/doc/src/sgml/man1/createuser.1 b/doc/src/sgml/man1/createuser.1 new file mode 100644 index 0000000..3e1db12 --- /dev/null +++ b/doc/src/sgml/man1/createuser.1 @@ -0,0 +1,388 @@ +'\" t +.\" Title: createuser +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "CREATEUSER" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +createuser \- define a new PostgreSQL user account +.SH "SYNOPSIS" +.HP \w'\fBcreateuser\fR\ 'u +\fBcreateuser\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\fIusername\fR] +.SH "DESCRIPTION" +.PP +createuser +creates a new +PostgreSQL +user (or more precisely, a role)\&. Only superusers and users with +CREATEROLE +privilege can create new users, so +createuser +must be invoked by someone who can connect as a superuser or a user with +CREATEROLE +privilege\&. +.PP +If you wish to create a role with the +SUPERUSER, +REPLICATION, or +BYPASSRLS +privilege, you must connect as a superuser, not merely with +CREATEROLE +privilege\&. Being a superuser implies the ability to bypass all access permission checks within the database, so superuser access should not be granted lightly\&. +CREATEROLE +also conveys +very extensive privileges\&. +.PP +createuser +is a wrapper around the +SQL +command +\fBCREATE ROLE\fR\&. There is no effective difference between creating users via this utility and via other methods for accessing the server\&. +.SH "OPTIONS" +.PP +createuser +accepts the following command\-line arguments: +.PP +\fIusername\fR +.RS 4 +Specifies the name of the +PostgreSQL +user to be created\&. This name must be different from all existing roles in this +PostgreSQL +installation\&. +.RE +.PP +\fB\-c \fR\fB\fInumber\fR\fR +.br +\fB\-\-connection\-limit=\fR\fB\fInumber\fR\fR +.RS 4 +Set a maximum number of connections for the new user\&. The default is to set no limit\&. +.RE +.PP +\fB\-d\fR +.br +\fB\-\-createdb\fR +.RS 4 +The new user will be allowed to create databases\&. +.RE +.PP +\fB\-D\fR +.br +\fB\-\-no\-createdb\fR +.RS 4 +The new user will not be allowed to create databases\&. This is the default\&. +.RE +.PP +\fB\-e\fR +.br +\fB\-\-echo\fR +.RS 4 +Echo the commands that +createuser +generates and sends to the server\&. +.RE +.PP +\fB\-E\fR +.br +\fB\-\-encrypted\fR +.RS 4 +This option is obsolete but still accepted for backward compatibility\&. +.RE +.PP +\fB\-g \fR\fB\fIrole\fR\fR +.br +\fB\-\-role=\fR\fB\fIrole\fR\fR +.RS 4 +Indicates role to which this role will be added immediately as a new member\&. Multiple roles to which this role will be added as a member can be specified by writing multiple +\fB\-g\fR +switches\&. +.RE +.PP +\fB\-i\fR +.br +\fB\-\-inherit\fR +.RS 4 +The new role will automatically inherit privileges of roles it is a member of\&. This is the default\&. +.RE +.PP +\fB\-I\fR +.br +\fB\-\-no\-inherit\fR +.RS 4 +The new role will not automatically inherit privileges of roles it is a member of\&. +.RE +.PP +\fB\-\-interactive\fR +.RS 4 +Prompt for the user name if none is specified on the command line, and also prompt for whichever of the options +\fB\-d\fR/\fB\-D\fR, +\fB\-r\fR/\fB\-R\fR, +\fB\-s\fR/\fB\-S\fR +is not specified on the command line\&. (This was the default behavior up to PostgreSQL 9\&.1\&.) +.RE +.PP +\fB\-l\fR +.br +\fB\-\-login\fR +.RS 4 +The new user will be allowed to log in (that is, the user name can be used as the initial session user identifier)\&. This is the default\&. +.RE +.PP +\fB\-L\fR +.br +\fB\-\-no\-login\fR +.RS 4 +The new user will not be allowed to log in\&. (A role without login privilege is still useful as a means of managing database permissions\&.) +.RE +.PP +\fB\-P\fR +.br +\fB\-\-pwprompt\fR +.RS 4 +If given, +createuser +will issue a prompt for the password of the new user\&. This is not necessary if you do not plan on using password authentication\&. +.RE +.PP +\fB\-r\fR +.br +\fB\-\-createrole\fR +.RS 4 +The new user will be allowed to create, alter, drop, comment on, change the security label for, and grant or revoke membership in other roles; that is, this user will have +CREATEROLE +privilege\&. See +role creation +for more details about what capabilities are conferred by this privilege\&. +.RE +.PP +\fB\-R\fR +.br +\fB\-\-no\-createrole\fR +.RS 4 +The new user will not be allowed to create new roles\&. This is the default\&. +.RE +.PP +\fB\-s\fR +.br +\fB\-\-superuser\fR +.RS 4 +The new user will be a superuser\&. +.RE +.PP +\fB\-S\fR +.br +\fB\-\-no\-superuser\fR +.RS 4 +The new user will not be a superuser\&. This is the default\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +createuser +version and exit\&. +.RE +.PP +\fB\-\-replication\fR +.RS 4 +The new user will have the +REPLICATION +privilege, which is described more fully in the documentation for +CREATE ROLE (\fBCREATE_ROLE\fR(7))\&. +.RE +.PP +\fB\-\-no\-replication\fR +.RS 4 +The new user will not have the +REPLICATION +privilege, which is described more fully in the documentation for +CREATE ROLE (\fBCREATE_ROLE\fR(7))\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +createuser +command line arguments, and exit\&. +.RE +.PP +createuser +also accepts the following command\-line arguments for connection parameters: +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as (not the user name to create)\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +createuser +to prompt for a password (for connecting to the server, not for the password of the new user)\&. +.sp +This option is never essential, since +createuser +will automatically prompt for a password if the server demands password authentication\&. However, +createuser +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGHOST\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "DIAGNOSTICS" +.PP +In case of difficulty, see +CREATE ROLE (\fBCREATE_ROLE\fR(7)) +and +\fBpsql\fR(1) +for discussions of potential problems and error messages\&. The database server must be running at the targeted host\&. Also, any default connection settings and environment variables used by the +libpq +front\-end library will apply\&. +.SH "EXAMPLES" +.PP +To create a user +joe +on the default database server: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBcreateuser joe\fR +.fi +.if n \{\ +.RE +.\} +.PP +To create a user +joe +on the default database server with prompting for some additional attributes: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBcreateuser \-\-interactive joe\fR +Shall the new role be a superuser? (y/n) \fBn\fR +Shall the new role be allowed to create databases? (y/n) \fBn\fR +Shall the new role be allowed to create more new roles? (y/n) \fBn\fR +.fi +.if n \{\ +.RE +.\} +.PP +To create the same user +joe +using the server on host +eden, port 5000, with attributes explicitly specified, taking a look at the underlying command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBcreateuser \-h eden \-p 5000 \-S \-D \-R \-e joe\fR +CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN; +.fi +.if n \{\ +.RE +.\} +.PP +To create the user +joe +as a superuser, and assign a password immediately: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBcreateuser \-P \-s \-e joe\fR +Enter password for new role: \fBxyzzy\fR +Enter it again: \fBxyzzy\fR +CREATE ROLE joe PASSWORD \*(Aqmd5b5f5ba1a423792b526f799ae4eb3d59e\*(Aq SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN; +.fi +.if n \{\ +.RE +.\} +.sp +In the above example, the new password isn\*(Aqt actually echoed when typed, but we show what was typed for clarity\&. As you see, the password is encrypted before it is sent to the client\&. +.SH "SEE ALSO" +\fBdropuser\fR(1), CREATE ROLE (\fBCREATE_ROLE\fR(7)) diff --git a/doc/src/sgml/man1/dropdb.1 b/doc/src/sgml/man1/dropdb.1 new file mode 100644 index 0000000..6be3631 --- /dev/null +++ b/doc/src/sgml/man1/dropdb.1 @@ -0,0 +1,233 @@ +'\" t +.\" Title: dropdb +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "DROPDB" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +dropdb \- remove a PostgreSQL database +.SH "SYNOPSIS" +.HP \w'\fBdropdb\fR\ 'u +\fBdropdb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] \fIdbname\fR +.SH "DESCRIPTION" +.PP +dropdb +destroys an existing +PostgreSQL +database\&. The user who executes this command must be a database superuser or the owner of the database\&. +.PP +dropdb +is a wrapper around the +SQL +command +\fBDROP DATABASE\fR\&. There is no effective difference between dropping databases via this utility and via other methods for accessing the server\&. +.SH "OPTIONS" +.PP +dropdb +accepts the following command\-line arguments: +.PP +\fIdbname\fR +.RS 4 +Specifies the name of the database to be removed\&. +.RE +.PP +\fB\-e\fR +.br +\fB\-\-echo\fR +.RS 4 +Echo the commands that +dropdb +generates and sends to the server\&. +.RE +.PP +\fB\-f\fR +.br +\fB\-\-force\fR +.RS 4 +Attempt to terminate all existing connections to the target database before dropping it\&. See +DROP DATABASE (\fBDROP_DATABASE\fR(7)) +for more information on this option\&. +.RE +.PP +\fB\-i\fR +.br +\fB\-\-interactive\fR +.RS 4 +Issues a verification prompt before doing anything destructive\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +dropdb +version and exit\&. +.RE +.PP +\fB\-\-if\-exists\fR +.RS 4 +Do not throw an error if the database does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +dropdb +command line arguments, and exit\&. +.RE +.PP +dropdb +also accepts the following command\-line arguments for connection parameters: +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +dropdb +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +dropdb +will automatically prompt for a password if the server demands password authentication\&. However, +dropdb +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +\fB\-\-maintenance\-db=\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to connect to in order to drop the target database\&. If not specified, the +postgres +database will be used; if that does not exist (or is the database being dropped), +template1 +will be used\&. This can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGHOST\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "DIAGNOSTICS" +.PP +In case of difficulty, see +DROP DATABASE (\fBDROP_DATABASE\fR(7)) +and +\fBpsql\fR(1) +for discussions of potential problems and error messages\&. The database server must be running at the targeted host\&. Also, any default connection settings and environment variables used by the +libpq +front\-end library will apply\&. +.SH "EXAMPLES" +.PP +To destroy the database +demo +on the default database server: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBdropdb demo\fR +.fi +.if n \{\ +.RE +.\} +.PP +To destroy the database +demo +using the server on host +eden, port 5000, with verification and a peek at the underlying command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBdropdb \-p 5000 \-h eden \-i \-e demo\fR +Database "demo" will be permanently deleted\&. +Are you sure? (y/n) \fBy\fR +DROP DATABASE demo; +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBcreatedb\fR(1), DROP DATABASE (\fBDROP_DATABASE\fR(7)) diff --git a/doc/src/sgml/man1/dropuser.1 b/doc/src/sgml/man1/dropuser.1 new file mode 100644 index 0000000..d94d4fa --- /dev/null +++ b/doc/src/sgml/man1/dropuser.1 @@ -0,0 +1,222 @@ +'\" t +.\" Title: dropuser +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "DROPUSER" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +dropuser \- remove a PostgreSQL user account +.SH "SYNOPSIS" +.HP \w'\fBdropuser\fR\ 'u +\fBdropuser\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\fIusername\fR] +.SH "DESCRIPTION" +.PP +dropuser +removes an existing +PostgreSQL +user\&. Only superusers and users with the +CREATEROLE +privilege can remove +PostgreSQL +users\&. (To remove a superuser, you must yourself be a superuser\&.) +.PP +dropuser +is a wrapper around the +SQL +command +\fBDROP ROLE\fR\&. There is no effective difference between dropping users via this utility and via other methods for accessing the server\&. +.SH "OPTIONS" +.PP +dropuser +accepts the following command\-line arguments: +.PP +\fIusername\fR +.RS 4 +Specifies the name of the +PostgreSQL +user to be removed\&. You will be prompted for a name if none is specified on the command line and the +\fB\-i\fR/\fB\-\-interactive\fR +option is used\&. +.RE +.PP +\fB\-e\fR +.br +\fB\-\-echo\fR +.RS 4 +Echo the commands that +dropuser +generates and sends to the server\&. +.RE +.PP +\fB\-i\fR +.br +\fB\-\-interactive\fR +.RS 4 +Prompt for confirmation before actually removing the user, and prompt for the user name if none is specified on the command line\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +dropuser +version and exit\&. +.RE +.PP +\fB\-\-if\-exists\fR +.RS 4 +Do not throw an error if the user does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +dropuser +command line arguments, and exit\&. +.RE +.PP +dropuser +also accepts the following command\-line arguments for connection parameters: +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as (not the user name to drop)\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +dropuser +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +dropuser +will automatically prompt for a password if the server demands password authentication\&. However, +dropuser +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGHOST\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "DIAGNOSTICS" +.PP +In case of difficulty, see +DROP ROLE (\fBDROP_ROLE\fR(7)) +and +\fBpsql\fR(1) +for discussions of potential problems and error messages\&. The database server must be running at the targeted host\&. Also, any default connection settings and environment variables used by the +libpq +front\-end library will apply\&. +.SH "EXAMPLES" +.PP +To remove user +joe +from the default database server: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBdropuser joe\fR +.fi +.if n \{\ +.RE +.\} +.PP +To remove user +joe +using the server on host +eden, port 5000, with verification and a peek at the underlying command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBdropuser \-p 5000 \-h eden \-i \-e joe\fR +Role "joe" will be permanently removed\&. +Are you sure? (y/n) \fBy\fR +DROP ROLE joe; +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBcreateuser\fR(1), DROP ROLE (\fBDROP_ROLE\fR(7)) diff --git a/doc/src/sgml/man1/ecpg.1 b/doc/src/sgml/man1/ecpg.1 new file mode 100644 index 0000000..6cad06e --- /dev/null +++ b/doc/src/sgml/man1/ecpg.1 @@ -0,0 +1,208 @@ +'\" t +.\" Title: ecpg +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "ECPG" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ecpg \- embedded SQL C preprocessor +.SH "SYNOPSIS" +.HP \w'\fBecpg\fR\ 'u +\fBecpg\fR [\fIoption\fR...] \fIfile\fR... +.SH "DESCRIPTION" +.PP +\fBecpg\fR +is the embedded SQL preprocessor for C programs\&. It converts C programs with embedded SQL statements to normal C code by replacing the SQL invocations with special function calls\&. The output files can then be processed with any C compiler tool chain\&. +.PP +\fBecpg\fR +will convert each input file given on the command line to the corresponding C output file\&. If an input file name does not have any extension, +\&.pgc +is assumed\&. The file\*(Aqs extension will be replaced by +\&.c +to construct the output file name\&. But the output file name can be overridden using the +\fB\-o\fR +option\&. +.PP +If an input file name is just +\-, +\fBecpg\fR +reads the program from standard input (and writes to standard output, unless that is overridden with +\fB\-o\fR)\&. +.PP +This reference page does not describe the embedded SQL language\&. See +Chapter\ \&36 +for more information on that topic\&. +.SH "OPTIONS" +.PP +\fBecpg\fR +accepts the following command\-line arguments: +.PP +\fB\-c\fR +.RS 4 +Automatically generate certain C code from SQL code\&. Currently, this works for +EXEC SQL TYPE\&. +.RE +.PP +\fB\-C \fR\fB\fImode\fR\fR +.RS 4 +Set a compatibility mode\&. +\fImode\fR +can be +INFORMIX, +INFORMIX_SE, or +ORACLE\&. +.RE +.PP +\fB\-D \fR\fB\fIsymbol\fR\fR +.RS 4 +Define a C preprocessor symbol\&. +.RE +.PP +\fB\-h\fR +.RS 4 +Process header files\&. When this option is specified, the output file extension becomes +\&.h +not +\&.c, and the default input file extension is +\&.pgh +not +\&.pgc\&. Also, the +\fB\-c\fR +option is forced on\&. +.RE +.PP +\fB\-i\fR +.RS 4 +Parse system include files as well\&. +.RE +.PP +\fB\-I \fR\fB\fIdirectory\fR\fR +.RS 4 +Specify an additional include path, used to find files included via +EXEC SQL INCLUDE\&. Defaults are +\&. +(current directory), +/usr/local/include, the +PostgreSQL +include directory which is defined at compile time (default: +/usr/local/pgsql/include), and +/usr/include, in that order\&. +.RE +.PP +\fB\-o \fR\fB\fIfilename\fR\fR +.RS 4 +Specifies that +\fBecpg\fR +should write all its output to the given +\fIfilename\fR\&. Write +\-o \- +to send all output to standard output\&. +.RE +.PP +\fB\-r \fR\fB\fIoption\fR\fR +.RS 4 +Selects run\-time behavior\&. +\fIOption\fR +can be one of the following: +.PP +\fBno_indicator\fR +.RS 4 +Do not use indicators but instead use special values to represent null values\&. Historically there have been databases using this approach\&. +.RE +.PP +\fBprepare\fR +.RS 4 +Prepare all statements before using them\&. Libecpg will keep a cache of prepared statements and reuse a statement if it gets executed again\&. If the cache runs full, libecpg will free the least used statement\&. +.RE +.PP +\fBquestionmarks\fR +.RS 4 +Allow question mark as placeholder for compatibility reasons\&. This used to be the default long ago\&. +.RE +.RE +.PP +\fB\-t\fR +.RS 4 +Turn on autocommit of transactions\&. In this mode, each SQL command is automatically committed unless it is inside an explicit transaction block\&. In the default mode, commands are committed only when +\fBEXEC SQL COMMIT\fR +is issued\&. +.RE +.PP +\fB\-v\fR +.RS 4 +Print additional information including the version and the "include" path\&. +.RE +.PP +\fB\-\-version\fR +.RS 4 +Print the +ecpg +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +ecpg +command line arguments, and exit\&. +.RE +.SH "NOTES" +.PP +When compiling the preprocessed C code files, the compiler needs to be able to find the +ECPG +header files in the +PostgreSQL +include directory\&. Therefore, you might have to use the +\fB\-I\fR +option when invoking the compiler (e\&.g\&., +\-I/usr/local/pgsql/include)\&. +.PP +Programs using C code with embedded SQL have to be linked against the +libecpg +library, for example using the linker options +\-L/usr/local/pgsql/lib \-lecpg\&. +.PP +The value of either of these directories that is appropriate for the installation can be found out using +\fBpg_config\fR(1)\&. +.SH "EXAMPLES" +.PP +If you have an embedded SQL C source file named +prog1\&.pgc, you can create an executable program using the following sequence of commands: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ecpg prog1\&.pgc +cc \-I/usr/local/pgsql/include \-c prog1\&.c +cc \-o prog1 prog1\&.o \-L/usr/local/pgsql/lib \-lecpg +.fi +.if n \{\ +.RE +.\} + diff --git a/doc/src/sgml/man1/initdb.1 b/doc/src/sgml/man1/initdb.1 new file mode 100644 index 0000000..3cb0fce --- /dev/null +++ b/doc/src/sgml/man1/initdb.1 @@ -0,0 +1,415 @@ +'\" t +.\" Title: initdb +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "INITDB" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +initdb \- create a new PostgreSQL database cluster +.SH "SYNOPSIS" +.HP \w'\fBinitdb\fR\ 'u +\fBinitdb\fR [\fIoption\fR...] [\fB\-\-pgdata\fR | \fB\-D\fR]\fI directory\fR +.SH "DESCRIPTION" +.PP +\fBinitdb\fR +creates a new +PostgreSQL +database cluster\&. A database cluster is a collection of databases that are managed by a single server instance\&. +.PP +Creating a database cluster consists of creating the directories in which the database data will live, generating the shared catalog tables (tables that belong to the whole cluster rather than to any particular database), and creating the +postgres, +template1, and +template0 +databases\&. The +postgres +database is a default database meant for use by users, utilities and third party applications\&. +template1 +and +template0 +are meant as source databases to be copied by later +\fBCREATE DATABASE\fR +commands\&. +template0 +should never be modified, but you can add objects to +template1, which by default will be copied into databases created later\&. See +Section\ \&23.3 +for more details\&. +.PP +Although +\fBinitdb\fR +will attempt to create the specified data directory, it might not have permission if the parent directory of the desired data directory is root\-owned\&. To initialize in such a setup, create an empty data directory as root, then use +\fBchown\fR +to assign ownership of that directory to the database user account, then +\fBsu\fR +to become the database user to run +\fBinitdb\fR\&. +.PP +\fBinitdb\fR +must be run as the user that will own the server process, because the server needs to have access to the files and directories that +\fBinitdb\fR +creates\&. Since the server cannot be run as root, you must not run +\fBinitdb\fR +as root either\&. (It will in fact refuse to do so\&.) +.PP +For security reasons the new cluster created by +\fBinitdb\fR +will only be accessible by the cluster owner by default\&. The +\fB\-\-allow\-group\-access\fR +option allows any user in the same group as the cluster owner to read files in the cluster\&. This is useful for performing backups as a non\-privileged user\&. +.PP +\fBinitdb\fR +initializes the database cluster\*(Aqs default locale and character set encoding\&. These can also be set separately for each database when it is created\&. +\fBinitdb\fR +determines those settings for the template databases, which will serve as the default for all other databases\&. By default, +\fBinitdb\fR +uses the locale provider +libc, takes the locale settings from the environment, and determines the encoding from the locale settings\&. This is almost always sufficient, unless there are special requirements\&. +.PP +To choose a different locale for the cluster, use the option +\fB\-\-locale\fR\&. There are also individual options +\fB\-\-lc\-*\fR +(see below) to set values for the individual locale categories\&. Note that inconsistent settings for different locale categories can give nonsensical results, so this should be used with care\&. +.PP +Alternatively, the ICU library can be used to provide locale services\&. (Again, this only sets the default for subsequently created databases\&.) To select this option, specify +\-\-locale\-provider=icu\&. To choose the specific ICU locale ID to apply, use the option +\fB\-\-icu\-locale\fR\&. Note that for implementation reasons and to support legacy code, +\fBinitdb\fR +will still select and initialize libc locale settings when the ICU locale provider is used\&. +.PP +When +\fBinitdb\fR +runs, it will print out the locale settings it has chosen\&. If you have complex requirements or specified multiple options, it is advisable to check that the result matches what was intended\&. +.PP +More details about locale settings can be found in +Section\ \&24.1\&. +.PP +To alter the default encoding, use the +\fB\-\-encoding\fR\&. More details can be found in +Section\ \&24.3\&. +.SH "OPTIONS" +.PP +.PP +\fB\-A \fR\fB\fIauthmethod\fR\fR +.br +\fB\-\-auth=\fR\fB\fIauthmethod\fR\fR +.RS 4 +This option specifies the default authentication method for local users used in +pg_hba\&.conf +(host +and +local +lines)\&. See +Section\ \&21.1 +for an overview of valid values\&. +.sp +\fBinitdb\fR +will prepopulate +pg_hba\&.conf +entries using the specified authentication method for non\-replication as well as replication connections\&. +.sp +Do not use +trust +unless you trust all local users on your system\&. +trust +is the default for ease of installation\&. +.RE +.PP +\fB\-\-auth\-host=\fR\fB\fIauthmethod\fR\fR +.RS 4 +This option specifies the authentication method for local users via TCP/IP connections used in +pg_hba\&.conf +(host +lines)\&. +.RE +.PP +\fB\-\-auth\-local=\fR\fB\fIauthmethod\fR\fR +.RS 4 +This option specifies the authentication method for local users via Unix\-domain socket connections used in +pg_hba\&.conf +(local +lines)\&. +.RE +.PP +\fB\-D \fR\fB\fIdirectory\fR\fR +.br +\fB\-\-pgdata=\fR\fB\fIdirectory\fR\fR +.RS 4 +This option specifies the directory where the database cluster should be stored\&. This is the only information required by +\fBinitdb\fR, but you can avoid writing it by setting the +\fBPGDATA\fR +environment variable, which can be convenient since the database server (\fBpostgres\fR) can find the database directory later by the same variable\&. +.RE +.PP +\fB\-E \fR\fB\fIencoding\fR\fR +.br +\fB\-\-encoding=\fR\fB\fIencoding\fR\fR +.RS 4 +Selects the encoding of the template databases\&. This will also be the default encoding of any database you create later, unless you override it then\&. The default is derived from the locale, if the libc locale provider is used, or +UTF8 +if the ICU locale provider is used\&. The character sets supported by the +PostgreSQL +server are described in +Section\ \&24.3.1\&. +.RE +.PP +\fB\-g\fR +.br +\fB\-\-allow\-group\-access\fR +.RS 4 +Allows users in the same group as the cluster owner to read all cluster files created by +\fBinitdb\fR\&. This option is ignored on +Windows +as it does not support +POSIX\-style group permissions\&. +.RE +.PP +\fB\-\-icu\-locale=\fR\fB\fIlocale\fR\fR +.RS 4 +Specifies the ICU locale ID, if the ICU locale provider is used\&. +.RE +.PP +\fB\-k\fR +.br +\fB\-\-data\-checksums\fR +.RS 4 +Use checksums on data pages to help detect corruption by the I/O system that would otherwise be silent\&. Enabling checksums may incur a noticeable performance penalty\&. If set, checksums are calculated for all objects, in all databases\&. All checksum failures will be reported in the +pg_stat_database +view\&. See +Section\ \&30.2 +for details\&. +.RE +.PP +\fB\-\-locale=\fR\fB\fIlocale\fR\fR +.RS 4 +Sets the default locale for the database cluster\&. If this option is not specified, the locale is inherited from the environment that +\fBinitdb\fR +runs in\&. Locale support is described in +Section\ \&24.1\&. +.RE +.PP +\fB\-\-lc\-collate=\fR\fB\fIlocale\fR\fR +.br +\fB\-\-lc\-ctype=\fR\fB\fIlocale\fR\fR +.br +\fB\-\-lc\-messages=\fR\fB\fIlocale\fR\fR +.br +\fB\-\-lc\-monetary=\fR\fB\fIlocale\fR\fR +.br +\fB\-\-lc\-numeric=\fR\fB\fIlocale\fR\fR +.br +\fB\-\-lc\-time=\fR\fB\fIlocale\fR\fR +.RS 4 +Like +\fB\-\-locale\fR, but only sets the locale in the specified category\&. +.RE +.PP +\fB\-\-no\-locale\fR +.RS 4 +Equivalent to +\fB\-\-locale=C\fR\&. +.RE +.PP +\fB\-\-locale\-provider={\fR\fBlibc\fR\fB|\fR\fBicu\fR\fB}\fR +.RS 4 +This option sets the locale provider for databases created in the new cluster\&. It can be overridden in the +\fBCREATE DATABASE\fR +command when new databases are subsequently created\&. The default is +libc\&. +.RE +.PP +\fB\-N\fR +.br +\fB\-\-no\-sync\fR +.RS 4 +By default, +\fBinitdb\fR +will wait for all files to be written safely to disk\&. This option causes +\fBinitdb\fR +to return without waiting, which is faster, but means that a subsequent operating system crash can leave the data directory corrupt\&. Generally, this option is useful for testing, but should not be used when creating a production installation\&. +.RE +.PP +\fB\-\-no\-instructions\fR +.RS 4 +By default, +\fBinitdb\fR +will write instructions for how to start the cluster at the end of its output\&. This option causes those instructions to be left out\&. This is primarily intended for use by tools that wrap +\fBinitdb\fR +in platform\-specific behavior, where those instructions are likely to be incorrect\&. +.RE +.PP +\fB\-\-pwfile=\fR\fB\fIfilename\fR\fR +.RS 4 +Makes +\fBinitdb\fR +read the database superuser\*(Aqs password from a file\&. The first line of the file is taken as the password\&. +.RE +.PP +\fB\-S\fR +.br +\fB\-\-sync\-only\fR +.RS 4 +Safely write all database files to disk and exit\&. This does not perform any of the normal +initdb +operations\&. Generally, this option is useful for ensuring reliable recovery after changing +fsync +from +off +to +on\&. +.RE +.PP +\fB\-T \fR\fB\fIconfig\fR\fR +.br +\fB\-\-text\-search\-config=\fR\fB\fIconfig\fR\fR +.RS 4 +Sets the default text search configuration\&. See +default_text_search_config +for further information\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +Selects the user name of the database superuser\&. This defaults to the name of the effective user running +\fBinitdb\fR\&. It is really not important what the superuser\*(Aqs name is, but one might choose to keep the customary name +postgres, even if the operating system user\*(Aqs name is different\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-pwprompt\fR +.RS 4 +Makes +\fBinitdb\fR +prompt for a password to give the database superuser\&. If you don\*(Aqt plan on using password authentication, this is not important\&. Otherwise you won\*(Aqt be able to use password authentication until you have a password set up\&. +.RE +.PP +\fB\-X \fR\fB\fIdirectory\fR\fR +.br +\fB\-\-waldir=\fR\fB\fIdirectory\fR\fR +.RS 4 +This option specifies the directory where the write\-ahead log should be stored\&. +.RE +.PP +\fB\-\-wal\-segsize=\fR\fB\fIsize\fR\fR +.RS 4 +Set the +WAL segment size, in megabytes\&. This is the size of each individual file in the WAL log\&. The default size is 16 megabytes\&. The value must be a power of 2 between 1 and 1024 (megabytes)\&. This option can only be set during initialization, and cannot be changed later\&. +.sp +It may be useful to adjust this size to control the granularity of WAL log shipping or archiving\&. Also, in databases with a high volume of WAL, the sheer number of WAL files per directory can become a performance and management problem\&. Increasing the WAL file size will reduce the number of WAL files\&. +.RE +.PP +Other, less commonly used, options are also available: +.PP +\fB\-d\fR +.br +\fB\-\-debug\fR +.RS 4 +Print debugging output from the bootstrap backend and a few other messages of lesser interest for the general public\&. The bootstrap backend is the program +\fBinitdb\fR +uses to create the catalog tables\&. This option generates a tremendous amount of extremely boring output\&. +.RE +.PP +\fB\-\-discard\-caches\fR +.RS 4 +Run the bootstrap backend with the +debug_discard_caches=1 +option\&. This takes a very long time and is only of use for deep debugging\&. +.RE +.PP +\fB\-L \fR\fB\fIdirectory\fR\fR +.RS 4 +Specifies where +\fBinitdb\fR +should find its input files to initialize the database cluster\&. This is normally not necessary\&. You will be told if you need to specify their location explicitly\&. +.RE +.PP +\fB\-n\fR +.br +\fB\-\-no\-clean\fR +.RS 4 +By default, when +\fBinitdb\fR +determines that an error prevented it from completely creating the database cluster, it removes any files it might have created before discovering that it cannot finish the job\&. This option inhibits tidying\-up and is thus useful for debugging\&. +.RE +.PP +Other options: +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +initdb +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +initdb +command line arguments, and exit\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGDATA\fR +.RS 4 +Specifies the directory where the database cluster is to be stored; can be overridden using the +\fB\-D\fR +option\&. +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +\fBTZ\fR +.RS 4 +Specifies the default time zone of the created database cluster\&. The value should be a full time zone name (see +Section\ \&8.5.3)\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "NOTES" +.PP +\fBinitdb\fR +can also be invoked via +\fBpg_ctl initdb\fR\&. +.SH "SEE ALSO" +\fBpg_ctl\fR(1), \fBpostgres\fR(1), Section\ \&21.1 diff --git a/doc/src/sgml/man1/oid2name.1 b/doc/src/sgml/man1/oid2name.1 new file mode 100644 index 0000000..2c9763b --- /dev/null +++ b/doc/src/sgml/man1/oid2name.1 @@ -0,0 +1,379 @@ +'\" t +.\" Title: oid2name +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "OID2NAME" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +oid2name \- resolve OIDs and file nodes in a PostgreSQL data directory +.SH "SYNOPSIS" +.HP \w'\fBoid2name\fR\ 'u +\fBoid2name\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +oid2name +is a utility program that helps administrators to examine the file structure used by PostgreSQL\&. To make use of it, you need to be familiar with the database file structure, which is described in +Chapter\ \&73\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +The name +\(lqoid2name\(rq +is historical, and is actually rather misleading, since most of the time when you use it, you will really be concerned with tables\*(Aq filenode numbers (which are the file names visible in the database directories)\&. Be sure you understand the difference between table OIDs and table filenodes! +.sp .5v +.RE +.PP +oid2name +connects to a target database and extracts OID, filenode, and/or table name information\&. You can also have it show database OIDs or tablespace OIDs\&. +.SH "OPTIONS" +.PP +oid2name +accepts the following command\-line arguments: +.PP +\fB\-f \fR\fB\fIfilenode\fR\fR +.br +\fB\-\-filenode=\fR\fB\fIfilenode\fR\fR +.RS 4 +show info for table with filenode +\fIfilenode\fR\&. +.RE +.PP +\fB\-i\fR +.br +\fB\-\-indexes\fR +.RS 4 +include indexes and sequences in the listing\&. +.RE +.PP +\fB\-o \fR\fB\fIoid\fR\fR +.br +\fB\-\-oid=\fR\fB\fIoid\fR\fR +.RS 4 +show info for table with OID +\fIoid\fR\&. +.RE +.PP +\fB\-q\fR +.br +\fB\-\-quiet\fR +.RS 4 +omit headers (useful for scripting)\&. +.RE +.PP +\fB\-s\fR +.br +\fB\-\-tablespaces\fR +.RS 4 +show tablespace OIDs\&. +.RE +.PP +\fB\-S\fR +.br +\fB\-\-system\-objects\fR +.RS 4 +include system objects (those in +\fBinformation_schema\fR, +\fBpg_toast\fR +and +\fBpg_catalog\fR +schemas)\&. +.RE +.PP +\fB\-t \fR\fB\fItablename_pattern\fR\fR +.br +\fB\-\-table=\fR\fB\fItablename_pattern\fR\fR +.RS 4 +show info for table(s) matching +\fItablename_pattern\fR\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +oid2name +version and exit\&. +.RE +.PP +\fB\-x\fR +.br +\fB\-\-extended\fR +.RS 4 +display more information about each object shown: tablespace name, schema name, and OID\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +oid2name +command line arguments, and exit\&. +.RE +.PP +oid2name +also accepts the following command\-line arguments for connection parameters: +.PP +\fB\-d \fR\fB\fIdatabase\fR\fR +.br +\fB\-\-dbname=\fR\fB\fIdatabase\fR\fR +.RS 4 +database to connect to\&. +.RE +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +database server\*(Aqs host\&. +.RE +.PP +\fB\-H \fR\fB\fIhost\fR\fR +.RS 4 +database server\*(Aqs host\&. Use of this parameter is +\fIdeprecated\fR +as of +PostgreSQL +12\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +database server\*(Aqs port\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +user name to connect as\&. +.RE +.PP +To display specific tables, select which tables to show by using +\fB\-o\fR, +\fB\-f\fR +and/or +\fB\-t\fR\&. +\fB\-o\fR +takes an OID, +\fB\-f\fR +takes a filenode, and +\fB\-t\fR +takes a table name (actually, it\*(Aqs a +LIKE +pattern, so you can use things like +foo%)\&. You can use as many of these options as you like, and the listing will include all objects matched by any of the options\&. But note that these options can only show objects in the database given by +\fB\-d\fR\&. +.PP +If you don\*(Aqt give any of +\fB\-o\fR, +\fB\-f\fR +or +\fB\-t\fR, but do give +\fB\-d\fR, it will list all tables in the database named by +\fB\-d\fR\&. In this mode, the +\fB\-S\fR +and +\fB\-i\fR +options control what gets listed\&. +.PP +If you don\*(Aqt give +\fB\-d\fR +either, it will show a listing of database OIDs\&. Alternatively you can give +\fB\-s\fR +to get a tablespace listing\&. +.SH "ENVIRONMENT" +.PP +\fBPGHOST\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.PP +The environment variable +\fBPG_COLOR\fR +specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.SH "NOTES" +.PP +oid2name +requires a running database server with non\-corrupt system catalogs\&. It is therefore of only limited use for recovering from catastrophic database corruption situations\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ # what\*(Aqs in this database server, anyway? +$ oid2name +All databases: + Oid Database Name Tablespace +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 17228 alvherre pg_default + 17255 regression pg_default + 17227 template0 pg_default + 1 template1 pg_default + +$ oid2name \-s +All tablespaces: + Oid Tablespace Name +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 1663 pg_default + 1664 pg_global + 155151 fastdisk + 155152 bigdisk + +$ # OK, let\*(Aqs look into database alvherre +$ cd $PGDATA/base/17228 + +$ # get top 10 db objects in the default tablespace, ordered by size +$ ls \-lS * | head \-10 +\-rw\-\-\-\-\-\-\- 1 alvherre alvherre 136536064 sep 14 09:51 155173 +\-rw\-\-\-\-\-\-\- 1 alvherre alvherre 17965056 sep 14 09:51 1155291 +\-rw\-\-\-\-\-\-\- 1 alvherre alvherre 1204224 sep 14 09:51 16717 +\-rw\-\-\-\-\-\-\- 1 alvherre alvherre 581632 sep 6 17:51 1255 +\-rw\-\-\-\-\-\-\- 1 alvherre alvherre 237568 sep 14 09:50 16674 +\-rw\-\-\-\-\-\-\- 1 alvherre alvherre 212992 sep 14 09:51 1249 +\-rw\-\-\-\-\-\-\- 1 alvherre alvherre 204800 sep 14 09:51 16684 +\-rw\-\-\-\-\-\-\- 1 alvherre alvherre 196608 sep 14 09:50 16700 +\-rw\-\-\-\-\-\-\- 1 alvherre alvherre 163840 sep 14 09:50 16699 +\-rw\-\-\-\-\-\-\- 1 alvherre alvherre 122880 sep 6 17:51 16751 + +$ # I wonder what file 155173 is \&.\&.\&. +$ oid2name \-d alvherre \-f 155173 +From database "alvherre": + Filenode Table Name +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 155173 accounts + +$ # you can ask for more than one object +$ oid2name \-d alvherre \-f 155173 \-f 1155291 +From database "alvherre": + Filenode Table Name +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 155173 accounts + 1155291 accounts_pkey + +$ # you can mix the options, and get more details with \-x +$ oid2name \-d alvherre \-t accounts \-f 1155291 \-x +From database "alvherre": + Filenode Table Name Oid Schema Tablespace +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 155173 accounts 155173 public pg_default + 1155291 accounts_pkey 1155291 public pg_default + +$ # show disk space for every db object +$ du [0\-9]* | +> while read SIZE FILENODE +> do +> echo "$SIZE `oid2name \-q \-d alvherre \-i \-f $FILENODE`" +> done +16 1155287 branches_pkey +16 1155289 tellers_pkey +17561 1155291 accounts_pkey +\&.\&.\&. + +$ # same, but sort by size +$ du [0\-9]* | sort \-rn | while read SIZE FN +> do +> echo "$SIZE `oid2name \-q \-d alvherre \-f $FN`" +> done +133466 155173 accounts +17561 1155291 accounts_pkey +1177 16717 pg_proc_proname_args_nsp_index +\&.\&.\&. + +$ # If you want to see what\*(Aqs in tablespaces, use the pg_tblspc directory +$ cd $PGDATA/pg_tblspc +$ oid2name \-s +All tablespaces: + Oid Tablespace Name +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 1663 pg_default + 1664 pg_global + 155151 fastdisk + 155152 bigdisk + +$ # what databases have objects in tablespace "fastdisk"? +$ ls \-d 155151/* +155151/17228/ 155151/PG_VERSION + +$ # Oh, what was database 17228 again? +$ oid2name +All databases: + Oid Database Name Tablespace +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 17228 alvherre pg_default + 17255 regression pg_default + 17227 template0 pg_default + 1 template1 pg_default + +$ # Let\*(Aqs see what objects does this database have in the tablespace\&. +$ cd 155151/17228 +$ ls \-l +total 0 +\-rw\-\-\-\-\-\-\- 1 postgres postgres 0 sep 13 23:20 155156 + +$ # OK, this is a pretty small table \&.\&.\&. but which one is it? +$ oid2name \-d alvherre \-f 155156 +From database "alvherre": + Filenode Table Name +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 155156 foo +.fi +.if n \{\ +.RE +.\} +.SH "AUTHOR" +.PP +B\&. Palmer +<bpalmer@crimelabs\&.net> diff --git a/doc/src/sgml/man1/pg_amcheck.1 b/doc/src/sgml/man1/pg_amcheck.1 new file mode 100644 index 0000000..5c559da --- /dev/null +++ b/doc/src/sgml/man1/pg_amcheck.1 @@ -0,0 +1,462 @@ +'\" t +.\" Title: pg_amcheck +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_AMCHECK" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_amcheck \- checks for corruption in one or more PostgreSQL databases +.SH "SYNOPSIS" +.HP \w'\fBpg_amcheck\fR\ 'u +\fBpg_amcheck\fR [\fIoption\fR...] [\fIdbname\fR] +.SH "DESCRIPTION" +.PP +pg_amcheck +supports running +amcheck\*(Aqs corruption checking functions against one or more databases, with options to select which schemas, tables and indexes to check, which kinds of checking to perform, and whether to perform the checks in parallel, and if so, the number of parallel connections to establish and use\&. +.PP +Only ordinary and toast table relations, materialized views, sequences, and btree indexes are currently supported\&. Other relation types are silently skipped\&. +.PP +If +dbname +is specified, it should be the name of a single database to check, and no other database selection options should be present\&. Otherwise, if any database selection options are present, all matching databases will be checked\&. If no such options are present, the default database will be checked\&. Database selection options include +\fB\-\-all\fR, +\fB\-\-database\fR +and +\fB\-\-exclude\-database\fR\&. They also include +\fB\-\-relation\fR, +\fB\-\-exclude\-relation\fR, +\fB\-\-table\fR, +\fB\-\-exclude\-table\fR, +\fB\-\-index\fR, and +\fB\-\-exclude\-index\fR, but only when such options are used with a three\-part pattern (e\&.g\&. +\fBmydb*\&.myschema*\&.myrel*\fR)\&. Finally, they include +\fB\-\-schema\fR +and +\fB\-\-exclude\-schema\fR +when such options are used with a two\-part pattern (e\&.g\&. +\fBmydb*\&.myschema*\fR)\&. +.PP +\fIdbname\fR +can also be a +connection string\&. +.SH "OPTIONS" +.PP +The following command\-line options control what is checked: +.PP +\fB\-a\fR +.br +\fB\-\-all\fR +.RS 4 +Check all databases, except for any excluded via +\fB\-\-exclude\-database\fR\&. +.RE +.PP +\fB\-d \fR\fB\fIpattern\fR\fR +.br +\fB\-\-database=\fR\fB\fIpattern\fR\fR +.RS 4 +Check databases matching the specified +\fIpattern\fR, except for any excluded by +\fB\-\-exclude\-database\fR\&. This option can be specified more than once\&. +.RE +.PP +\fB\-D \fR\fB\fIpattern\fR\fR +.br +\fB\-\-exclude\-database=\fR\fB\fIpattern\fR\fR +.RS 4 +Exclude databases matching the given +\fIpattern\fR\&. This option can be specified more than once\&. +.RE +.PP +\fB\-i \fR\fB\fIpattern\fR\fR +.br +\fB\-\-index=\fR\fB\fIpattern\fR\fR +.RS 4 +Check indexes matching the specified +\fIpattern\fR, unless they are otherwise excluded\&. This option can be specified more than once\&. +.sp +This is similar to the +\fB\-\-relation\fR +option, except that it applies only to indexes, not to other relation types\&. +.RE +.PP +\fB\-I \fR\fB\fIpattern\fR\fR +.br +\fB\-\-exclude\-index=\fR\fB\fIpattern\fR\fR +.RS 4 +Exclude indexes matching the specified +\fIpattern\fR\&. This option can be specified more than once\&. +.sp +This is similar to the +\fB\-\-exclude\-relation\fR +option, except that it applies only to indexes, not other relation types\&. +.RE +.PP +\fB\-r \fR\fB\fIpattern\fR\fR +.br +\fB\-\-relation=\fR\fB\fIpattern\fR\fR +.RS 4 +Check relations matching the specified +\fIpattern\fR, unless they are otherwise excluded\&. This option can be specified more than once\&. +.sp +Patterns may be unqualified, e\&.g\&. +myrel*, or they may be schema\-qualified, e\&.g\&. +myschema*\&.myrel* +or database\-qualified and schema\-qualified, e\&.g\&. +mydb*\&.myschema*\&.myrel*\&. A database\-qualified pattern will add matching databases to the list of databases to be checked\&. +.RE +.PP +\fB\-R \fR\fB\fIpattern\fR\fR +.br +\fB\-\-exclude\-relation=\fR\fB\fIpattern\fR\fR +.RS 4 +Exclude relations matching the specified +\fIpattern\fR\&. This option can be specified more than once\&. +.sp +As with +\fB\-\-relation\fR, the +\fIpattern\fR +may be unqualified, schema\-qualified, or database\- and schema\-qualified\&. +.RE +.PP +\fB\-s \fR\fB\fIpattern\fR\fR +.br +\fB\-\-schema=\fR\fB\fIpattern\fR\fR +.RS 4 +Check tables and indexes in schemas matching the specified +\fIpattern\fR, unless they are otherwise excluded\&. This option can be specified more than once\&. +.sp +To select only tables in schemas matching a particular pattern, consider using something like +\-\-table=SCHEMAPAT\&.* \-\-no\-dependent\-indexes\&. To select only indexes, consider using something like +\-\-index=SCHEMAPAT\&.*\&. +.sp +A schema pattern may be database\-qualified\&. For example, you may write +\-\-schema=mydb*\&.myschema* +to select schemas matching +myschema* +in databases matching +mydb*\&. +.RE +.PP +\fB\-S \fR\fB\fIpattern\fR\fR +.br +\fB\-\-exclude\-schema=\fR\fB\fIpattern\fR\fR +.RS 4 +Exclude tables and indexes in schemas matching the specified +\fIpattern\fR\&. This option can be specified more than once\&. +.sp +As with +\fB\-\-schema\fR, the pattern may be database\-qualified\&. +.RE +.PP +\fB\-t \fR\fB\fIpattern\fR\fR +.br +\fB\-\-table=\fR\fB\fIpattern\fR\fR +.RS 4 +Check tables matching the specified +\fIpattern\fR, unless they are otherwise excluded\&. This option can be specified more than once\&. +.sp +This is similar to the +\fB\-\-relation\fR +option, except that it applies only to tables, materialized views, and sequences, not to indexes\&. +.RE +.PP +\fB\-T \fR\fB\fIpattern\fR\fR +.br +\fB\-\-exclude\-table=\fR\fB\fIpattern\fR\fR +.RS 4 +Exclude tables matching the specified +\fIpattern\fR\&. This option can be specified more than once\&. +.sp +This is similar to the +\fB\-\-exclude\-relation\fR +option, except that it applies only to tables, materialized views, and sequences, not to indexes\&. +.RE +.PP +\fB\-\-no\-dependent\-indexes\fR +.RS 4 +By default, if a table is checked, any btree indexes of that table will also be checked, even if they are not explicitly selected by an option such as +\-\-index +or +\-\-relation\&. This option suppresses that behavior\&. +.RE +.PP +\fB\-\-no\-dependent\-toast\fR +.RS 4 +By default, if a table is checked, its toast table, if any, will also be checked, even if it is not explicitly selected by an option such as +\-\-table +or +\-\-relation\&. This option suppresses that behavior\&. +.RE +.PP +\fB\-\-no\-strict\-names\fR +.RS 4 +By default, if an argument to +\-\-database, +\-\-table, +\-\-index, or +\-\-relation +matches no objects, it is a fatal error\&. This option downgrades that error to a warning\&. +.RE +.PP +The following command\-line options control checking of tables: +.PP +\fB\-\-exclude\-toast\-pointers\fR +.RS 4 +By default, whenever a toast pointer is encountered in a table, a lookup is performed to ensure that it references apparently\-valid entries in the toast table\&. These checks can be quite slow, and this option can be used to skip them\&. +.RE +.PP +\fB\-\-on\-error\-stop\fR +.RS 4 +After reporting all corruptions on the first page of a table where corruption is found, stop processing that table relation and move on to the next table or index\&. +.sp +Note that index checking always stops after the first corrupt page\&. This option only has meaning relative to table relations\&. +.RE +.PP +\fB\-\-skip=\fR\fB\fIoption\fR\fR +.RS 4 +If +all\-frozen +is given, table corruption checks will skip over pages in all tables that are marked as all frozen\&. +.sp +If +all\-visible +is given, table corruption checks will skip over pages in all tables that are marked as all visible\&. +.sp +By default, no pages are skipped\&. This can be specified as +none, but since this is the default, it need not be mentioned\&. +.RE +.PP +\fB\-\-startblock=\fR\fB\fIblock\fR\fR +.RS 4 +Start checking at the specified block number\&. An error will occur if the table relation being checked has fewer than this number of blocks\&. This option does not apply to indexes, and is probably only useful when checking a single table relation\&. See +\-\-endblock +for further caveats\&. +.RE +.PP +\fB\-\-endblock=\fR\fB\fIblock\fR\fR +.RS 4 +End checking at the specified block number\&. An error will occur if the table relation being checked has fewer than this number of blocks\&. This option does not apply to indexes, and is probably only useful when checking a single table relation\&. If both a regular table and a toast table are checked, this option will apply to both, but higher\-numbered toast blocks may still be accessed while validating toast pointers, unless that is suppressed using +\fB\-\-exclude\-toast\-pointers\fR\&. +.RE +.PP +The following command\-line options control checking of B\-tree indexes: +.PP +\fB\-\-heapallindexed\fR +.RS 4 +For each index checked, verify the presence of all heap tuples as index tuples in the index using +amcheck\*(Aqs +\fBheapallindexed\fR +option\&. +.RE +.PP +\fB\-\-parent\-check\fR +.RS 4 +For each btree index checked, use +amcheck\*(Aqs +\fBbt_index_parent_check\fR +function, which performs additional checks of parent/child relationships during index checking\&. +.sp +The default is to use +amcheck\*(Aqs +\fBbt_index_check\fR +function, but note that use of the +\fB\-\-rootdescend\fR +option implicitly selects +\fBbt_index_parent_check\fR\&. +.RE +.PP +\fB\-\-rootdescend\fR +.RS 4 +For each index checked, re\-find tuples on the leaf level by performing a new search from the root page for each tuple using +amcheck\*(Aqs +\fBrootdescend\fR +option\&. +.sp +Use of this option implicitly also selects the +\fB\-\-parent\-check\fR +option\&. +.sp +This form of verification was originally written to help in the development of btree index features\&. It may be of limited use or even of no use in helping detect the kinds of corruption that occur in practice\&. It may also cause corruption checking to take considerably longer and consume considerably more resources on the server\&. +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +.PP +The extra checks performed against B\-tree indexes when the +\fB\-\-parent\-check\fR +option or the +\fB\-\-rootdescend\fR +option is specified require relatively strong relation\-level locks\&. These checks are the only checks that will block concurrent data modification from +\fBINSERT\fR, +\fBUPDATE\fR, and +\fBDELETE\fR +commands\&. +.sp .5v +.RE +.PP +The following command\-line options control the connection to the server: +.PP +\fB\-h \fR\fB\fIhostname\fR\fR +.br +\fB\-\-host=\fR\fB\fIhostname\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. +.RE +.PP +\fB\-U\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +pg_amcheck +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +pg_amcheck +will automatically prompt for a password if the server demands password authentication\&. However, +pg_amcheck +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +\fB\-\-maintenance\-db=\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies a database or +connection string +to be used to discover the list of databases to be checked\&. If neither +\fB\-\-all\fR +nor any option including a database pattern is used, no such connection is required and this option does nothing\&. Otherwise, any connection string parameters other than the database name which are included in the value for this option will also be used when connecting to the databases being checked\&. If this option is omitted, the default is +postgres +or, if that fails, +template1\&. +.RE +.PP +Other options are also available: +.PP +\fB\-e\fR +.br +\fB\-\-echo\fR +.RS 4 +Echo to stdout all SQL sent to the server\&. +.RE +.PP +\fB\-j \fR\fB\fInum\fR\fR +.br +\fB\-\-jobs=\fR\fB\fInum\fR\fR +.RS 4 +Use +\fInum\fR +concurrent connections to the server, or one per object to be checked, whichever is less\&. +.sp +The default is to use a single connection\&. +.RE +.PP +\fB\-P\fR +.br +\fB\-\-progress\fR +.RS 4 +Show progress information\&. Progress information includes the number of relations for which checking has been completed, and the total size of those relations\&. It also includes the total number of relations that will eventually be checked, and the estimated size of those relations\&. +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Print more messages\&. In particular, this will print a message for each relation being checked, and will increase the level of detail shown for server errors\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_amcheck +version and exit\&. +.RE +.PP +\fB\-\-install\-missing\fR +.br +\fB\-\-install\-missing=\fR\fB\fIschema\fR\fR +.RS 4 +Install any missing extensions that are required to check the database(s)\&. If not yet installed, each extension\*(Aqs objects will be installed into the given +\fIschema\fR, or if not specified into schema +pg_catalog\&. +.sp +At present, the only required extension is +amcheck\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_amcheck +command line arguments, and exit\&. +.RE +.SH "NOTES" +.PP +pg_amcheck +is designed to work with +PostgreSQL +14\&.0 and later\&. +.SH "SEE ALSO" +amcheck diff --git a/doc/src/sgml/man1/pg_archivecleanup.1 b/doc/src/sgml/man1/pg_archivecleanup.1 new file mode 100644 index 0000000..ce693f7 --- /dev/null +++ b/doc/src/sgml/man1/pg_archivecleanup.1 @@ -0,0 +1,207 @@ +'\" t +.\" Title: pg_archivecleanup +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_ARCHIVECLEANUP" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_archivecleanup \- clean up PostgreSQL WAL archive files +.SH "SYNOPSIS" +.HP \w'\fBpg_archivecleanup\fR\ 'u +\fBpg_archivecleanup\fR [\fIoption\fR...] \fIarchivelocation\fR \fIoldestkeptwalfile\fR +.SH "DESCRIPTION" +.PP +pg_archivecleanup +is designed to be used as an +archive_cleanup_command +to clean up WAL file archives when running as a standby server (see +Section\ \&27.2)\&. +pg_archivecleanup +can also be used as a standalone program to clean WAL file archives\&. +.PP +To configure a standby server to use +pg_archivecleanup, put this into its +postgresql\&.conf +configuration file: +.sp +.if n \{\ +.RS 4 +.\} +.nf +archive_cleanup_command = \*(Aqpg_archivecleanup \fIarchivelocation\fR %r\*(Aq +.fi +.if n \{\ +.RE +.\} +.sp +where +\fIarchivelocation\fR +is the directory from which WAL segment files should be removed\&. +.PP +When used within +archive_cleanup_command, all WAL files logically preceding the value of the +%r +argument will be removed from +\fIarchivelocation\fR\&. This minimizes the number of files that need to be retained, while preserving crash\-restart capability\&. Use of this parameter is appropriate if the +\fIarchivelocation\fR +is a transient staging area for this particular standby server, but +\fInot\fR +when the +\fIarchivelocation\fR +is intended as a long\-term WAL archive area, or when multiple standby servers are recovering from the same archive location\&. +.PP +When used as a standalone program all WAL files logically preceding the +\fIoldestkeptwalfile\fR +will be removed from +\fIarchivelocation\fR\&. In this mode, if you specify a +\&.partial +or +\&.backup +file name, then only the file prefix will be used as the +\fIoldestkeptwalfile\fR\&. This treatment of +\&.backup +file name allows you to remove all WAL files archived prior to a specific base backup without error\&. For example, the following example will remove all files older than WAL file name +000000010000003700000010: +.sp +.if n \{\ +.RS 4 +.\} +.nf +pg_archivecleanup \-d archive 000000010000003700000010\&.00000020\&.backup + +pg_archivecleanup: keep WAL file "archive/000000010000003700000010" and later +pg_archivecleanup: removing file "archive/00000001000000370000000F" +pg_archivecleanup: removing file "archive/00000001000000370000000E" +.fi +.if n \{\ +.RE +.\} +.PP +pg_archivecleanup +assumes that +\fIarchivelocation\fR +is a directory readable and writable by the server\-owning user\&. +.SH "OPTIONS" +.PP +pg_archivecleanup +accepts the following command\-line arguments: +.PP +\fB\-d\fR +.RS 4 +Print lots of debug logging output on +stderr\&. +.RE +.PP +\fB\-n\fR +.RS 4 +Print the names of the files that would have been removed on +stdout +(performs a dry run)\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_archivecleanup +version and exit\&. +.RE +.PP +\fB\-x\fR \fIextension\fR +.RS 4 +Provide an extension that will be stripped from all file names before deciding if they should be deleted\&. This is typically useful for cleaning up archives that have been compressed during storage, and therefore have had an extension added by the compression program\&. For example: +\-x \&.gz\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_archivecleanup +command line arguments, and exit\&. +.RE +.SH "ENVIRONMENT" +.PP +The environment variable +\fBPG_COLOR\fR +specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.SH "NOTES" +.PP +pg_archivecleanup +is designed to work with +PostgreSQL +8\&.0 and later when used as a standalone utility, or with +PostgreSQL +9\&.0 and later when used as an archive cleanup command\&. +.PP +pg_archivecleanup +is written in C and has an easy\-to\-modify source code, with specifically designated sections to modify for your own needs +.SH "EXAMPLES" +.PP +On Linux or Unix systems, you might use: +.sp +.if n \{\ +.RS 4 +.\} +.nf +archive_cleanup_command = \*(Aqpg_archivecleanup \-d /mnt/standby/archive %r 2>>cleanup\&.log\*(Aq +.fi +.if n \{\ +.RE +.\} +.sp +where the archive directory is physically located on the standby server, so that the +\fIarchive_command\fR +is accessing it across NFS, but the files are local to the standby\&. This will: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +produce debugging output in +cleanup\&.log +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +remove no\-longer\-needed files from the archive directory +.RE diff --git a/doc/src/sgml/man1/pg_basebackup.1 b/doc/src/sgml/man1/pg_basebackup.1 new file mode 100644 index 0000000..28603f9 --- /dev/null +++ b/doc/src/sgml/man1/pg_basebackup.1 @@ -0,0 +1,756 @@ +'\" t +.\" Title: pg_basebackup +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_BASEBACKUP" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_basebackup \- take a base backup of a PostgreSQL cluster +.SH "SYNOPSIS" +.HP \w'\fBpg_basebackup\fR\ 'u +\fBpg_basebackup\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +pg_basebackup +is used to take a base backup of a running +PostgreSQL +database cluster\&. The backup is taken without affecting other clients of the database, and can be used both for point\-in\-time recovery (see +Section\ \&26.3) and as the starting point for a log\-shipping or streaming\-replication standby server (see +Section\ \&27.2)\&. +.PP +pg_basebackup +makes an exact copy of the database cluster\*(Aqs files, while making sure the server is put into and out of backup mode automatically\&. Backups are always taken of the entire database cluster; it is not possible to back up individual databases or database objects\&. For selective backups, another tool such as +\fBpg_dump\fR(1) +must be used\&. +.PP +The backup is made over a regular +PostgreSQL +connection that uses the replication protocol\&. The connection must be made with a user ID that has +REPLICATION +permissions (see +Section\ \&22.2) or is a superuser, and +pg_hba\&.conf +must permit the replication connection\&. The server must also be configured with +max_wal_senders +set high enough to provide at least one walsender for the backup plus one for WAL streaming (if used)\&. +.PP +There can be multiple +\fBpg_basebackup\fRs running at the same time, but it is usually better from a performance point of view to take only one backup, and copy the result\&. +.PP +pg_basebackup +can make a base backup from not only a primary server but also a standby\&. To take a backup from a standby, set up the standby so that it can accept replication connections (that is, set +\fImax_wal_senders\fR +and +hot_standby, and configure its +pg_hba\&.conf +appropriately)\&. You will also need to enable +full_page_writes +on the primary\&. +.PP +Note that there are some limitations in taking a backup from a standby: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The backup history file is not created in the database cluster backed up\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +pg_basebackup +cannot force the standby to switch to a new WAL file at the end of backup\&. When you are using +\-X none, if write activity on the primary is low, +pg_basebackup +may need to wait a long time for the last WAL file required for the backup to be switched and archived\&. In this case, it may be useful to run +\fBpg_switch_wal\fR +on the primary in order to trigger an immediate WAL file switch\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If the standby is promoted to be primary during backup, the backup fails\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +All WAL records required for the backup must contain sufficient full\-page writes, which requires you to enable +\fIfull_page_writes\fR +on the primary\&. +.RE +.PP +Whenever +pg_basebackup +is taking a base backup, the server\*(Aqs +pg_stat_progress_basebackup +view will report the progress of the backup\&. See +Section\ \&28.4.5 +for details\&. +.SH "OPTIONS" +.PP +The following command\-line options control the location and format of the output: +.PP +\fB\-D \fR\fB\fIdirectory\fR\fR +.br +\fB\-\-pgdata=\fR\fB\fIdirectory\fR\fR +.RS 4 +Sets the target directory to write the output to\&. +pg_basebackup +will create this directory (and any missing parent directories) if it does not exist\&. If it already exists, it must be empty\&. +.sp +When the backup is in tar format, the target directory may be specified as +\- +(dash), causing the tar file to be written to +stdout\&. +.sp +This option is required\&. +.RE +.PP +\fB\-F \fR\fB\fIformat\fR\fR +.br +\fB\-\-format=\fR\fB\fIformat\fR\fR +.RS 4 +Selects the format for the output\&. +\fIformat\fR +can be one of the following: +.PP +p +.br +plain +.RS 4 +Write the output as plain files, with the same layout as the source server\*(Aqs data directory and tablespaces\&. When the cluster has no additional tablespaces, the whole database will be placed in the target directory\&. If the cluster contains additional tablespaces, the main data directory will be placed in the target directory, but all other tablespaces will be placed in the same absolute path as they have on the source server\&. (See +\fB\-\-tablespace\-mapping\fR +to change that\&.) +.sp +This is the default format\&. +.RE +.PP +t +.br +tar +.RS 4 +Write the output as tar files in the target directory\&. The main data directory\*(Aqs contents will be written to a file named +base\&.tar, and each other tablespace will be written to a separate tar file named after that tablespace\*(Aqs OID\&. +.sp +If the target directory is specified as +\- +(dash), the tar contents will be written to standard output, suitable for piping to (for example) +gzip\&. This is only allowed if the cluster has no additional tablespaces and WAL streaming is not used\&. +.RE +.RE +.PP +\fB\-R\fR +.br +\fB\-\-write\-recovery\-conf\fR +.RS 4 +Creates a +standby\&.signal + +file and appends connection settings to the +postgresql\&.auto\&.conf +file in the target directory (or within the base archive file when using tar format)\&. This eases setting up a standby server using the results of the backup\&. +.sp +The +postgresql\&.auto\&.conf +file will record the connection settings and, if specified, the replication slot that +pg_basebackup +is using, so that streaming replication will use the same settings later on\&. +.RE +.PP +\fB\-t \fR\fB\fItarget\fR\fR +.br +\fB\-\-target=\fR\fB\fItarget\fR\fR +.RS 4 +Instructs the server where to place the base backup\&. The default target is +client, which specifies that the backup should be sent to the machine where +pg_basebackup +is running\&. If the target is instead set to +server:/some/path, the backup will be stored on the machine where the server is running in the +/some/path +directory\&. Storing a backup on the server requires superuser privileges or having privileges of the +pg_write_server_files +role\&. If the target is set to +blackhole, the contents are discarded and not stored anywhere\&. This should only be used for testing purposes, as you will not end up with an actual backup\&. +.sp +Since WAL streaming is implemented by +pg_basebackup +rather than by the server, this option cannot be used together with +\-Xstream\&. Since that is the default, when this option is specified, you must also specify either +\-Xfetch +or +\-Xnone\&. +.RE +.PP +\fB\-T \fR\fB\fIolddir\fR\fR\fB=\fR\fB\fInewdir\fR\fR +.br +\fB\-\-tablespace\-mapping=\fR\fB\fIolddir\fR\fR\fB=\fR\fB\fInewdir\fR\fR +.RS 4 +Relocates the tablespace in directory +\fIolddir\fR +to +\fInewdir\fR +during the backup\&. To be effective, +\fIolddir\fR +must exactly match the path specification of the tablespace as it is defined on the source server\&. (But it is not an error if there is no tablespace in +\fIolddir\fR +on the source server\&.) Meanwhile +\fInewdir\fR +is a directory in the receiving host\*(Aqs filesystem\&. As with the main target directory, +\fInewdir\fR +need not exist already, but if it does exist it must be empty\&. Both +\fIolddir\fR +and +\fInewdir\fR +must be absolute paths\&. If either path needs to contain an equal sign (=), precede that with a backslash\&. This option can be specified multiple times for multiple tablespaces\&. +.sp +If a tablespace is relocated in this way, the symbolic links inside the main data directory are updated to point to the new location\&. So the new data directory is ready to be used for a new server instance with all tablespaces in the updated locations\&. +.sp +Currently, this option only works with plain output format; it is ignored if tar format is selected\&. +.RE +.PP +\fB\-\-waldir=\fR\fB\fIwaldir\fR\fR +.RS 4 +Sets the directory to write WAL (write\-ahead log) files to\&. By default WAL files will be placed in the +pg_wal +subdirectory of the target directory, but this option can be used to place them elsewhere\&. +\fIwaldir\fR +must be an absolute path\&. As with the main target directory, +\fIwaldir\fR +need not exist already, but if it does exist it must be empty\&. This option can only be specified when the backup is in plain format\&. +.RE +.PP +\fB\-X \fR\fB\fImethod\fR\fR +.br +\fB\-\-wal\-method=\fR\fB\fImethod\fR\fR +.RS 4 +Includes the required WAL (write\-ahead log) files in the backup\&. This will include all write\-ahead logs generated during the backup\&. Unless the method +none +is specified, it is possible to start a postmaster in the target directory without the need to consult the log archive, thus making the output a completely standalone backup\&. +.sp +The following +\fImethod\fRs for collecting the write\-ahead logs are supported: +.PP +n +.br +none +.RS 4 +Don\*(Aqt include write\-ahead logs in the backup\&. +.RE +.PP +f +.br +fetch +.RS 4 +The write\-ahead log files are collected at the end of the backup\&. Therefore, it is necessary for the source server\*(Aqs +wal_keep_size +parameter to be set high enough that the required log data is not removed before the end of the backup\&. If the required log data has been recycled before it\*(Aqs time to transfer it, the backup will fail and be unusable\&. +.sp +When tar format is used, the write\-ahead log files will be included in the +base\&.tar +file\&. +.RE +.PP +s +.br +stream +.RS 4 +Stream write\-ahead log data while the backup is being taken\&. This method will open a second connection to the server and start streaming the write\-ahead log in parallel while running the backup\&. Therefore, it will require two replication connections not just one\&. As long as the client can keep up with the write\-ahead log data, using this method requires no extra write\-ahead logs to be saved on the source server\&. +.sp +When tar format is used, the write\-ahead log files will be written to a separate file named +pg_wal\&.tar +(if the server is a version earlier than 10, the file will be named +pg_xlog\&.tar)\&. +.sp +This value is the default\&. +.RE +.RE +.PP +\fB\-z\fR +.br +\fB\-\-gzip\fR +.RS 4 +Enables gzip compression of tar file output, with the default compression level\&. Compression is only available when using the tar format, and the suffix +\&.gz +will automatically be added to all tar filenames\&. +.RE +.PP +\fB\-Z \fR\fB\fIlevel\fR\fR +.br +\fB\-Z [{client|server}\-]\fR\fB\fImethod\fR\fR\fB[:\fR\fB\fIdetail\fR\fR\fB]\fR +.br +\fB\-\-compress=\fR\fB\fIlevel\fR\fR +.br +\fB\-\-compress=[{client|server}\-]\fR\fB\fImethod\fR\fR\fB[:\fR\fB\fIdetail\fR\fR\fB]\fR +.RS 4 +Requests compression of the backup\&. If +client +or +server +is included, it specifies where the compression is to be performed\&. Compressing on the server will reduce transfer bandwidth but will increase server CPU consumption\&. The default is +client +except when +\-\-target +is used\&. In that case, the backup is not being sent to the client, so only server compression is sensible\&. When +\-Xstream, which is the default, is used, server\-side compression will not be applied to the WAL\&. To compress the WAL, use client\-side compression, or specify +\-Xfetch\&. +.sp +The compression method can be set to +gzip, +lz4, +zstd, or +none +for no compression\&. A compression detail string can optionally be specified\&. If the detail string is an integer, it specifies the compression level\&. Otherwise, it should be a comma\-separated list of items, each of the form +keyword +or +keyword=value\&. Currently, the supported keywords are +level +and +workers\&. +.sp +If no compression level is specified, the default compression level will be used\&. If only a level is specified without mentioning an algorithm, +gzip +compression will be used if the level is greater than 0, and no compression will be used if the level is 0\&. +.sp +When the tar format is used with +gzip, +lz4, or +zstd, the suffix +\&.gz, +\&.lz4, or +\&.zst, respectively, will be automatically added to all tar filenames\&. When the plain format is used, client\-side compression may not be specified, but it is still possible to request server\-side compression\&. If this is done, the server will compress the backup for transmission, and the client will decompress and extract it\&. +.sp +When this option is used in combination with +\-Xstream, +pg_wal\&.tar +will be compressed using +gzip +if client\-side gzip compression is selected, but will not be compressed if any other compression algorithm is selected, or if server\-side compression is selected\&. +.RE +.PP +The following command\-line options control the generation of the backup and the invocation of the program: +.PP +\fB\-c {fast|spread}\fR +.br +\fB\-\-checkpoint={fast|spread}\fR +.RS 4 +Sets checkpoint mode to fast (immediate) or spread (the default) (see +Section\ \&26.3.3)\&. +.RE +.PP +\fB\-C\fR +.br +\fB\-\-create\-slot\fR +.RS 4 +Specifies that the replication slot named by the +\-\-slot +option should be created before starting the backup\&. An error is raised if the slot already exists\&. +.RE +.PP +\fB\-l \fR\fB\fIlabel\fR\fR +.br +\fB\-\-label=\fR\fB\fIlabel\fR\fR +.RS 4 +Sets the label for the backup\&. If none is specified, a default value of +\(lqpg_basebackup base backup\(rq +will be used\&. +.RE +.PP +\fB\-n\fR +.br +\fB\-\-no\-clean\fR +.RS 4 +By default, when +\fBpg_basebackup\fR +aborts with an error, it removes any directories it might have created before discovering that it cannot finish the job (for example, the target directory and write\-ahead log directory)\&. This option inhibits tidying\-up and is thus useful for debugging\&. +.sp +Note that tablespace directories are not cleaned up either way\&. +.RE +.PP +\fB\-N\fR +.br +\fB\-\-no\-sync\fR +.RS 4 +By default, +\fBpg_basebackup\fR +will wait for all files to be written safely to disk\&. This option causes +\fBpg_basebackup\fR +to return without waiting, which is faster, but means that a subsequent operating system crash can leave the base backup corrupt\&. Generally, this option is useful for testing but should not be used when creating a production installation\&. +.RE +.PP +\fB\-P\fR +.br +\fB\-\-progress\fR +.RS 4 +Enables progress reporting\&. Turning this on will deliver an approximate progress report during the backup\&. Since the database may change during the backup, this is only an approximation and may not end at exactly +100%\&. In particular, when WAL log is included in the backup, the total amount of data cannot be estimated in advance, and in this case the estimated target size will increase once it passes the total estimate without WAL\&. +.RE +.PP +\fB\-r \fR\fB\fIrate\fR\fR +.br +\fB\-\-max\-rate=\fR\fB\fIrate\fR\fR +.RS 4 +Sets the maximum transfer rate at which data is collected from the source server\&. This can be useful to limit the impact of +pg_basebackup +on the server\&. Values are in kilobytes per second\&. Use a suffix of +M +to indicate megabytes per second\&. A suffix of +k +is also accepted, and has no effect\&. Valid values are between 32 kilobytes per second and 1024 megabytes per second\&. +.sp +This option always affects transfer of the data directory\&. Transfer of WAL files is only affected if the collection method is +fetch\&. +.RE +.PP +\fB\-S \fR\fB\fIslotname\fR\fR +.br +\fB\-\-slot=\fR\fB\fIslotname\fR\fR +.RS 4 +This option can only be used together with +\-X stream\&. It causes WAL streaming to use the specified replication slot\&. If the base backup is intended to be used as a streaming\-replication standby using a replication slot, the standby should then use the same replication slot name as +primary_slot_name\&. This ensures that the primary server does not remove any necessary WAL data in the time between the end of the base backup and the start of streaming replication on the new standby\&. +.sp +The specified replication slot has to exist unless the option +\fB\-C\fR +is also used\&. +.sp +If this option is not specified and the server supports temporary replication slots (version 10 and later), then a temporary replication slot is automatically used for WAL streaming\&. +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Enables verbose mode\&. Will output some extra steps during startup and shutdown, as well as show the exact file name that is currently being processed if progress reporting is also enabled\&. +.RE +.PP +\fB\-\-manifest\-checksums=\fR\fB\fIalgorithm\fR\fR +.RS 4 +Specifies the checksum algorithm that should be applied to each file included in the backup manifest\&. Currently, the available algorithms are +NONE, +CRC32C, +SHA224, +SHA256, +SHA384, and +SHA512\&. The default is +CRC32C\&. +.sp +If +NONE +is selected, the backup manifest will not contain any checksums\&. Otherwise, it will contain a checksum of each file in the backup using the specified algorithm\&. In addition, the manifest will always contain a +SHA256 +checksum of its own contents\&. The +SHA +algorithms are significantly more CPU\-intensive than +CRC32C, so selecting one of them may increase the time required to complete the backup\&. +.sp +Using a SHA hash function provides a cryptographically secure digest of each file for users who wish to verify that the backup has not been tampered with, while the CRC32C algorithm provides a checksum that is much faster to calculate; it is good at catching errors due to accidental changes but is not resistant to malicious modifications\&. Note that, to be useful against an adversary who has access to the backup, the backup manifest would need to be stored securely elsewhere or otherwise verified not to have been modified since the backup was taken\&. +.sp +\fBpg_verifybackup\fR(1) +can be used to check the integrity of a backup against the backup manifest\&. +.RE +.PP +\fB\-\-manifest\-force\-encode\fR +.RS 4 +Forces all filenames in the backup manifest to be hex\-encoded\&. If this option is not specified, only non\-UTF8 filenames are hex\-encoded\&. This option is mostly intended to test that tools which read a backup manifest file properly handle this case\&. +.RE +.PP +\fB\-\-no\-estimate\-size\fR +.RS 4 +Prevents the server from estimating the total amount of backup data that will be streamed, resulting in the +backup_total +column in the +pg_stat_progress_basebackup +view always being +NULL\&. +.sp +Without this option, the backup will start by enumerating the size of the entire database, and then go back and send the actual contents\&. This may make the backup take slightly longer, and in particular it will take longer before the first data is sent\&. This option is useful to avoid such estimation time if it\*(Aqs too long\&. +.sp +This option is not allowed when using +\fB\-\-progress\fR\&. +.RE +.PP +\fB\-\-no\-manifest\fR +.RS 4 +Disables generation of a backup manifest\&. If this option is not specified, the server will generate and send a backup manifest which can be verified using +\fBpg_verifybackup\fR(1)\&. The manifest is a list of every file present in the backup with the exception of any WAL files that may be included\&. It also stores the size, last modification time, and an optional checksum for each file\&. +.RE +.PP +\fB\-\-no\-slot\fR +.RS 4 +Prevents the creation of a temporary replication slot for the backup\&. +.sp +By default, if log streaming is selected but no slot name is given with the +\fB\-S\fR +option, then a temporary replication slot is created (if supported by the source server)\&. +.sp +The main purpose of this option is to allow taking a base backup when the server has no free replication slots\&. Using a replication slot is almost always preferred, because it prevents needed WAL from being removed by the server during the backup\&. +.RE +.PP +\fB\-\-no\-verify\-checksums\fR +.RS 4 +Disables verification of checksums, if they are enabled on the server the base backup is taken from\&. +.sp +By default, checksums are verified and checksum failures will result in a non\-zero exit status\&. However, the base backup will not be removed in such a case, as if the +\fB\-\-no\-clean\fR +option had been used\&. Checksum verification failures will also be reported in the +pg_stat_database +view\&. +.RE +.PP +The following command\-line options control the connection to the source server: +.PP +\fB\-d \fR\fB\fIconnstr\fR\fR +.br +\fB\-\-dbname=\fR\fB\fIconnstr\fR\fR +.RS 4 +Specifies parameters used to connect to the server, as a +connection string; these will override any conflicting command line options\&. +.sp +The option is called +\-\-dbname +for consistency with other client applications, but because +pg_basebackup +doesn\*(Aqt connect to any particular database in the cluster, any database name in the connection string will be ignored\&. +.RE +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for a Unix domain socket\&. The default is taken from the +\fBPGHOST\fR +environment variable, if set, else a Unix domain socket connection is attempted\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. Defaults to the +\fBPGPORT\fR +environment variable, if set, or a compiled\-in default\&. +.RE +.PP +\fB\-s \fR\fB\fIinterval\fR\fR +.br +\fB\-\-status\-interval=\fR\fB\fIinterval\fR\fR +.RS 4 +Specifies the number of seconds between status packets sent back to the source server\&. Smaller values allow more accurate monitoring of backup progress from the server\&. A value of zero disables periodic status updates completely, although an update will still be sent when requested by the server, to avoid timeout\-based disconnects\&. The default value is 10 seconds\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +Specifies the user name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Prevents issuing a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Forces +pg_basebackup +to prompt for a password before connecting to the source server\&. +.sp +This option is never essential, since +pg_basebackup +will automatically prompt for a password if the server demands password authentication\&. However, +pg_basebackup +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +Other options are also available: +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Prints the +pg_basebackup +version and exits\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Shows help about +pg_basebackup +command line arguments, and exits\&. +.RE +.SH "ENVIRONMENT" +.PP +This utility, like most other +PostgreSQL +utilities, uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.PP +The environment variable +\fBPG_COLOR\fR +specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.SH "NOTES" +.PP +At the beginning of the backup, a checkpoint needs to be performed on the source server\&. This can take some time (especially if the option +\-\-checkpoint=fast +is not used), during which +pg_basebackup +will appear to be idle\&. +.PP +The backup will include all files in the data directory and tablespaces, including the configuration files and any additional files placed in the directory by third parties, except certain temporary files managed by PostgreSQL\&. But only regular files and directories are copied, except that symbolic links used for tablespaces are preserved\&. Symbolic links pointing to certain directories known to PostgreSQL are copied as empty directories\&. Other symbolic links and special device files are skipped\&. See +Section\ \&55.4 +for the precise details\&. +.PP +In plain format, tablespaces will be backed up to the same path they have on the source server, unless the option +\-\-tablespace\-mapping +is used\&. Without this option, running a plain format base backup on the same host as the server will not work if tablespaces are in use, because the backup would have to be written to the same directory locations as the original tablespaces\&. +.PP +When tar format is used, it is the user\*(Aqs responsibility to unpack each tar file before starting a PostgreSQL server that uses the data\&. If there are additional tablespaces, the tar files for them need to be unpacked in the correct locations\&. In this case the symbolic links for those tablespaces will be created by the server according to the contents of the +tablespace_map +file that is included in the +base\&.tar +file\&. +.PP +pg_basebackup +works with servers of the same or an older major version, down to 9\&.1\&. However, WAL streaming mode (\-X stream) only works with server version 9\&.3 and later, and tar format (\-\-format=tar) only works with server version 9\&.5 and later\&. +.PP +pg_basebackup +will preserve group permissions for data files if group permissions are enabled on the source cluster\&. +.SH "EXAMPLES" +.PP +To create a base backup of the server at +mydbserver +and store it in the local directory +/usr/local/pgsql/data: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_basebackup \-h mydbserver \-D /usr/local/pgsql/data\fR +.fi +.if n \{\ +.RE +.\} +.PP +To create a backup of the local server with one compressed tar file for each tablespace, and store it in the directory +backup, showing a progress report while running: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_basebackup \-D backup \-Ft \-z \-P\fR +.fi +.if n \{\ +.RE +.\} +.PP +To create a backup of a single\-tablespace local database and compress this with +bzip2: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_basebackup \-D \- \-Ft \-X fetch | bzip2 > backup\&.tar\&.bz2\fR +.fi +.if n \{\ +.RE +.\} +.sp +(This command will fail if there are multiple tablespaces in the database\&.) +.PP +To create a backup of a local database where the tablespace in +/opt/ts +is relocated to +\&./backup/ts: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_basebackup \-D backup/data \-T /opt/ts=$(pwd)/backup/ts\fR +.fi +.if n \{\ +.RE +.\} +.PP +To create a backup of a local server with one tar file for each tablespace compressed with +gzip +at level 9, stored in the directory +backup: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_basebackup \-D backup \-Ft \-\-compress=gzip:9\fR +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBpg_dump\fR(1), Section\ \&28.4.5 diff --git a/doc/src/sgml/man1/pg_checksums.1 b/doc/src/sgml/man1/pg_checksums.1 new file mode 100644 index 0000000..f107c1a --- /dev/null +++ b/doc/src/sgml/man1/pg_checksums.1 @@ -0,0 +1,156 @@ +'\" t +.\" Title: pg_checksums +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_CHECKSUMS" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_checksums \- enable, disable or check data checksums in a PostgreSQL database cluster +.SH "SYNOPSIS" +.HP \w'\fBpg_checksums\fR\ 'u +\fBpg_checksums\fR [\fIoption\fR...] [[\fB\-D\fR | \fB\-\-pgdata\fR]\fIdatadir\fR] +.SH "DESCRIPTION" +.PP +pg_checksums +checks, enables or disables data checksums in a +PostgreSQL +cluster\&. The server must be shut down cleanly before running +pg_checksums\&. When verifying checksums, the exit status is zero if there are no checksum errors, and nonzero if at least one checksum failure is detected\&. When enabling or disabling checksums, the exit status is nonzero if the operation failed\&. +.PP +When verifying checksums, every file in the cluster is scanned\&. When enabling checksums, each relation file block with a changed checksum is rewritten in\-place\&. Disabling checksums only updates the file +pg_control\&. +.SH "OPTIONS" +.PP +The following command\-line options are available: +.PP +\fB\-D \fR\fB\fIdirectory\fR\fR +.br +\fB\-\-pgdata=\fR\fB\fIdirectory\fR\fR +.RS 4 +Specifies the directory where the database cluster is stored\&. +.RE +.PP +\fB\-c\fR +.br +\fB\-\-check\fR +.RS 4 +Checks checksums\&. This is the default mode if nothing else is specified\&. +.RE +.PP +\fB\-d\fR +.br +\fB\-\-disable\fR +.RS 4 +Disables checksums\&. +.RE +.PP +\fB\-e\fR +.br +\fB\-\-enable\fR +.RS 4 +Enables checksums\&. +.RE +.PP +\fB\-f \fR\fB\fIfilenode\fR\fR +.br +\fB\-\-filenode=\fR\fB\fIfilenode\fR\fR +.RS 4 +Only validate checksums in the relation with filenode +\fIfilenode\fR\&. +.RE +.PP +\fB\-N\fR +.br +\fB\-\-no\-sync\fR +.RS 4 +By default, +\fBpg_checksums\fR +will wait for all files to be written safely to disk\&. This option causes +\fBpg_checksums\fR +to return without waiting, which is faster, but means that a subsequent operating system crash can leave the updated data directory corrupt\&. Generally, this option is useful for testing but should not be used on a production installation\&. This option has no effect when using +\-\-check\&. +.RE +.PP +\fB\-P\fR +.br +\fB\-\-progress\fR +.RS 4 +Enable progress reporting\&. Turning this on will deliver a progress report while checking or enabling checksums\&. +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Enable verbose output\&. Lists all checked files\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_checksums +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_checksums +command line arguments, and exit\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGDATA\fR +.RS 4 +Specifies the directory where the database cluster is stored; can be overridden using the +\fB\-D\fR +option\&. +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.SH "NOTES" +.PP +Enabling checksums in a large cluster can potentially take a long time\&. During this operation, the cluster or other programs that write to the data directory must not be started or else data loss may occur\&. +.PP +When using a replication setup with tools which perform direct copies of relation file blocks (for example +\fBpg_rewind\fR(1)), enabling or disabling checksums can lead to page corruptions in the shape of incorrect checksums if the operation is not done consistently across all nodes\&. When enabling or disabling checksums in a replication setup, it is thus recommended to stop all the clusters before switching them all consistently\&. Destroying all standbys, performing the operation on the primary and finally recreating the standbys from scratch is also safe\&. +.PP +If +pg_checksums +is aborted or killed while enabling or disabling checksums, the cluster\*(Aqs data checksum configuration remains unchanged, and +pg_checksums +can be re\-run to perform the same operation\&. diff --git a/doc/src/sgml/man1/pg_config.1 b/doc/src/sgml/man1/pg_config.1 new file mode 100644 index 0000000..160ce45 --- /dev/null +++ b/doc/src/sgml/man1/pg_config.1 @@ -0,0 +1,257 @@ +'\" t +.\" Title: pg_config +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_CONFIG" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_config \- retrieve information about the installed version of PostgreSQL +.SH "SYNOPSIS" +.HP \w'\fBpg_config\fR\ 'u +\fBpg_config\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +The +pg_config +utility prints configuration parameters of the currently installed version of +PostgreSQL\&. It is intended, for example, to be used by software packages that want to interface to +PostgreSQL +to facilitate finding the required header files and libraries\&. +.SH "OPTIONS" +.PP +To use +pg_config, supply one or more of the following options: +.PP +\fB\-\-bindir\fR +.RS 4 +Print the location of user executables\&. Use this, for example, to find the +\fBpsql\fR +program\&. This is normally also the location where the +pg_config +program resides\&. +.RE +.PP +\fB\-\-docdir\fR +.RS 4 +Print the location of documentation files\&. +.RE +.PP +\fB\-\-htmldir\fR +.RS 4 +Print the location of HTML documentation files\&. +.RE +.PP +\fB\-\-includedir\fR +.RS 4 +Print the location of C header files of the client interfaces\&. +.RE +.PP +\fB\-\-pkgincludedir\fR +.RS 4 +Print the location of other C header files\&. +.RE +.PP +\fB\-\-includedir\-server\fR +.RS 4 +Print the location of C header files for server programming\&. +.RE +.PP +\fB\-\-libdir\fR +.RS 4 +Print the location of object code libraries\&. +.RE +.PP +\fB\-\-pkglibdir\fR +.RS 4 +Print the location of dynamically loadable modules, or where the server would search for them\&. (Other architecture\-dependent data files might also be installed in this directory\&.) +.RE +.PP +\fB\-\-localedir\fR +.RS 4 +Print the location of locale support files\&. (This will be an empty string if locale support was not configured when +PostgreSQL +was built\&.) +.RE +.PP +\fB\-\-mandir\fR +.RS 4 +Print the location of manual pages\&. +.RE +.PP +\fB\-\-sharedir\fR +.RS 4 +Print the location of architecture\-independent support files\&. +.RE +.PP +\fB\-\-sysconfdir\fR +.RS 4 +Print the location of system\-wide configuration files\&. +.RE +.PP +\fB\-\-pgxs\fR +.RS 4 +Print the location of extension makefiles\&. +.RE +.PP +\fB\-\-configure\fR +.RS 4 +Print the options that were given to the +configure +script when +PostgreSQL +was configured for building\&. This can be used to reproduce the identical configuration, or to find out with what options a binary package was built\&. (Note however that binary packages often contain vendor\-specific custom patches\&.) See also the examples below\&. +.RE +.PP +\fB\-\-cc\fR +.RS 4 +Print the value of the +\fICC\fR +variable that was used for building +PostgreSQL\&. This shows the C compiler used\&. +.RE +.PP +\fB\-\-cppflags\fR +.RS 4 +Print the value of the +\fICPPFLAGS\fR +variable that was used for building +PostgreSQL\&. This shows C compiler switches needed at preprocessing time (typically, +\-I +switches)\&. +.RE +.PP +\fB\-\-cflags\fR +.RS 4 +Print the value of the +\fICFLAGS\fR +variable that was used for building +PostgreSQL\&. This shows C compiler switches\&. +.RE +.PP +\fB\-\-cflags_sl\fR +.RS 4 +Print the value of the +\fICFLAGS_SL\fR +variable that was used for building +PostgreSQL\&. This shows extra C compiler switches used for building shared libraries\&. +.RE +.PP +\fB\-\-ldflags\fR +.RS 4 +Print the value of the +\fILDFLAGS\fR +variable that was used for building +PostgreSQL\&. This shows linker switches\&. +.RE +.PP +\fB\-\-ldflags_ex\fR +.RS 4 +Print the value of the +\fILDFLAGS_EX\fR +variable that was used for building +PostgreSQL\&. This shows linker switches used for building executables only\&. +.RE +.PP +\fB\-\-ldflags_sl\fR +.RS 4 +Print the value of the +\fILDFLAGS_SL\fR +variable that was used for building +PostgreSQL\&. This shows linker switches used for building shared libraries only\&. +.RE +.PP +\fB\-\-libs\fR +.RS 4 +Print the value of the +\fILIBS\fR +variable that was used for building +PostgreSQL\&. This normally contains +\-l +switches for external libraries linked into +PostgreSQL\&. +.RE +.PP +\fB\-\-version\fR +.RS 4 +Print the version of +PostgreSQL\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_config +command line arguments, and exit\&. +.RE +If more than one option is given, the information is printed in that order, one item per line\&. If no options are given, all available information is printed, with labels\&. +.SH "NOTES" +.PP +The options +\fB\-\-docdir\fR, +\fB\-\-pkgincludedir\fR, +\fB\-\-localedir\fR, +\fB\-\-mandir\fR, +\fB\-\-sharedir\fR, +\fB\-\-sysconfdir\fR, +\fB\-\-cc\fR, +\fB\-\-cppflags\fR, +\fB\-\-cflags\fR, +\fB\-\-cflags_sl\fR, +\fB\-\-ldflags\fR, +\fB\-\-ldflags_sl\fR, and +\fB\-\-libs\fR +were added in +PostgreSQL +8\&.1\&. The option +\fB\-\-htmldir\fR +was added in +PostgreSQL +8\&.4\&. The option +\fB\-\-ldflags_ex\fR +was added in +PostgreSQL +9\&.0\&. +.SH "EXAMPLE" +.PP +To reproduce the build configuration of the current PostgreSQL installation, run the following command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +eval \&./configure `pg_config \-\-configure` +.fi +.if n \{\ +.RE +.\} +.sp +The output of +pg_config \-\-configure +contains shell quotation marks so arguments with spaces are represented correctly\&. Therefore, using +eval +is required for proper results\&. diff --git a/doc/src/sgml/man1/pg_controldata.1 b/doc/src/sgml/man1/pg_controldata.1 new file mode 100644 index 0000000..6bbe553 --- /dev/null +++ b/doc/src/sgml/man1/pg_controldata.1 @@ -0,0 +1,65 @@ +'\" t +.\" Title: pg_controldata +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_CONTROLDATA" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_controldata \- display control information of a PostgreSQL database cluster +.SH "SYNOPSIS" +.HP \w'\fBpg_controldata\fR\ 'u +\fBpg_controldata\fR [\fIoption\fR] [[\fB\-D\fR | \fB\-\-pgdata\fR]\fIdatadir\fR] +.SH "DESCRIPTION" +.PP +\fBpg_controldata\fR +prints information initialized during +\fBinitdb\fR, such as the catalog version\&. It also shows information about write\-ahead logging and checkpoint processing\&. This information is cluster\-wide, and not specific to any one database\&. +.PP +This utility can only be run by the user who initialized the cluster because it requires read access to the data directory\&. You can specify the data directory on the command line, or use the environment variable +\fBPGDATA\fR\&. This utility supports the options +\fB\-V\fR +and +\fB\-\-version\fR, which print the +pg_controldata +version and exit\&. It also supports options +\fB\-?\fR +and +\fB\-\-help\fR, which output the supported arguments\&. +.SH "ENVIRONMENT" +.PP +\fBPGDATA\fR +.RS 4 +Default data directory location +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE diff --git a/doc/src/sgml/man1/pg_ctl.1 b/doc/src/sgml/man1/pg_ctl.1 new file mode 100644 index 0000000..24a7c13 --- /dev/null +++ b/doc/src/sgml/man1/pg_ctl.1 @@ -0,0 +1,537 @@ +'\" t +.\" Title: pg_ctl +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_CTL" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_ctl \- initialize, start, stop, or control a PostgreSQL server +.SH "SYNOPSIS" +.HP \w'\fBpg_ctl\fR\ 'u +\fBpg_ctl\fR \fBinit[db]\fR [\fB\-D\fR\ \fIdatadir\fR] [\fB\-s\fR] [\fB\-o\fR\ \fIinitdb\-options\fR] +.HP \w'\fBpg_ctl\fR\ 'u +\fBpg_ctl\fR \fBstart\fR [\fB\-D\fR\ \fIdatadir\fR] [\fB\-l\fR\ \fIfilename\fR] [\fB\-W\fR] [\fB\-t\fR\ \fIseconds\fR] [\fB\-s\fR] [\fB\-o\fR\ \fIoptions\fR] [\fB\-p\fR\ \fIpath\fR] [\fB\-c\fR] +.HP \w'\fBpg_ctl\fR\ 'u +\fBpg_ctl\fR \fBstop\fR [\fB\-D\fR\ \fIdatadir\fR] [\fB\-m\fR\ \fBs[mart]\fR\ |\ \fBf[ast]\fR\ |\ \fBi[mmediate]\fR] [\fB\-W\fR] [\fB\-t\fR\ \fIseconds\fR] [\fB\-s\fR] +.HP \w'\fBpg_ctl\fR\ 'u +\fBpg_ctl\fR \fBrestart\fR [\fB\-D\fR\ \fIdatadir\fR] [\fB\-m\fR\ \fBs[mart]\fR\ |\ \fBf[ast]\fR\ |\ \fBi[mmediate]\fR] [\fB\-W\fR] [\fB\-t\fR\ \fIseconds\fR] [\fB\-s\fR] [\fB\-o\fR\ \fIoptions\fR] [\fB\-c\fR] +.HP \w'\fBpg_ctl\fR\ 'u +\fBpg_ctl\fR \fBreload\fR [\fB\-D\fR\ \fIdatadir\fR] [\fB\-s\fR] +.HP \w'\fBpg_ctl\fR\ 'u +\fBpg_ctl\fR \fBstatus\fR [\fB\-D\fR\ \fIdatadir\fR] +.HP \w'\fBpg_ctl\fR\ 'u +\fBpg_ctl\fR \fBpromote\fR [\fB\-D\fR\ \fIdatadir\fR] [\fB\-W\fR] [\fB\-t\fR\ \fIseconds\fR] [\fB\-s\fR] +.HP \w'\fBpg_ctl\fR\ 'u +\fBpg_ctl\fR \fBlogrotate\fR [\fB\-D\fR\ \fIdatadir\fR] [\fB\-s\fR] +.HP \w'\fBpg_ctl\fR\ 'u +\fBpg_ctl\fR \fBkill\fR \fIsignal_name\fR \fIprocess_id\fR +.PP +On Microsoft Windows, also: +.HP \w'\fBpg_ctl\fR\ 'u +\fBpg_ctl\fR \fBregister\fR [\fB\-D\fR\ \fIdatadir\fR] [\fB\-N\fR\ \fIservicename\fR] [\fB\-U\fR\ \fIusername\fR] [\fB\-P\fR\ \fIpassword\fR] [\fB\-S\fR\ \fBa[uto]\fR\ |\ \fBd[emand]\fR] [\fB\-e\fR\ \fIsource\fR] [\fB\-W\fR] [\fB\-t\fR\ \fIseconds\fR] [\fB\-s\fR] [\fB\-o\fR\ \fIoptions\fR] +.HP \w'\fBpg_ctl\fR\ 'u +\fBpg_ctl\fR \fBunregister\fR [\fB\-N\fR\ \fIservicename\fR] +.SH "DESCRIPTION" +.PP +pg_ctl +is a utility for initializing a +PostgreSQL +database cluster, starting, stopping, or restarting the +PostgreSQL +database server (\fBpostgres\fR(1)), or displaying the status of a running server\&. Although the server can be started manually, +pg_ctl +encapsulates tasks such as redirecting log output and properly detaching from the terminal and process group\&. It also provides convenient options for controlled shutdown\&. +.PP +The +\fBinit\fR +or +\fBinitdb\fR +mode creates a new +PostgreSQL +database cluster, that is, a collection of databases that will be managed by a single server instance\&. This mode invokes the +\fBinitdb\fR +command\&. See +\fBinitdb\fR(1) +for details\&. +.PP +\fBstart\fR +mode launches a new server\&. The server is started in the background, and its standard input is attached to +/dev/null +(or +nul +on Windows)\&. On Unix\-like systems, by default, the server\*(Aqs standard output and standard error are sent to +pg_ctl\*(Aqs standard output (not standard error)\&. The standard output of +pg_ctl +should then be redirected to a file or piped to another process such as a log rotating program like +rotatelogs; otherwise +\fBpostgres\fR +will write its output to the controlling terminal (from the background) and will not leave the shell\*(Aqs process group\&. On Windows, by default the server\*(Aqs standard output and standard error are sent to the terminal\&. These default behaviors can be changed by using +\fB\-l\fR +to append the server\*(Aqs output to a log file\&. Use of either +\fB\-l\fR +or output redirection is recommended\&. +.PP +\fBstop\fR +mode shuts down the server that is running in the specified data directory\&. Three different shutdown methods can be selected with the +\fB\-m\fR +option\&. +\(lqSmart\(rq +mode disallows new connections, then waits for all existing clients to disconnect\&. If the server is in hot standby, recovery and streaming replication will be terminated once all clients have disconnected\&. +\(lqFast\(rq +mode (the default) does not wait for clients to disconnect\&. All active transactions are rolled back and clients are forcibly disconnected, then the server is shut down\&. +\(lqImmediate\(rq +mode will abort all server processes immediately, without a clean shutdown\&. This choice will lead to a crash\-recovery cycle during the next server start\&. +.PP +\fBrestart\fR +mode effectively executes a stop followed by a start\&. This allows changing the +\fBpostgres\fR +command\-line options, or changing configuration\-file options that cannot be changed without restarting the server\&. If relative paths were used on the command line during server start, +\fBrestart\fR +might fail unless +pg_ctl +is executed in the same current directory as it was during server start\&. +.PP +\fBreload\fR +mode simply sends the +\fBpostgres\fR +server process a +SIGHUP +signal, causing it to reread its configuration files (postgresql\&.conf, +pg_hba\&.conf, etc\&.)\&. This allows changing configuration\-file options that do not require a full server restart to take effect\&. +.PP +\fBstatus\fR +mode checks whether a server is running in the specified data directory\&. If it is, the server\*(Aqs +PID +and the command line options that were used to invoke it are displayed\&. If the server is not running, +pg_ctl +returns an exit status of 3\&. If an accessible data directory is not specified, +pg_ctl +returns an exit status of 4\&. +.PP +\fBpromote\fR +mode commands the standby server that is running in the specified data directory to end standby mode and begin read\-write operations\&. +.PP +\fBlogrotate\fR +mode rotates the server log file\&. For details on how to use this mode with external log rotation tools, see +Section\ \&25.3\&. +.PP +\fBkill\fR +mode sends a signal to a specified process\&. This is primarily valuable on +Microsoft Windows +which does not have a built\-in +kill +command\&. Use +\-\-help +to see a list of supported signal names\&. +.PP +\fBregister\fR +mode registers the +PostgreSQL +server as a system service on +Microsoft Windows\&. The +\fB\-S\fR +option allows selection of service start type, either +\(lqauto\(rq +(start service automatically on system startup) or +\(lqdemand\(rq +(start service on demand)\&. +.PP +\fBunregister\fR +mode unregisters a system service on +Microsoft Windows\&. This undoes the effects of the +\fBregister\fR +command\&. +.SH "OPTIONS" +.PP +\fB\-c\fR +.br +\fB\-\-core\-files\fR +.RS 4 +Attempt to allow server crashes to produce core files, on platforms where this is possible, by lifting any soft resource limit placed on core files\&. This is useful in debugging or diagnosing problems by allowing a stack trace to be obtained from a failed server process\&. +.RE +.PP +\fB\-D \fR\fB\fIdatadir\fR\fR +.br +\fB\-\-pgdata=\fR\fB\fIdatadir\fR\fR +.RS 4 +Specifies the file system location of the database configuration files\&. If this option is omitted, the environment variable +\fBPGDATA\fR +is used\&. +.RE +.PP +\fB\-l \fR\fB\fIfilename\fR\fR +.br +\fB\-\-log=\fR\fB\fIfilename\fR\fR +.RS 4 +Append the server log output to +\fIfilename\fR\&. If the file does not exist, it is created\&. The +umask +is set to 077, so access to the log file is disallowed to other users by default\&. +.RE +.PP +\fB\-m \fR\fB\fImode\fR\fR +.br +\fB\-\-mode=\fR\fB\fImode\fR\fR +.RS 4 +Specifies the shutdown mode\&. +\fImode\fR +can be +smart, +fast, or +immediate, or the first letter of one of these three\&. If this option is omitted, +fast +is the default\&. +.RE +.PP +\fB\-o \fR\fB\fIoptions\fR\fR +.br +\fB\-\-options=\fR\fB\fIoptions\fR\fR +.RS 4 +Specifies options to be passed directly to the +\fBpostgres\fR +command\&. +\fB\-o\fR +can be specified multiple times, with all the given options being passed through\&. +.sp +The +\fIoptions\fR +should usually be surrounded by single or double quotes to ensure that they are passed through as a group\&. +.RE +.PP +\fB\-o \fR\fB\fIinitdb\-options\fR\fR +.br +\fB\-\-options=\fR\fB\fIinitdb\-options\fR\fR +.RS 4 +Specifies options to be passed directly to the +\fBinitdb\fR +command\&. +\fB\-o\fR +can be specified multiple times, with all the given options being passed through\&. +.sp +The +\fIinitdb\-options\fR +should usually be surrounded by single or double quotes to ensure that they are passed through as a group\&. +.RE +.PP +\fB\-p \fR\fB\fIpath\fR\fR +.RS 4 +Specifies the location of the +postgres +executable\&. By default the +postgres +executable is taken from the same directory as +\fBpg_ctl\fR, or failing that, the hard\-wired installation directory\&. It is not necessary to use this option unless you are doing something unusual and get errors that the +postgres +executable was not found\&. +.sp +In +init +mode, this option analogously specifies the location of the +initdb +executable\&. +.RE +.PP +\fB\-s\fR +.br +\fB\-\-silent\fR +.RS 4 +Print only errors, no informational messages\&. +.RE +.PP +\fB\-t \fR\fB\fIseconds\fR\fR +.br +\fB\-\-timeout=\fR\fB\fIseconds\fR\fR +.RS 4 +Specifies the maximum number of seconds to wait when waiting for an operation to complete (see option +\fB\-w\fR)\&. Defaults to the value of the +\fBPGCTLTIMEOUT\fR +environment variable or, if not set, to 60 seconds\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_ctl +version and exit\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-wait\fR +.RS 4 +Wait for the operation to complete\&. This is supported for the modes +start, +stop, +restart, +promote, and +register, and is the default for those modes\&. +.sp +When waiting, +\fBpg_ctl\fR +repeatedly checks the server\*(Aqs +PID +file, sleeping for a short amount of time between checks\&. Startup is considered complete when the +PID +file indicates that the server is ready to accept connections\&. Shutdown is considered complete when the server removes the +PID +file\&. +\fBpg_ctl\fR +returns an exit code based on the success of the startup or shutdown\&. +.sp +If the operation does not complete within the timeout (see option +\fB\-t\fR), then +\fBpg_ctl\fR +exits with a nonzero exit status\&. But note that the operation might continue in the background and eventually succeed\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-no\-wait\fR +.RS 4 +Do not wait for the operation to complete\&. This is the opposite of the option +\fB\-w\fR\&. +.sp +If waiting is disabled, the requested action is triggered, but there is no feedback about its success\&. In that case, the server log file or an external monitoring system would have to be used to check the progress and success of the operation\&. +.sp +In prior releases of PostgreSQL, this was the default except for the +stop +mode\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_ctl +command line arguments, and exit\&. +.RE +.PP +If an option is specified that is valid, but not relevant to the selected operating mode, +pg_ctl +ignores it\&. +.SS "Options for Windows" +.PP +\fB\-e \fR\fB\fIsource\fR\fR +.RS 4 +Name of the event source for +pg_ctl +to use for logging to the event log when running as a Windows service\&. The default is +PostgreSQL\&. Note that this only controls messages sent from +pg_ctl +itself; once started, the server will use the event source specified by its +event_source +parameter\&. Should the server fail very early in startup, before that parameter has been set, it might also log using the default event source name +PostgreSQL\&. +.RE +.PP +\fB\-N \fR\fB\fIservicename\fR\fR +.RS 4 +Name of the system service to register\&. This name will be used as both the service name and the display name\&. The default is +PostgreSQL\&. +.RE +.PP +\fB\-P \fR\fB\fIpassword\fR\fR +.RS 4 +Password for the user to run the service as\&. +.RE +.PP +\fB\-S \fR\fB\fIstart\-type\fR\fR +.RS 4 +Start type of the system service\&. +\fIstart\-type\fR +can be +auto, or +demand, or the first letter of one of these two\&. If this option is omitted, +auto +is the default\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.RS 4 +User name for the user to run the service as\&. For domain users, use the format +DOMAIN\eusername\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGCTLTIMEOUT\fR +.RS 4 +Default limit on the number of seconds to wait when waiting for startup or shutdown to complete\&. If not set, the default is 60 seconds\&. +.RE +.PP +\fBPGDATA\fR +.RS 4 +Default data directory location\&. +.RE +.PP +Most +\fBpg_ctl\fR +modes require knowing the data directory location; therefore, the +\fB\-D\fR +option is required unless +\fBPGDATA\fR +is set\&. +.PP +\fBpg_ctl\fR, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.PP +For additional variables that affect the server, see +\fBpostgres\fR(1)\&. +.SH "FILES" +.PP +postmaster\&.pid +.RS 4 +pg_ctl +examines this file in the data directory to determine whether the server is currently running\&. +.RE +.PP +postmaster\&.opts +.RS 4 +If this file exists in the data directory, +pg_ctl +(in +\fBrestart\fR +mode) will pass the contents of the file as options to +postgres, unless overridden by the +\fB\-o\fR +option\&. The contents of this file are also displayed in +\fBstatus\fR +mode\&. +.RE +.SH "EXAMPLES" +.SS "Starting the Server" +.PP +To start the server, waiting until the server is accepting connections: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_ctl start\fR +.fi +.if n \{\ +.RE +.\} +.PP +To start the server using port 5433, and running without +\fBfsync\fR, use: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_ctl \-o "\-F \-p 5433" start\fR +.fi +.if n \{\ +.RE +.\} +.SS "Stopping the Server" +.PP +To stop the server, use: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_ctl stop\fR +.fi +.if n \{\ +.RE +.\} +.sp +The +\fB\-m\fR +option allows control over +\fIhow\fR +the server shuts down: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_ctl stop \-m smart\fR +.fi +.if n \{\ +.RE +.\} +.SS "Restarting the Server" +.PP +Restarting the server is almost equivalent to stopping the server and starting it again, except that by default, +\fBpg_ctl\fR +saves and reuses the command line options that were passed to the previously\-running instance\&. To restart the server using the same options as before, use: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_ctl restart\fR +.fi +.if n \{\ +.RE +.\} +.PP +But if +\fB\-o\fR +is specified, that replaces any previous options\&. To restart using port 5433, disabling +\fBfsync\fR +upon restart: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_ctl \-o "\-F \-p 5433" restart\fR +.fi +.if n \{\ +.RE +.\} +.SS "Showing the Server Status" +.PP +Here is sample status output from +pg_ctl: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_ctl status\fR + +pg_ctl: server is running (PID: 13718) +/usr/local/pgsql/bin/postgres "\-D" "/usr/local/pgsql/data" "\-p" "5433" "\-B" "128" +.fi +.if n \{\ +.RE +.\} +.sp +The second line is the command that would be invoked in restart mode\&. +.SH "SEE ALSO" +\fBinitdb\fR(1), \fBpostgres\fR(1) diff --git a/doc/src/sgml/man1/pg_dump.1 b/doc/src/sgml/man1/pg_dump.1 new file mode 100644 index 0000000..6603d11 --- /dev/null +++ b/doc/src/sgml/man1/pg_dump.1 @@ -0,0 +1,1239 @@ +'\" t +.\" Title: pg_dump +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_DUMP" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_dump \- extract a PostgreSQL database into a script file or other archive file +.SH "SYNOPSIS" +.HP \w'\fBpg_dump\fR\ 'u +\fBpg_dump\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\fIdbname\fR] +.SH "DESCRIPTION" +.PP +pg_dump +is a utility for backing up a +PostgreSQL +database\&. It makes consistent backups even if the database is being used concurrently\&. +pg_dump +does not block other users accessing the database (readers or writers)\&. +.PP +pg_dump +only dumps a single database\&. To back up an entire cluster, or to back up global objects that are common to all databases in a cluster (such as roles and tablespaces), use +\fBpg_dumpall\fR(1)\&. +.PP +Dumps can be output in script or archive file formats\&. Script dumps are plain\-text files containing the SQL commands required to reconstruct the database to the state it was in at the time it was saved\&. To restore from such a script, feed it to +\fBpsql\fR(1)\&. Script files can be used to reconstruct the database even on other machines and other architectures; with some modifications, even on other SQL database products\&. +.PP +The alternative archive file formats must be used with +\fBpg_restore\fR(1) +to rebuild the database\&. They allow +pg_restore +to be selective about what is restored, or even to reorder the items prior to being restored\&. The archive file formats are designed to be portable across architectures\&. +.PP +When used with one of the archive file formats and combined with +pg_restore, +pg_dump +provides a flexible archival and transfer mechanism\&. +pg_dump +can be used to backup an entire database, then +pg_restore +can be used to examine the archive and/or select which parts of the database are to be restored\&. The most flexible output file formats are the +\(lqcustom\(rq +format (\fB\-Fc\fR) and the +\(lqdirectory\(rq +format (\fB\-Fd\fR)\&. They allow for selection and reordering of all archived items, support parallel restoration, and are compressed by default\&. The +\(lqdirectory\(rq +format is the only format that supports parallel dumps\&. +.PP +While running +pg_dump, one should examine the output for any warnings (printed on standard error), especially in light of the limitations listed below\&. +.SH "OPTIONS" +.PP +The following command\-line options control the content and format of the output\&. +.PP +\fIdbname\fR +.RS 4 +Specifies the name of the database to be dumped\&. If this is not specified, the environment variable +\fBPGDATABASE\fR +is used\&. If that is not set, the user name specified for the connection is used\&. +.RE +.PP +\fB\-a\fR +.br +\fB\-\-data\-only\fR +.RS 4 +Dump only the data, not the schema (data definitions)\&. Table data, large objects, and sequence values are dumped\&. +.sp +This option is similar to, but for historical reasons not identical to, specifying +\fB\-\-section=data\fR\&. +.RE +.PP +\fB\-b\fR +.br +\fB\-\-blobs\fR +.RS 4 +Include large objects in the dump\&. This is the default behavior except when +\fB\-\-schema\fR, +\fB\-\-table\fR, or +\fB\-\-schema\-only\fR +is specified\&. The +\fB\-b\fR +switch is therefore only useful to add large objects to dumps where a specific schema or table has been requested\&. Note that blobs are considered data and therefore will be included when +\fB\-\-data\-only\fR +is used, but not when +\fB\-\-schema\-only\fR +is\&. +.RE +.PP +\fB\-B\fR +.br +\fB\-\-no\-blobs\fR +.RS 4 +Exclude large objects in the dump\&. +.sp +When both +\fB\-b\fR +and +\fB\-B\fR +are given, the behavior is to output large objects, when data is being dumped, see the +\fB\-b\fR +documentation\&. +.RE +.PP +\fB\-c\fR +.br +\fB\-\-clean\fR +.RS 4 +Output commands to clean (drop) database objects prior to outputting the commands for creating them\&. (Unless +\fB\-\-if\-exists\fR +is also specified, restore might generate some harmless error messages, if any objects were not present in the destination database\&.) +.sp +This option is ignored when emitting an archive (non\-text) output file\&. For the archive formats, you can specify the option when you call +\fBpg_restore\fR\&. +.RE +.PP +\fB\-C\fR +.br +\fB\-\-create\fR +.RS 4 +Begin the output with a command to create the database itself and reconnect to the created database\&. (With a script of this form, it doesn\*(Aqt matter which database in the destination installation you connect to before running the script\&.) If +\fB\-\-clean\fR +is also specified, the script drops and recreates the target database before reconnecting to it\&. +.sp +With +\fB\-\-create\fR, the output also includes the database\*(Aqs comment if any, and any configuration variable settings that are specific to this database, that is, any +\fBALTER DATABASE \&.\&.\&. SET \&.\&.\&.\fR +and +\fBALTER ROLE \&.\&.\&. IN DATABASE \&.\&.\&. SET \&.\&.\&.\fR +commands that mention this database\&. Access privileges for the database itself are also dumped, unless +\fB\-\-no\-acl\fR +is specified\&. +.sp +This option is ignored when emitting an archive (non\-text) output file\&. For the archive formats, you can specify the option when you call +\fBpg_restore\fR\&. +.RE +.PP +\fB\-e \fR\fB\fIpattern\fR\fR +.br +\fB\-\-extension=\fR\fB\fIpattern\fR\fR +.RS 4 +Dump only extensions matching +\fIpattern\fR\&. When this option is not specified, all non\-system extensions in the target database will be dumped\&. Multiple extensions can be selected by writing multiple +\fB\-e\fR +switches\&. The +\fIpattern\fR +parameter is interpreted as a pattern according to the same rules used by +psql\*(Aqs +\ed +commands (see +Patterns), so multiple extensions can also be selected by writing wildcard characters in the pattern\&. When using wildcards, be careful to quote the pattern if needed to prevent the shell from expanding the wildcards\&. +.sp +Any configuration relation registered by +\fBpg_extension_config_dump\fR +is included in the dump if its extension is specified by +\fB\-\-extension\fR\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +When +\fB\-e\fR +is specified, +pg_dump +makes no attempt to dump any other database objects that the selected extension(s) might depend upon\&. Therefore, there is no guarantee that the results of a specific\-extension dump can be successfully restored by themselves into a clean database\&. +.sp .5v +.RE +.RE +.PP +\fB\-E \fR\fB\fIencoding\fR\fR +.br +\fB\-\-encoding=\fR\fB\fIencoding\fR\fR +.RS 4 +Create the dump in the specified character set encoding\&. By default, the dump is created in the database encoding\&. (Another way to get the same result is to set the +\fBPGCLIENTENCODING\fR +environment variable to the desired dump encoding\&.) The supported encodings are described in +Section\ \&24.3.1\&. +.RE +.PP +\fB\-f \fR\fB\fIfile\fR\fR +.br +\fB\-\-file=\fR\fB\fIfile\fR\fR +.RS 4 +Send output to the specified file\&. This parameter can be omitted for file based output formats, in which case the standard output is used\&. It must be given for the directory output format however, where it specifies the target directory instead of a file\&. In this case the directory is created by +\fBpg_dump\fR +and must not exist before\&. +.RE +.PP +\fB\-F \fR\fB\fIformat\fR\fR +.br +\fB\-\-format=\fR\fB\fIformat\fR\fR +.RS 4 +Selects the format of the output\&. +\fIformat\fR +can be one of the following: +.PP +p +.br +plain +.RS 4 +Output a plain\-text +SQL +script file (the default)\&. +.RE +.PP +c +.br +custom +.RS 4 +Output a custom\-format archive suitable for input into +pg_restore\&. Together with the directory output format, this is the most flexible output format in that it allows manual selection and reordering of archived items during restore\&. This format is also compressed by default\&. +.RE +.PP +d +.br +directory +.RS 4 +Output a directory\-format archive suitable for input into +pg_restore\&. This will create a directory with one file for each table and blob being dumped, plus a so\-called Table of Contents file describing the dumped objects in a machine\-readable format that +pg_restore +can read\&. A directory format archive can be manipulated with standard Unix tools; for example, files in an uncompressed archive can be compressed with the +gzip +tool\&. This format is compressed by default and also supports parallel dumps\&. +.RE +.PP +t +.br +tar +.RS 4 +Output a +\fBtar\fR\-format archive suitable for input into +pg_restore\&. The tar format is compatible with the directory format: extracting a tar\-format archive produces a valid directory\-format archive\&. However, the tar format does not support compression\&. Also, when using tar format the relative order of table data items cannot be changed during restore\&. +.RE +.RE +.PP +\fB\-j \fR\fB\fInjobs\fR\fR +.br +\fB\-\-jobs=\fR\fB\fInjobs\fR\fR +.RS 4 +Run the dump in parallel by dumping +\fInjobs\fR +tables simultaneously\&. This option may reduce the time needed to perform the dump but it also increases the load on the database server\&. You can only use this option with the directory output format because this is the only output format where multiple processes can write their data at the same time\&. +.sp +pg_dump +will open +\fInjobs\fR ++ 1 connections to the database, so make sure your +max_connections +setting is high enough to accommodate all connections\&. +.sp +Requesting exclusive locks on database objects while running a parallel dump could cause the dump to fail\&. The reason is that the +pg_dump +leader process requests shared locks (ACCESS SHARE) on the objects that the worker processes are going to dump later in order to make sure that nobody deletes them and makes them go away while the dump is running\&. If another client then requests an exclusive lock on a table, that lock will not be granted but will be queued waiting for the shared lock of the leader process to be released\&. Consequently any other access to the table will not be granted either and will queue after the exclusive lock request\&. This includes the worker process trying to dump the table\&. Without any precautions this would be a classic deadlock situation\&. To detect this conflict, the +pg_dump +worker process requests another shared lock using the +NOWAIT +option\&. If the worker process is not granted this shared lock, somebody else must have requested an exclusive lock in the meantime and there is no way to continue with the dump, so +pg_dump +has no choice but to abort the dump\&. +.sp +To perform a parallel dump, the database server needs to support synchronized snapshots, a feature that was introduced in +PostgreSQL +9\&.2 for primary servers and 10 for standbys\&. With this feature, database clients can ensure they see the same data set even though they use different connections\&. +\fBpg_dump \-j\fR +uses multiple database connections; it connects to the database once with the leader process and once again for each worker job\&. Without the synchronized snapshot feature, the different worker jobs wouldn\*(Aqt be guaranteed to see the same data in each connection, which could lead to an inconsistent backup\&. +.RE +.PP +\fB\-n \fR\fB\fIpattern\fR\fR +.br +\fB\-\-schema=\fR\fB\fIpattern\fR\fR +.RS 4 +Dump only schemas matching +\fIpattern\fR; this selects both the schema itself, and all its contained objects\&. When this option is not specified, all non\-system schemas in the target database will be dumped\&. Multiple schemas can be selected by writing multiple +\fB\-n\fR +switches\&. The +\fIpattern\fR +parameter is interpreted as a pattern according to the same rules used by +psql\*(Aqs +\ed +commands (see +Patterns +below), so multiple schemas can also be selected by writing wildcard characters in the pattern\&. When using wildcards, be careful to quote the pattern if needed to prevent the shell from expanding the wildcards; see +Examples +below\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +When +\fB\-n\fR +is specified, +pg_dump +makes no attempt to dump any other database objects that the selected schema(s) might depend upon\&. Therefore, there is no guarantee that the results of a specific\-schema dump can be successfully restored by themselves into a clean database\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +Non\-schema objects such as blobs are not dumped when +\fB\-n\fR +is specified\&. You can add blobs back to the dump with the +\fB\-\-blobs\fR +switch\&. +.sp .5v +.RE +.RE +.PP +\fB\-N \fR\fB\fIpattern\fR\fR +.br +\fB\-\-exclude\-schema=\fR\fB\fIpattern\fR\fR +.RS 4 +Do not dump any schemas matching +\fIpattern\fR\&. The pattern is interpreted according to the same rules as for +\fB\-n\fR\&. +\fB\-N\fR +can be given more than once to exclude schemas matching any of several patterns\&. +.sp +When both +\fB\-n\fR +and +\fB\-N\fR +are given, the behavior is to dump just the schemas that match at least one +\fB\-n\fR +switch but no +\fB\-N\fR +switches\&. If +\fB\-N\fR +appears without +\fB\-n\fR, then schemas matching +\fB\-N\fR +are excluded from what is otherwise a normal dump\&. +.RE +.PP +\fB\-O\fR +.br +\fB\-\-no\-owner\fR +.RS 4 +Do not output commands to set ownership of objects to match the original database\&. By default, +pg_dump +issues +\fBALTER OWNER\fR +or +\fBSET SESSION AUTHORIZATION\fR +statements to set ownership of created database objects\&. These statements will fail when the script is run unless it is started by a superuser (or the same user that owns all of the objects in the script)\&. To make a script that can be restored by any user, but will give that user ownership of all the objects, specify +\fB\-O\fR\&. +.sp +This option is ignored when emitting an archive (non\-text) output file\&. For the archive formats, you can specify the option when you call +\fBpg_restore\fR\&. +.RE +.PP +\fB\-R\fR +.br +\fB\-\-no\-reconnect\fR +.RS 4 +This option is obsolete but still accepted for backwards compatibility\&. +.RE +.PP +\fB\-s\fR +.br +\fB\-\-schema\-only\fR +.RS 4 +Dump only the object definitions (schema), not data\&. +.sp +This option is the inverse of +\fB\-\-data\-only\fR\&. It is similar to, but for historical reasons not identical to, specifying +\fB\-\-section=pre\-data \-\-section=post\-data\fR\&. +.sp +(Do not confuse this with the +\fB\-\-schema\fR +option, which uses the word +\(lqschema\(rq +in a different meaning\&.) +.sp +To exclude table data for only a subset of tables in the database, see +\fB\-\-exclude\-table\-data\fR\&. +.RE +.PP +\fB\-S \fR\fB\fIusername\fR\fR +.br +\fB\-\-superuser=\fR\fB\fIusername\fR\fR +.RS 4 +Specify the superuser user name to use when disabling triggers\&. This is relevant only if +\fB\-\-disable\-triggers\fR +is used\&. (Usually, it\*(Aqs better to leave this out, and instead start the resulting script as superuser\&.) +.RE +.PP +\fB\-t \fR\fB\fIpattern\fR\fR +.br +\fB\-\-table=\fR\fB\fIpattern\fR\fR +.RS 4 +Dump only tables with names matching +\fIpattern\fR\&. Multiple tables can be selected by writing multiple +\fB\-t\fR +switches\&. The +\fIpattern\fR +parameter is interpreted as a pattern according to the same rules used by +psql\*(Aqs +\ed +commands (see +Patterns +below), so multiple tables can also be selected by writing wildcard characters in the pattern\&. When using wildcards, be careful to quote the pattern if needed to prevent the shell from expanding the wildcards; see +Examples +below\&. +.sp +As well as tables, this option can be used to dump the definition of matching views, materialized views, foreign tables, and sequences\&. It will not dump the contents of views or materialized views, and the contents of foreign tables will only be dumped if the corresponding foreign server is specified with +\fB\-\-include\-foreign\-data\fR\&. +.sp +The +\fB\-n\fR +and +\fB\-N\fR +switches have no effect when +\fB\-t\fR +is used, because tables selected by +\fB\-t\fR +will be dumped regardless of those switches, and non\-table objects will not be dumped\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +When +\fB\-t\fR +is specified, +pg_dump +makes no attempt to dump any other database objects that the selected table(s) might depend upon\&. Therefore, there is no guarantee that the results of a specific\-table dump can be successfully restored by themselves into a clean database\&. +.sp .5v +.RE +.RE +.PP +\fB\-T \fR\fB\fIpattern\fR\fR +.br +\fB\-\-exclude\-table=\fR\fB\fIpattern\fR\fR +.RS 4 +Do not dump any tables matching +\fIpattern\fR\&. The pattern is interpreted according to the same rules as for +\fB\-t\fR\&. +\fB\-T\fR +can be given more than once to exclude tables matching any of several patterns\&. +.sp +When both +\fB\-t\fR +and +\fB\-T\fR +are given, the behavior is to dump just the tables that match at least one +\fB\-t\fR +switch but no +\fB\-T\fR +switches\&. If +\fB\-T\fR +appears without +\fB\-t\fR, then tables matching +\fB\-T\fR +are excluded from what is otherwise a normal dump\&. +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Specifies verbose mode\&. This will cause +pg_dump +to output detailed object comments and start/stop times to the dump file, and progress messages to standard error\&. Repeating the option causes additional debug\-level messages to appear on standard error\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_dump +version and exit\&. +.RE +.PP +\fB\-x\fR +.br +\fB\-\-no\-privileges\fR +.br +\fB\-\-no\-acl\fR +.RS 4 +Prevent dumping of access privileges (grant/revoke commands)\&. +.RE +.PP +\fB\-Z \fR\fB\fI0\&.\&.9\fR\fR +.br +\fB\-\-compress=\fR\fB\fI0\&.\&.9\fR\fR +.RS 4 +Specify the compression level to use\&. Zero means no compression\&. For the custom and directory archive formats, this specifies compression of individual table\-data segments, and the default is to compress at a moderate level\&. For plain text output, setting a nonzero compression level causes the entire output file to be compressed, as though it had been fed through +gzip; but the default is not to compress\&. The tar archive format currently does not support compression at all\&. +.RE +.PP +\fB\-\-binary\-upgrade\fR +.RS 4 +This option is for use by in\-place upgrade utilities\&. Its use for other purposes is not recommended or supported\&. The behavior of the option may change in future releases without notice\&. +.RE +.PP +\fB\-\-column\-inserts\fR +.br +\fB\-\-attribute\-inserts\fR +.RS 4 +Dump data as +\fBINSERT\fR +commands with explicit column names (INSERT INTO \fItable\fR (\fIcolumn\fR, \&.\&.\&.) VALUES \&.\&.\&.)\&. This will make restoration very slow; it is mainly useful for making dumps that can be loaded into non\-PostgreSQL +databases\&. Any error during restoring will cause only rows that are part of the problematic +\fBINSERT\fR +to be lost, rather than the entire table contents\&. +.RE +.PP +\fB\-\-disable\-dollar\-quoting\fR +.RS 4 +This option disables the use of dollar quoting for function bodies, and forces them to be quoted using SQL standard string syntax\&. +.RE +.PP +\fB\-\-disable\-triggers\fR +.RS 4 +This option is relevant only when creating a data\-only dump\&. It instructs +pg_dump +to include commands to temporarily disable triggers on the target tables while the data is restored\&. Use this if you have referential integrity checks or other triggers on the tables that you do not want to invoke during data restore\&. +.sp +Presently, the commands emitted for +\fB\-\-disable\-triggers\fR +must be done as superuser\&. So, you should also specify a superuser name with +\fB\-S\fR, or preferably be careful to start the resulting script as a superuser\&. +.sp +This option is ignored when emitting an archive (non\-text) output file\&. For the archive formats, you can specify the option when you call +\fBpg_restore\fR\&. +.RE +.PP +\fB\-\-enable\-row\-security\fR +.RS 4 +This option is relevant only when dumping the contents of a table which has row security\&. By default, +pg_dump +will set +row_security +to off, to ensure that all data is dumped from the table\&. If the user does not have sufficient privileges to bypass row security, then an error is thrown\&. This parameter instructs +pg_dump +to set +row_security +to on instead, allowing the user to dump the parts of the contents of the table that they have access to\&. +.sp +Note that if you use this option currently, you probably also want the dump be in +\fBINSERT\fR +format, as the +\fBCOPY FROM\fR +during restore does not support row security\&. +.RE +.PP +\fB\-\-exclude\-table\-data=\fR\fB\fIpattern\fR\fR +.RS 4 +Do not dump data for any tables matching +\fIpattern\fR\&. The pattern is interpreted according to the same rules as for +\fB\-t\fR\&. +\fB\-\-exclude\-table\-data\fR +can be given more than once to exclude tables matching any of several patterns\&. This option is useful when you need the definition of a particular table even though you do not need the data in it\&. +.sp +To exclude data for all tables in the database, see +\fB\-\-schema\-only\fR\&. +.RE +.PP +\fB\-\-extra\-float\-digits=\fR\fB\fIndigits\fR\fR +.RS 4 +Use the specified value of +\fBextra_float_digits\fR +when dumping floating\-point data, instead of the maximum available precision\&. Routine dumps made for backup purposes should not use this option\&. +.RE +.PP +\fB\-\-if\-exists\fR +.RS 4 +Use conditional commands (i\&.e\&., add an +IF EXISTS +clause) when cleaning database objects\&. This option is not valid unless +\fB\-\-clean\fR +is also specified\&. +.RE +.PP +\fB\-\-include\-foreign\-data=\fR\fB\fIforeignserver\fR\fR +.RS 4 +Dump the data for any foreign table with a foreign server matching +\fIforeignserver\fR +pattern\&. Multiple foreign servers can be selected by writing multiple +\fB\-\-include\-foreign\-data\fR +switches\&. Also, the +\fIforeignserver\fR +parameter is interpreted as a pattern according to the same rules used by +psql\*(Aqs +\ed +commands (see +Patterns +below), so multiple foreign servers can also be selected by writing wildcard characters in the pattern\&. When using wildcards, be careful to quote the pattern if needed to prevent the shell from expanding the wildcards; see +Examples +below\&. The only exception is that an empty pattern is disallowed\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +When +\fB\-\-include\-foreign\-data\fR +is specified, +pg_dump +does not check that the foreign table is writable\&. Therefore, there is no guarantee that the results of a foreign table dump can be successfully restored\&. +.sp .5v +.RE +.RE +.PP +\fB\-\-inserts\fR +.RS 4 +Dump data as +\fBINSERT\fR +commands (rather than +\fBCOPY\fR)\&. This will make restoration very slow; it is mainly useful for making dumps that can be loaded into non\-PostgreSQL +databases\&. Any error during restoring will cause only rows that are part of the problematic +\fBINSERT\fR +to be lost, rather than the entire table contents\&. Note that the restore might fail altogether if you have rearranged column order\&. The +\fB\-\-column\-inserts\fR +option is safe against column order changes, though even slower\&. +.RE +.PP +\fB\-\-load\-via\-partition\-root\fR +.RS 4 +When dumping data for a table partition, make the +\fBCOPY\fR +or +\fBINSERT\fR +statements target the root of the partitioning hierarchy that contains it, rather than the partition itself\&. This causes the appropriate partition to be re\-determined for each row when the data is loaded\&. This may be useful when restoring data on a server where rows do not always fall into the same partitions as they did on the original server\&. That could happen, for example, if the partitioning column is of type text and the two systems have different definitions of the collation used to sort the partitioning column\&. +.RE +.PP +\fB\-\-lock\-wait\-timeout=\fR\fB\fItimeout\fR\fR +.RS 4 +Do not wait forever to acquire shared table locks at the beginning of the dump\&. Instead fail if unable to lock a table within the specified +\fItimeout\fR\&. The timeout may be specified in any of the formats accepted by +\fBSET statement_timeout\fR\&. (Allowed formats vary depending on the server version you are dumping from, but an integer number of milliseconds is accepted by all versions\&.) +.RE +.PP +\fB\-\-no\-comments\fR +.RS 4 +Do not dump comments\&. +.RE +.PP +\fB\-\-no\-publications\fR +.RS 4 +Do not dump publications\&. +.RE +.PP +\fB\-\-no\-security\-labels\fR +.RS 4 +Do not dump security labels\&. +.RE +.PP +\fB\-\-no\-subscriptions\fR +.RS 4 +Do not dump subscriptions\&. +.RE +.PP +\fB\-\-no\-sync\fR +.RS 4 +By default, +\fBpg_dump\fR +will wait for all files to be written safely to disk\&. This option causes +\fBpg_dump\fR +to return without waiting, which is faster, but means that a subsequent operating system crash can leave the dump corrupt\&. Generally, this option is useful for testing but should not be used when dumping data from production installation\&. +.RE +.PP +\fB\-\-no\-table\-access\-method\fR +.RS 4 +Do not output commands to select table access methods\&. With this option, all objects will be created with whichever table access method is the default during restore\&. +.sp +This option is ignored when emitting an archive (non\-text) output file\&. For the archive formats, you can specify the option when you call +\fBpg_restore\fR\&. +.RE +.PP +\fB\-\-no\-tablespaces\fR +.RS 4 +Do not output commands to select tablespaces\&. With this option, all objects will be created in whichever tablespace is the default during restore\&. +.sp +This option is ignored when emitting an archive (non\-text) output file\&. For the archive formats, you can specify the option when you call +\fBpg_restore\fR\&. +.RE +.PP +\fB\-\-no\-toast\-compression\fR +.RS 4 +Do not output commands to set +TOAST +compression methods\&. With this option, all columns will be restored with the default compression setting\&. +.RE +.PP +\fB\-\-no\-unlogged\-table\-data\fR +.RS 4 +Do not dump the contents of unlogged tables and sequences\&. This option has no effect on whether or not the table and sequence definitions (schema) are dumped; it only suppresses dumping the table and sequence data\&. Data in unlogged tables and sequences is always excluded when dumping from a standby server\&. +.RE +.PP +\fB\-\-on\-conflict\-do\-nothing\fR +.RS 4 +Add +ON CONFLICT DO NOTHING +to +\fBINSERT\fR +commands\&. This option is not valid unless +\fB\-\-inserts\fR, +\fB\-\-column\-inserts\fR +or +\fB\-\-rows\-per\-insert\fR +is also specified\&. +.RE +.PP +\fB\-\-quote\-all\-identifiers\fR +.RS 4 +Force quoting of all identifiers\&. This option is recommended when dumping a database from a server whose +PostgreSQL +major version is different from +pg_dump\*(Aqs, or when the output is intended to be loaded into a server of a different major version\&. By default, +pg_dump +quotes only identifiers that are reserved words in its own major version\&. This sometimes results in compatibility issues when dealing with servers of other versions that may have slightly different sets of reserved words\&. Using +\fB\-\-quote\-all\-identifiers\fR +prevents such issues, at the price of a harder\-to\-read dump script\&. +.RE +.PP +\fB\-\-rows\-per\-insert=\fR\fB\fInrows\fR\fR +.RS 4 +Dump data as +\fBINSERT\fR +commands (rather than +\fBCOPY\fR)\&. Controls the maximum number of rows per +\fBINSERT\fR +command\&. The value specified must be a number greater than zero\&. Any error during restoring will cause only rows that are part of the problematic +\fBINSERT\fR +to be lost, rather than the entire table contents\&. +.RE +.PP +\fB\-\-section=\fR\fB\fIsectionname\fR\fR +.RS 4 +Only dump the named section\&. The section name can be +\fBpre\-data\fR, +\fBdata\fR, or +\fBpost\-data\fR\&. This option can be specified more than once to select multiple sections\&. The default is to dump all sections\&. +.sp +The data section contains actual table data, large\-object contents, and sequence values\&. Post\-data items include definitions of indexes, triggers, rules, and constraints other than validated check constraints\&. Pre\-data items include all other data definition items\&. +.RE +.PP +\fB\-\-serializable\-deferrable\fR +.RS 4 +Use a +serializable +transaction for the dump, to ensure that the snapshot used is consistent with later database states; but do this by waiting for a point in the transaction stream at which no anomalies can be present, so that there isn\*(Aqt a risk of the dump failing or causing other transactions to roll back with a +serialization_failure\&. See +Chapter\ \&13 +for more information about transaction isolation and concurrency control\&. +.sp +This option is not beneficial for a dump which is intended only for disaster recovery\&. It could be useful for a dump used to load a copy of the database for reporting or other read\-only load sharing while the original database continues to be updated\&. Without it the dump may reflect a state which is not consistent with any serial execution of the transactions eventually committed\&. For example, if batch processing techniques are used, a batch may show as closed in the dump without all of the items which are in the batch appearing\&. +.sp +This option will make no difference if there are no read\-write transactions active when pg_dump is started\&. If read\-write transactions are active, the start of the dump may be delayed for an indeterminate length of time\&. Once running, performance with or without the switch is the same\&. +.RE +.PP +\fB\-\-snapshot=\fR\fB\fIsnapshotname\fR\fR +.RS 4 +Use the specified synchronized snapshot when making a dump of the database (see +Table\ \&9.92 +for more details)\&. +.sp +This option is useful when needing to synchronize the dump with a logical replication slot (see +Chapter\ \&49) or with a concurrent session\&. +.sp +In the case of a parallel dump, the snapshot name defined by this option is used rather than taking a new snapshot\&. +.RE +.PP +\fB\-\-strict\-names\fR +.RS 4 +Require that each extension (\fB\-e\fR/\fB\-\-extension\fR), schema (\fB\-n\fR/\fB\-\-schema\fR) and table (\fB\-t\fR/\fB\-\-table\fR) qualifier match at least one extension/schema/table in the database to be dumped\&. Note that if none of the extension/schema/table qualifiers find matches, +pg_dump +will generate an error even without +\fB\-\-strict\-names\fR\&. +.sp +This option has no effect on +\fB\-N\fR/\fB\-\-exclude\-schema\fR, +\fB\-T\fR/\fB\-\-exclude\-table\fR, or +\fB\-\-exclude\-table\-data\fR\&. An exclude pattern failing to match any objects is not considered an error\&. +.RE +.PP +\fB\-\-use\-set\-session\-authorization\fR +.RS 4 +Output SQL\-standard +\fBSET SESSION AUTHORIZATION\fR +commands instead of +\fBALTER OWNER\fR +commands to determine object ownership\&. This makes the dump more standards\-compatible, but depending on the history of the objects in the dump, might not restore properly\&. Also, a dump using +\fBSET SESSION AUTHORIZATION\fR +will certainly require superuser privileges to restore correctly, whereas +\fBALTER OWNER\fR +requires lesser privileges\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_dump +command line arguments, and exit\&. +.RE +.PP +The following command\-line options control the database connection parameters\&. +.PP +\fB\-d \fR\fB\fIdbname\fR\fR +.br +\fB\-\-dbname=\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to connect to\&. This is equivalent to specifying +\fIdbname\fR +as the first non\-option argument on the command line\&. The +\fIdbname\fR +can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. +.RE +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. The default is taken from the +\fBPGHOST\fR +environment variable, if set, else a Unix domain socket connection is attempted\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. Defaults to the +\fBPGPORT\fR +environment variable, if set, or a compiled\-in default\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +pg_dump +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +pg_dump +will automatically prompt for a password if the server demands password authentication\&. However, +pg_dump +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +\fB\-\-role=\fR\fB\fIrolename\fR\fR +.RS 4 +Specifies a role name to be used to create the dump\&. This option causes +pg_dump +to issue a +\fBSET ROLE\fR +\fIrolename\fR +command after connecting to the database\&. It is useful when the authenticated user (specified by +\fB\-U\fR) lacks privileges needed by +pg_dump, but can switch to a role with the required rights\&. Some installations have a policy against logging in directly as a superuser, and use of this option allows dumps to be made without violating the policy\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGDATABASE\fR +.br +\fBPGHOST\fR +.br +\fBPGOPTIONS\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters\&. +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "DIAGNOSTICS" +.PP +pg_dump +internally executes +\fBSELECT\fR +statements\&. If you have problems running +pg_dump, make sure you are able to select information from the database using, for example, +\fBpsql\fR(1)\&. Also, any default connection settings and environment variables used by the +libpq +front\-end library will apply\&. +.PP +The database activity of +pg_dump +is normally collected by the cumulative statistics system\&. If this is undesirable, you can set parameter +\fItrack_counts\fR +to false via +\fBPGOPTIONS\fR +or the +ALTER USER +command\&. +.SH "NOTES" +.PP +If your database cluster has any local additions to the +template1 +database, be careful to restore the output of +pg_dump +into a truly empty database; otherwise you are likely to get errors due to duplicate definitions of the added objects\&. To make an empty database without any local additions, copy from +template0 +not +template1, for example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE DATABASE foo WITH TEMPLATE template0; +.fi +.if n \{\ +.RE +.\} +.PP +When a data\-only dump is chosen and the option +\fB\-\-disable\-triggers\fR +is used, +pg_dump +emits commands to disable triggers on user tables before inserting the data, and then commands to re\-enable them after the data has been inserted\&. If the restore is stopped in the middle, the system catalogs might be left in the wrong state\&. +.PP +The dump file produced by +pg_dump +does not contain the statistics used by the optimizer to make query planning decisions\&. Therefore, it is wise to run +\fBANALYZE\fR +after restoring from a dump file to ensure optimal performance; see +Section\ \&25.1.3 +and +Section\ \&25.1.6 +for more information\&. +.PP +Because +pg_dump +is used to transfer data to newer versions of +PostgreSQL, the output of +pg_dump +can be expected to load into +PostgreSQL +server versions newer than +pg_dump\*(Aqs version\&. +pg_dump +can also dump from +PostgreSQL +servers older than its own version\&. (Currently, servers back to version 9\&.2 are supported\&.) However, +pg_dump +cannot dump from +PostgreSQL +servers newer than its own major version; it will refuse to even try, rather than risk making an invalid dump\&. Also, it is not guaranteed that +pg_dump\*(Aqs output can be loaded into a server of an older major version \(em not even if the dump was taken from a server of that version\&. Loading a dump file into an older server may require manual editing of the dump file to remove syntax not understood by the older server\&. Use of the +\fB\-\-quote\-all\-identifiers\fR +option is recommended in cross\-version cases, as it can prevent problems arising from varying reserved\-word lists in different +PostgreSQL +versions\&. +.PP +When dumping logical replication subscriptions, +pg_dump +will generate +\fBCREATE SUBSCRIPTION\fR +commands that use the +connect = false +option, so that restoring the subscription does not make remote connections for creating a replication slot or for initial table copy\&. That way, the dump can be restored without requiring network access to the remote servers\&. It is then up to the user to reactivate the subscriptions in a suitable way\&. If the involved hosts have changed, the connection information might have to be changed\&. It might also be appropriate to truncate the target tables before initiating a new full table copy\&. If users intend to copy initial data during refresh they must create the slot with +two_phase = false\&. After the initial sync, the +two_phase +option will be automatically enabled by the subscriber if the subscription had been originally created with +two_phase = true +option\&. +.SH "EXAMPLES" +.PP +To dump a database called +mydb +into an SQL\-script file: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dump mydb > db\&.sql\fR +.fi +.if n \{\ +.RE +.\} +.PP +To reload such a script into a (freshly created) database named +newdb: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpsql \-d newdb \-f db\&.sql\fR +.fi +.if n \{\ +.RE +.\} +.PP +To dump a database into a custom\-format archive file: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dump \-Fc mydb > db\&.dump\fR +.fi +.if n \{\ +.RE +.\} +.PP +To dump a database into a directory\-format archive: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dump \-Fd mydb \-f dumpdir\fR +.fi +.if n \{\ +.RE +.\} +.PP +To dump a database into a directory\-format archive in parallel with 5 worker jobs: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dump \-Fd mydb \-j 5 \-f dumpdir\fR +.fi +.if n \{\ +.RE +.\} +.PP +To reload an archive file into a (freshly created) database named +newdb: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_restore \-d newdb db\&.dump\fR +.fi +.if n \{\ +.RE +.\} +.PP +To reload an archive file into the same database it was dumped from, discarding the current contents of that database: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_restore \-d postgres \-\-clean \-\-create db\&.dump\fR +.fi +.if n \{\ +.RE +.\} +.PP +To dump a single table named +mytab: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dump \-t mytab mydb > db\&.sql\fR +.fi +.if n \{\ +.RE +.\} +.PP +To dump all tables whose names start with +emp +in the +detroit +schema, except for the table named +employee_log: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dump \-t \*(Aqdetroit\&.emp*\*(Aq \-T detroit\&.employee_log mydb > db\&.sql\fR +.fi +.if n \{\ +.RE +.\} +.PP +To dump all schemas whose names start with +east +or +west +and end in +gsm, excluding any schemas whose names contain the word +test: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dump \-n \*(Aqeast*gsm\*(Aq \-n \*(Aqwest*gsm\*(Aq \-N \*(Aq*test*\*(Aq mydb > db\&.sql\fR +.fi +.if n \{\ +.RE +.\} +.PP +The same, using regular expression notation to consolidate the switches: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dump \-n \*(Aq(east|west)*gsm\*(Aq \-N \*(Aq*test*\*(Aq mydb > db\&.sql\fR +.fi +.if n \{\ +.RE +.\} +.PP +To dump all database objects except for tables whose names begin with +ts_: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dump \-T \*(Aqts_*\*(Aq mydb > db\&.sql\fR +.fi +.if n \{\ +.RE +.\} +.PP +To specify an upper\-case or mixed\-case name in +\fB\-t\fR +and related switches, you need to double\-quote the name; else it will be folded to lower case (see +Patterns +below)\&. But double quotes are special to the shell, so in turn they must be quoted\&. Thus, to dump a single table with a mixed\-case name, you need something like +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dump \-t "\e"MixedCaseName\e"" mydb > mytab\&.sql\fR +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBpg_dumpall\fR(1), \fBpg_restore\fR(1), \fBpsql\fR(1) diff --git a/doc/src/sgml/man1/pg_dumpall.1 b/doc/src/sgml/man1/pg_dumpall.1 new file mode 100644 index 0000000..ecd216f --- /dev/null +++ b/doc/src/sgml/man1/pg_dumpall.1 @@ -0,0 +1,581 @@ +'\" t +.\" Title: pg_dumpall +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_DUMPALL" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_dumpall \- extract a PostgreSQL database cluster into a script file +.SH "SYNOPSIS" +.HP \w'\fBpg_dumpall\fR\ 'u +\fBpg_dumpall\fR [\fIconnection\-option\fR...] [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +pg_dumpall +is a utility for writing out (\(lqdumping\(rq) all +PostgreSQL +databases of a cluster into one script file\&. The script file contains +SQL +commands that can be used as input to +\fBpsql\fR(1) +to restore the databases\&. It does this by calling +\fBpg_dump\fR(1) +for each database in the cluster\&. +pg_dumpall +also dumps global objects that are common to all databases, namely database roles, tablespaces, and privilege grants for configuration parameters\&. (pg_dump +does not save these objects\&.) +.PP +Since +pg_dumpall +reads tables from all databases you will most likely have to connect as a database superuser in order to produce a complete dump\&. Also you will need superuser privileges to execute the saved script in order to be allowed to add roles and create databases\&. +.PP +The SQL script will be written to the standard output\&. Use the +\fB\-f\fR/\fB\-\-file\fR +option or shell operators to redirect it into a file\&. +.PP +pg_dumpall +needs to connect several times to the +PostgreSQL +server (once per database)\&. If you use password authentication it will ask for a password each time\&. It is convenient to have a +~/\&.pgpass +file in such cases\&. See +Section\ \&34.16 +for more information\&. +.SH "OPTIONS" +.PP +The following command\-line options control the content and format of the output\&. +.PP +\fB\-a\fR +.br +\fB\-\-data\-only\fR +.RS 4 +Dump only the data, not the schema (data definitions)\&. +.RE +.PP +\fB\-c\fR +.br +\fB\-\-clean\fR +.RS 4 +Include SQL commands to clean (drop) databases before recreating them\&. +\fBDROP\fR +commands for roles and tablespaces are added as well\&. +.RE +.PP +\fB\-E \fR\fB\fIencoding\fR\fR +.br +\fB\-\-encoding=\fR\fB\fIencoding\fR\fR +.RS 4 +Create the dump in the specified character set encoding\&. By default, the dump is created in the database encoding\&. (Another way to get the same result is to set the +\fBPGCLIENTENCODING\fR +environment variable to the desired dump encoding\&.) +.RE +.PP +\fB\-f \fR\fB\fIfilename\fR\fR +.br +\fB\-\-file=\fR\fB\fIfilename\fR\fR +.RS 4 +Send output to the specified file\&. If this is omitted, the standard output is used\&. +.RE +.PP +\fB\-g\fR +.br +\fB\-\-globals\-only\fR +.RS 4 +Dump only global objects (roles and tablespaces), no databases\&. +.RE +.PP +\fB\-O\fR +.br +\fB\-\-no\-owner\fR +.RS 4 +Do not output commands to set ownership of objects to match the original database\&. By default, +pg_dumpall +issues +\fBALTER OWNER\fR +or +\fBSET SESSION AUTHORIZATION\fR +statements to set ownership of created schema elements\&. These statements will fail when the script is run unless it is started by a superuser (or the same user that owns all of the objects in the script)\&. To make a script that can be restored by any user, but will give that user ownership of all the objects, specify +\fB\-O\fR\&. +.RE +.PP +\fB\-r\fR +.br +\fB\-\-roles\-only\fR +.RS 4 +Dump only roles, no databases or tablespaces\&. +.RE +.PP +\fB\-s\fR +.br +\fB\-\-schema\-only\fR +.RS 4 +Dump only the object definitions (schema), not data\&. +.RE +.PP +\fB\-S \fR\fB\fIusername\fR\fR +.br +\fB\-\-superuser=\fR\fB\fIusername\fR\fR +.RS 4 +Specify the superuser user name to use when disabling triggers\&. This is relevant only if +\fB\-\-disable\-triggers\fR +is used\&. (Usually, it\*(Aqs better to leave this out, and instead start the resulting script as superuser\&.) +.RE +.PP +\fB\-t\fR +.br +\fB\-\-tablespaces\-only\fR +.RS 4 +Dump only tablespaces, no databases or roles\&. +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Specifies verbose mode\&. This will cause +pg_dumpall +to output start/stop times to the dump file, and progress messages to standard error\&. Repeating the option causes additional debug\-level messages to appear on standard error\&. The option is also passed down to +pg_dump\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_dumpall +version and exit\&. +.RE +.PP +\fB\-x\fR +.br +\fB\-\-no\-privileges\fR +.br +\fB\-\-no\-acl\fR +.RS 4 +Prevent dumping of access privileges (grant/revoke commands)\&. +.RE +.PP +\fB\-\-binary\-upgrade\fR +.RS 4 +This option is for use by in\-place upgrade utilities\&. Its use for other purposes is not recommended or supported\&. The behavior of the option may change in future releases without notice\&. +.RE +.PP +\fB\-\-column\-inserts\fR +.br +\fB\-\-attribute\-inserts\fR +.RS 4 +Dump data as +\fBINSERT\fR +commands with explicit column names (INSERT INTO \fItable\fR (\fIcolumn\fR, \&.\&.\&.) VALUES \&.\&.\&.)\&. This will make restoration very slow; it is mainly useful for making dumps that can be loaded into non\-PostgreSQL +databases\&. +.RE +.PP +\fB\-\-disable\-dollar\-quoting\fR +.RS 4 +This option disables the use of dollar quoting for function bodies, and forces them to be quoted using SQL standard string syntax\&. +.RE +.PP +\fB\-\-disable\-triggers\fR +.RS 4 +This option is relevant only when creating a data\-only dump\&. It instructs +pg_dumpall +to include commands to temporarily disable triggers on the target tables while the data is restored\&. Use this if you have referential integrity checks or other triggers on the tables that you do not want to invoke during data restore\&. +.sp +Presently, the commands emitted for +\fB\-\-disable\-triggers\fR +must be done as superuser\&. So, you should also specify a superuser name with +\fB\-S\fR, or preferably be careful to start the resulting script as a superuser\&. +.RE +.PP +\fB\-\-exclude\-database=\fR\fB\fIpattern\fR\fR +.RS 4 +Do not dump databases whose name matches +\fIpattern\fR\&. Multiple patterns can be excluded by writing multiple +\fB\-\-exclude\-database\fR +switches\&. The +\fIpattern\fR +parameter is interpreted as a pattern according to the same rules used by +psql\*(Aqs +\ed +commands (see +Patterns +below), so multiple databases can also be excluded by writing wildcard characters in the pattern\&. When using wildcards, be careful to quote the pattern if needed to prevent shell wildcard expansion\&. +.RE +.PP +\fB\-\-extra\-float\-digits=\fR\fB\fIndigits\fR\fR +.RS 4 +Use the specified value of extra_float_digits when dumping floating\-point data, instead of the maximum available precision\&. Routine dumps made for backup purposes should not use this option\&. +.RE +.PP +\fB\-\-if\-exists\fR +.RS 4 +Use conditional commands (i\&.e\&., add an +IF EXISTS +clause) to drop databases and other objects\&. This option is not valid unless +\fB\-\-clean\fR +is also specified\&. +.RE +.PP +\fB\-\-inserts\fR +.RS 4 +Dump data as +\fBINSERT\fR +commands (rather than +\fBCOPY\fR)\&. This will make restoration very slow; it is mainly useful for making dumps that can be loaded into non\-PostgreSQL +databases\&. Note that the restore might fail altogether if you have rearranged column order\&. The +\fB\-\-column\-inserts\fR +option is safer, though even slower\&. +.RE +.PP +\fB\-\-load\-via\-partition\-root\fR +.RS 4 +When dumping data for a table partition, make the +\fBCOPY\fR +or +\fBINSERT\fR +statements target the root of the partitioning hierarchy that contains it, rather than the partition itself\&. This causes the appropriate partition to be re\-determined for each row when the data is loaded\&. This may be useful when restoring data on a server where rows do not always fall into the same partitions as they did on the original server\&. That could happen, for example, if the partitioning column is of type text and the two systems have different definitions of the collation used to sort the partitioning column\&. +.RE +.PP +\fB\-\-lock\-wait\-timeout=\fR\fB\fItimeout\fR\fR +.RS 4 +Do not wait forever to acquire shared table locks at the beginning of the dump\&. Instead, fail if unable to lock a table within the specified +\fItimeout\fR\&. The timeout may be specified in any of the formats accepted by +\fBSET statement_timeout\fR\&. +.RE +.PP +\fB\-\-no\-comments\fR +.RS 4 +Do not dump comments\&. +.RE +.PP +\fB\-\-no\-publications\fR +.RS 4 +Do not dump publications\&. +.RE +.PP +\fB\-\-no\-role\-passwords\fR +.RS 4 +Do not dump passwords for roles\&. When restored, roles will have a null password, and password authentication will always fail until the password is set\&. Since password values aren\*(Aqt needed when this option is specified, the role information is read from the catalog view +pg_roles +instead of +pg_authid\&. Therefore, this option also helps if access to +pg_authid +is restricted by some security policy\&. +.RE +.PP +\fB\-\-no\-security\-labels\fR +.RS 4 +Do not dump security labels\&. +.RE +.PP +\fB\-\-no\-subscriptions\fR +.RS 4 +Do not dump subscriptions\&. +.RE +.PP +\fB\-\-no\-sync\fR +.RS 4 +By default, +\fBpg_dumpall\fR +will wait for all files to be written safely to disk\&. This option causes +\fBpg_dumpall\fR +to return without waiting, which is faster, but means that a subsequent operating system crash can leave the dump corrupt\&. Generally, this option is useful for testing but should not be used when dumping data from production installation\&. +.RE +.PP +\fB\-\-no\-table\-access\-method\fR +.RS 4 +Do not output commands to select table access methods\&. With this option, all objects will be created with whichever table access method is the default during restore\&. +.RE +.PP +\fB\-\-no\-tablespaces\fR +.RS 4 +Do not output commands to create tablespaces nor select tablespaces for objects\&. With this option, all objects will be created in whichever tablespace is the default during restore\&. +.RE +.PP +\fB\-\-no\-toast\-compression\fR +.RS 4 +Do not output commands to set +TOAST +compression methods\&. With this option, all columns will be restored with the default compression setting\&. +.RE +.PP +\fB\-\-no\-unlogged\-table\-data\fR +.RS 4 +Do not dump the contents of unlogged tables\&. This option has no effect on whether or not the table definitions (schema) are dumped; it only suppresses dumping the table data\&. +.RE +.PP +\fB\-\-on\-conflict\-do\-nothing\fR +.RS 4 +Add +ON CONFLICT DO NOTHING +to +\fBINSERT\fR +commands\&. This option is not valid unless +\fB\-\-inserts\fR +or +\fB\-\-column\-inserts\fR +is also specified\&. +.RE +.PP +\fB\-\-quote\-all\-identifiers\fR +.RS 4 +Force quoting of all identifiers\&. This option is recommended when dumping a database from a server whose +PostgreSQL +major version is different from +pg_dumpall\*(Aqs, or when the output is intended to be loaded into a server of a different major version\&. By default, +pg_dumpall +quotes only identifiers that are reserved words in its own major version\&. This sometimes results in compatibility issues when dealing with servers of other versions that may have slightly different sets of reserved words\&. Using +\fB\-\-quote\-all\-identifiers\fR +prevents such issues, at the price of a harder\-to\-read dump script\&. +.RE +.PP +\fB\-\-rows\-per\-insert=\fR\fB\fInrows\fR\fR +.RS 4 +Dump data as +\fBINSERT\fR +commands (rather than +\fBCOPY\fR)\&. Controls the maximum number of rows per +\fBINSERT\fR +command\&. The value specified must be a number greater than zero\&. Any error during restoring will cause only rows that are part of the problematic +\fBINSERT\fR +to be lost, rather than the entire table contents\&. +.RE +.PP +\fB\-\-use\-set\-session\-authorization\fR +.RS 4 +Output SQL\-standard +\fBSET SESSION AUTHORIZATION\fR +commands instead of +\fBALTER OWNER\fR +commands to determine object ownership\&. This makes the dump more standards compatible, but depending on the history of the objects in the dump, might not restore properly\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_dumpall +command line arguments, and exit\&. +.RE +.PP +The following command\-line options control the database connection parameters\&. +.PP +\fB\-d \fR\fB\fIconnstr\fR\fR +.br +\fB\-\-dbname=\fR\fB\fIconnstr\fR\fR +.RS 4 +Specifies parameters used to connect to the server, as a +connection string; these will override any conflicting command line options\&. +.sp +The option is called +\-\-dbname +for consistency with other client applications, but because +pg_dumpall +needs to connect to many databases, the database name in the connection string will be ignored\&. Use the +\-l +option to specify the name of the database used for the initial connection, which will dump global objects and discover what other databases should be dumped\&. +.RE +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the database server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. The default is taken from the +\fBPGHOST\fR +environment variable, if set, else a Unix domain socket connection is attempted\&. +.RE +.PP +\fB\-l \fR\fB\fIdbname\fR\fR +.br +\fB\-\-database=\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to connect to for dumping global objects and discovering what other databases should be dumped\&. If not specified, the +postgres +database will be used, and if that does not exist, +template1 +will be used\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. Defaults to the +\fBPGPORT\fR +environment variable, if set, or a compiled\-in default\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +pg_dumpall +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +pg_dumpall +will automatically prompt for a password if the server demands password authentication\&. However, +pg_dumpall +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.sp +Note that the password prompt will occur again for each database to be dumped\&. Usually, it\*(Aqs better to set up a +~/\&.pgpass +file than to rely on manual password entry\&. +.RE +.PP +\fB\-\-role=\fR\fB\fIrolename\fR\fR +.RS 4 +Specifies a role name to be used to create the dump\&. This option causes +pg_dumpall +to issue a +\fBSET ROLE\fR +\fIrolename\fR +command after connecting to the database\&. It is useful when the authenticated user (specified by +\fB\-U\fR) lacks privileges needed by +pg_dumpall, but can switch to a role with the required rights\&. Some installations have a policy against logging in directly as a superuser, and use of this option allows dumps to be made without violating the policy\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGHOST\fR +.br +\fBPGOPTIONS\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "NOTES" +.PP +Since +pg_dumpall +calls +pg_dump +internally, some diagnostic messages will refer to +pg_dump\&. +.PP +The +\fB\-\-clean\fR +option can be useful even when your intention is to restore the dump script into a fresh cluster\&. Use of +\fB\-\-clean\fR +authorizes the script to drop and re\-create the built\-in +postgres +and +template1 +databases, ensuring that those databases will retain the same properties (for instance, locale and encoding) that they had in the source cluster\&. Without the option, those databases will retain their existing database\-level properties, as well as any pre\-existing contents\&. +.PP +Once restored, it is wise to run +\fBANALYZE\fR +on each database so the optimizer has useful statistics\&. You can also run +\fBvacuumdb \-a \-z\fR +to analyze all databases\&. +.PP +The dump script should not be expected to run completely without errors\&. In particular, because the script will issue +\fBCREATE ROLE\fR +for every role existing in the source cluster, it is certain to get a +\(lqrole already exists\(rq +error for the bootstrap superuser, unless the destination cluster was initialized with a different bootstrap superuser name\&. This error is harmless and should be ignored\&. Use of the +\fB\-\-clean\fR +option is likely to produce additional harmless error messages about non\-existent objects, although you can minimize those by adding +\fB\-\-if\-exists\fR\&. +.PP +pg_dumpall +requires all needed tablespace directories to exist before the restore; otherwise, database creation will fail for databases in non\-default locations\&. +.SH "EXAMPLES" +.PP +To dump all databases: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dumpall > db\&.out\fR +.fi +.if n \{\ +.RE +.\} +.PP +To restore database(s) from this file, you can use: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpsql \-f db\&.out postgres\fR +.fi +.if n \{\ +.RE +.\} +.sp +It is not important to which database you connect here since the script file created by +pg_dumpall +will contain the appropriate commands to create and connect to the saved databases\&. An exception is that if you specified +\fB\-\-clean\fR, you must connect to the +postgres +database initially; the script will attempt to drop other databases immediately, and that will fail for the database you are connected to\&. +.SH "SEE ALSO" +.PP +Check +\fBpg_dump\fR(1) +for details on possible error conditions\&. diff --git a/doc/src/sgml/man1/pg_isready.1 b/doc/src/sgml/man1/pg_isready.1 new file mode 100644 index 0000000..89502e5 --- /dev/null +++ b/doc/src/sgml/man1/pg_isready.1 @@ -0,0 +1,191 @@ +'\" t +.\" Title: pg_isready +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_ISREADY" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_isready \- check the connection status of a PostgreSQL server +.SH "SYNOPSIS" +.HP \w'\fBpg_isready\fR\ 'u +\fBpg_isready\fR [\fIconnection\-option\fR...] [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +pg_isready +is a utility for checking the connection status of a +PostgreSQL +database server\&. The exit status specifies the result of the connection check\&. +.SH "OPTIONS" +.PP +\fB\-d \fR\fB\fIdbname\fR\fR +.br +\fB\-\-dbname=\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to connect to\&. The +\fIdbname\fR +can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. +.RE +.PP +\fB\-h \fR\fB\fIhostname\fR\fR +.br +\fB\-\-host=\fR\fB\fIhostname\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix\-domain socket\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or the local Unix\-domain socket file extension on which the server is listening for connections\&. Defaults to the value of the +\fBPGPORT\fR +environment variable or, if not set, to the port specified at compile time, usually 5432\&. +.RE +.PP +\fB\-q\fR +.br +\fB\-\-quiet\fR +.RS 4 +Do not display status message\&. This is useful when scripting\&. +.RE +.PP +\fB\-t \fR\fB\fIseconds\fR\fR +.br +\fB\-\-timeout=\fR\fB\fIseconds\fR\fR +.RS 4 +The maximum number of seconds to wait when attempting connection before returning that the server is not responding\&. Setting to 0 disables\&. The default is 3 seconds\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +Connect to the database as the user +\fIusername\fR +instead of the default\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_isready +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_isready +command line arguments, and exit\&. +.RE +.SH "EXIT STATUS" +.PP +pg_isready +returns +0 +to the shell if the server is accepting connections normally, +1 +if the server is rejecting connections (for example during startup), +2 +if there was no response to the connection attempt, and +3 +if no attempt was made (for example due to invalid parameters)\&. +.SH "ENVIRONMENT" +.PP +\fBpg_isready\fR, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.PP +The environment variable +\fBPG_COLOR\fR +specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.SH "NOTES" +.PP +It is not necessary to supply correct user name, password, or database name values to obtain the server status; however, if incorrect values are provided, the server will log a failed connection attempt\&. +.SH "EXAMPLES" +.PP +Standard Usage: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_isready\fR +/tmp:5432 \- accepting connections +$ \fBecho $?\fR +0 +.fi +.if n \{\ +.RE +.\} +.PP +Running with connection parameters to a +PostgreSQL +cluster in startup: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_isready \-h localhost \-p 5433\fR +localhost:5433 \- rejecting connections +$ \fBecho $?\fR +1 +.fi +.if n \{\ +.RE +.\} +.PP +Running with connection parameters to a non\-responsive +PostgreSQL +cluster: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_isready \-h someremotehost\fR +someremotehost:5432 \- no response +$ \fBecho $?\fR +2 +.fi +.if n \{\ +.RE +.\} +.sp + diff --git a/doc/src/sgml/man1/pg_receivewal.1 b/doc/src/sgml/man1/pg_receivewal.1 new file mode 100644 index 0000000..8ddf2e3 --- /dev/null +++ b/doc/src/sgml/man1/pg_receivewal.1 @@ -0,0 +1,419 @@ +'\" t +.\" Title: pg_receivewal +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_RECEIVEWAL" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_receivewal \- stream write\-ahead logs from a PostgreSQL server +.SH "SYNOPSIS" +.HP \w'\fBpg_receivewal\fR\ 'u +\fBpg_receivewal\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +pg_receivewal +is used to stream the write\-ahead log from a running +PostgreSQL +cluster\&. The write\-ahead log is streamed using the streaming replication protocol, and is written to a local directory of files\&. This directory can be used as the archive location for doing a restore using point\-in\-time recovery (see +Section\ \&26.3)\&. +.PP +pg_receivewal +streams the write\-ahead log in real time as it\*(Aqs being generated on the server, and does not wait for segments to complete like +archive_command +and +archive_library +do\&. For this reason, it is not necessary to set +archive_timeout +when using +pg_receivewal\&. +.PP +Unlike the WAL receiver of a PostgreSQL standby server, +pg_receivewal +by default flushes WAL data only when a WAL file is closed\&. The option +\fB\-\-synchronous\fR +must be specified to flush WAL data in real time\&. Since +pg_receivewal +does not apply WAL, you should not allow it to become a synchronous standby when +synchronous_commit +equals +remote_apply\&. If it does, it will appear to be a standby that never catches up, and will cause transaction commits to block\&. To avoid this, you should either configure an appropriate value for +synchronous_standby_names, or specify +\fIapplication_name\fR +for +pg_receivewal +that does not match it, or change the value of +\fIsynchronous_commit\fR +to something other than +remote_apply\&. +.PP +The write\-ahead log is streamed over a regular +PostgreSQL +connection and uses the replication protocol\&. The connection must be made with a user having +REPLICATION +permissions (see +Section\ \&22.2) or a superuser, and +pg_hba\&.conf +must permit the replication connection\&. The server must also be configured with +max_wal_senders +set high enough to leave at least one session available for the stream\&. +.PP +The starting point of the write\-ahead log streaming is calculated when +pg_receivewal +starts: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +First, scan the directory where the WAL segment files are written and find the newest completed segment file, using as the starting point the beginning of the next WAL segment file\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +If a starting point cannot be calculated with the previous method, and if a replication slot is used, an extra +\fBREAD_REPLICATION_SLOT\fR +command is issued to retrieve the slot\*(Aqs +restart_lsn +to use as the starting point\&. This option is only available when streaming write\-ahead logs from +PostgreSQL +15 and up\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +If a starting point cannot be calculated with the previous method, the latest WAL flush location is used as reported by the server from an +IDENTIFY_SYSTEM +command\&. +.RE +.PP +If the connection is lost, or if it cannot be initially established, with a non\-fatal error, +pg_receivewal +will retry the connection indefinitely, and reestablish streaming as soon as possible\&. To avoid this behavior, use the +\-n +parameter\&. +.PP +In the absence of fatal errors, +pg_receivewal +will run until terminated by the +SIGINT +signal (Control+C)\&. +.SH "OPTIONS" +.PP +\fB\-D \fR\fB\fIdirectory\fR\fR +.br +\fB\-\-directory=\fR\fB\fIdirectory\fR\fR +.RS 4 +Directory to write the output to\&. +.sp +This parameter is required\&. +.RE +.PP +\fB\-E \fR\fB\fIlsn\fR\fR +.br +\fB\-\-endpos=\fR\fB\fIlsn\fR\fR +.RS 4 +Automatically stop replication and exit with normal exit status 0 when receiving reaches the specified LSN\&. +.sp +If there is a record with LSN exactly equal to +\fIlsn\fR, the record will be processed\&. +.RE +.PP +\fB\-\-if\-not\-exists\fR +.RS 4 +Do not error out when +\fB\-\-create\-slot\fR +is specified and a slot with the specified name already exists\&. +.RE +.PP +\fB\-n\fR +.br +\fB\-\-no\-loop\fR +.RS 4 +Don\*(Aqt loop on connection errors\&. Instead, exit right away with an error\&. +.RE +.PP +\fB\-\-no\-sync\fR +.RS 4 +This option causes +\fBpg_receivewal\fR +to not force WAL data to be flushed to disk\&. This is faster, but means that a subsequent operating system crash can leave the WAL segments corrupt\&. Generally, this option is useful for testing but should not be used when doing WAL archiving on a production deployment\&. +.sp +This option is incompatible with +\-\-synchronous\&. +.RE +.PP +\fB\-s \fR\fB\fIinterval\fR\fR +.br +\fB\-\-status\-interval=\fR\fB\fIinterval\fR\fR +.RS 4 +Specifies the number of seconds between status packets sent back to the server\&. This allows for easier monitoring of the progress from server\&. A value of zero disables the periodic status updates completely, although an update will still be sent when requested by the server, to avoid timeout disconnect\&. The default value is 10 seconds\&. +.RE +.PP +\fB\-S \fR\fB\fIslotname\fR\fR +.br +\fB\-\-slot=\fR\fB\fIslotname\fR\fR +.RS 4 +Require +pg_receivewal +to use an existing replication slot (see +Section\ \&27.2.6)\&. When this option is used, +pg_receivewal +will report a flush position to the server, indicating when each segment has been synchronized to disk so that the server can remove that segment if it is not otherwise needed\&. +.sp +When the replication client of +pg_receivewal +is configured on the server as a synchronous standby, then using a replication slot will report the flush position to the server, but only when a WAL file is closed\&. Therefore, that configuration will cause transactions on the primary to wait for a long time and effectively not work satisfactorily\&. The option +\-\-synchronous +(see below) must be specified in addition to make this work correctly\&. +.RE +.PP +\fB\-\-synchronous\fR +.RS 4 +Flush the WAL data to disk immediately after it has been received\&. Also send a status packet back to the server immediately after flushing, regardless of +\-\-status\-interval\&. +.sp +This option should be specified if the replication client of +pg_receivewal +is configured on the server as a synchronous standby, to ensure that timely feedback is sent to the server\&. +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Enables verbose mode\&. +.RE +.PP +\fB\-Z \fR\fB\fIlevel\fR\fR +.br +\fB\-Z \fR\fB\fImethod\fR\fR\fB[:\fR\fB\fIdetail\fR\fR\fB]\fR +.br +\fB\-\-compress=\fR\fB\fIlevel\fR\fR +.br +\fB\-\-compress=\fR\fB\fImethod\fR\fR\fB[:\fR\fB\fIdetail\fR\fR\fB]\fR +.RS 4 +Enables compression of write\-ahead logs\&. +.sp +The compression method can be set to +gzip, +lz4 +(if +PostgreSQL +was compiled with +\fB\-\-with\-lz4\fR) or +none +for no compression\&. A compression detail string can optionally be specified\&. If the detail string is an integer, it specifies the compression level\&. Otherwise, it should be a comma\-separated list of items, each of the form +keyword +or +keyword=value\&. Currently, the only supported keyword is +level\&. +.sp +If no compression level is specified, the default compression level will be used\&. If only a level is specified without mentioning an algorithm, +gzip +compression will be used if the level is greater than 0, and no compression will be used if the level is 0\&. +.sp +The suffix +\&.gz +will automatically be added to all filenames when using +gzip, and the suffix +\&.lz4 +is added when using +lz4\&. +.RE +.PP +The following command\-line options control the database connection parameters\&. +.PP +\fB\-d \fR\fB\fIconnstr\fR\fR +.br +\fB\-\-dbname=\fR\fB\fIconnstr\fR\fR +.RS 4 +Specifies parameters used to connect to the server, as a +connection string; these will override any conflicting command line options\&. +.sp +The option is called +\-\-dbname +for consistency with other client applications, but because +pg_receivewal +doesn\*(Aqt connect to any particular database in the cluster, database name in the connection string will be ignored\&. +.RE +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. The default is taken from the +\fBPGHOST\fR +environment variable, if set, else a Unix domain socket connection is attempted\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. Defaults to the +\fBPGPORT\fR +environment variable, if set, or a compiled\-in default\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +pg_receivewal +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +pg_receivewal +will automatically prompt for a password if the server demands password authentication\&. However, +pg_receivewal +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +pg_receivewal +can perform one of the two following actions in order to control physical replication slots: +.PP +\fB\-\-create\-slot\fR +.RS 4 +Create a new physical replication slot with the name specified in +\fB\-\-slot\fR, then exit\&. +.RE +.PP +\fB\-\-drop\-slot\fR +.RS 4 +Drop the replication slot with the name specified in +\fB\-\-slot\fR, then exit\&. +.RE +.PP +Other options are also available: +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_receivewal +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_receivewal +command line arguments, and exit\&. +.RE +.SH "EXIT STATUS" +.PP +pg_receivewal +will exit with status 0 when terminated by the +SIGINT +signal\&. (That is the normal way to end it\&. Hence it is not an error\&.) For fatal errors or other signals, the exit status will be nonzero\&. +.SH "ENVIRONMENT" +.PP +This utility, like most other +PostgreSQL +utilities, uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.PP +The environment variable +\fBPG_COLOR\fR +specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.SH "NOTES" +.PP +When using +pg_receivewal +instead of +archive_command +or +archive_library +as the main WAL backup method, it is strongly recommended to use replication slots\&. Otherwise, the server is free to recycle or remove write\-ahead log files before they are backed up, because it does not have any information, either from +archive_command +or +archive_library +or the replication slots, about how far the WAL stream has been archived\&. Note, however, that a replication slot will fill up the server\*(Aqs disk space if the receiver does not keep up with fetching the WAL data\&. +.PP +pg_receivewal +will preserve group permissions on the received WAL files if group permissions are enabled on the source cluster\&. +.SH "EXAMPLES" +.PP +To stream the write\-ahead log from the server at +mydbserver +and store it in the local directory +/usr/local/pgsql/archive: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_receivewal \-h mydbserver \-D /usr/local/pgsql/archive\fR +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBpg_basebackup\fR(1) diff --git a/doc/src/sgml/man1/pg_recvlogical.1 b/doc/src/sgml/man1/pg_recvlogical.1 new file mode 100644 index 0000000..2d65dbe --- /dev/null +++ b/doc/src/sgml/man1/pg_recvlogical.1 @@ -0,0 +1,328 @@ +'\" t +.\" Title: pg_recvlogical +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_RECVLOGICAL" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_recvlogical \- control PostgreSQL logical decoding streams +.SH "SYNOPSIS" +.HP \w'\fBpg_recvlogical\fR\ 'u +\fBpg_recvlogical\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +\fBpg_recvlogical\fR +controls logical decoding replication slots and streams data from such replication slots\&. +.PP +It creates a replication\-mode connection, so it is subject to the same constraints as +\fBpg_receivewal\fR(1), plus those for logical replication (see +Chapter\ \&49)\&. +.PP +\fBpg_recvlogical\fR +has no equivalent to the logical decoding SQL interface\*(Aqs peek and get modes\&. It sends replay confirmations for data lazily as it receives it and on clean exit\&. To examine pending data on a slot without consuming it, use +\fBpg_logical_slot_peek_changes\fR\&. +.SH "OPTIONS" +.PP +At least one of the following options must be specified to select an action: +.PP +\fB\-\-create\-slot\fR +.RS 4 +Create a new logical replication slot with the name specified by +\fB\-\-slot\fR, using the output plugin specified by +\fB\-\-plugin\fR, for the database specified by +\fB\-\-dbname\fR\&. +.sp +The +\fB\-\-two\-phase\fR +can be specified with +\fB\-\-create\-slot\fR +to enable decoding of prepared transactions\&. +.RE +.PP +\fB\-\-drop\-slot\fR +.RS 4 +Drop the replication slot with the name specified by +\fB\-\-slot\fR, then exit\&. +.RE +.PP +\fB\-\-start\fR +.RS 4 +Begin streaming changes from the logical replication slot specified by +\fB\-\-slot\fR, continuing until terminated by a signal\&. If the server side change stream ends with a server shutdown or disconnect, retry in a loop unless +\fB\-\-no\-loop\fR +is specified\&. +.sp +The stream format is determined by the output plugin specified when the slot was created\&. +.sp +The connection must be to the same database used to create the slot\&. +.RE +.PP +\fB\-\-create\-slot\fR +and +\fB\-\-start\fR +can be specified together\&. +\fB\-\-drop\-slot\fR +cannot be combined with another action\&. +.PP +The following command\-line options control the location and format of the output and other replication behavior: +.PP +\fB\-E \fR\fB\fIlsn\fR\fR +.br +\fB\-\-endpos=\fR\fB\fIlsn\fR\fR +.RS 4 +In +\fB\-\-start\fR +mode, automatically stop replication and exit with normal exit status 0 when receiving reaches the specified LSN\&. If specified when not in +\fB\-\-start\fR +mode, an error is raised\&. +.sp +If there\*(Aqs a record with LSN exactly equal to +\fIlsn\fR, the record will be output\&. +.sp +The +\fB\-\-endpos\fR +option is not aware of transaction boundaries and may truncate output partway through a transaction\&. Any partially output transaction will not be consumed and will be replayed again when the slot is next read from\&. Individual messages are never truncated\&. +.RE +.PP +\fB\-f \fR\fB\fIfilename\fR\fR +.br +\fB\-\-file=\fR\fB\fIfilename\fR\fR +.RS 4 +Write received and decoded transaction data into this file\&. Use +\- +for +stdout\&. +.RE +.PP +\fB\-F \fR\fB\fIinterval_seconds\fR\fR +.br +\fB\-\-fsync\-interval=\fR\fB\fIinterval_seconds\fR\fR +.RS 4 +Specifies how often +pg_recvlogical +should issue +\fBfsync()\fR +calls to ensure the output file is safely flushed to disk\&. +.sp +The server will occasionally request the client to perform a flush and report the flush position to the server\&. This setting is in addition to that, to perform flushes more frequently\&. +.sp +Specifying an interval of +0 +disables issuing +\fBfsync()\fR +calls altogether, while still reporting progress to the server\&. In this case, data could be lost in the event of a crash\&. +.RE +.PP +\fB\-I \fR\fB\fIlsn\fR\fR +.br +\fB\-\-startpos=\fR\fB\fIlsn\fR\fR +.RS 4 +In +\fB\-\-start\fR +mode, start replication from the given LSN\&. For details on the effect of this, see the documentation in +Chapter\ \&49 +and +Section\ \&55.4\&. Ignored in other modes\&. +.RE +.PP +\fB\-\-if\-not\-exists\fR +.RS 4 +Do not error out when +\fB\-\-create\-slot\fR +is specified and a slot with the specified name already exists\&. +.RE +.PP +\fB\-n\fR +.br +\fB\-\-no\-loop\fR +.RS 4 +When the connection to the server is lost, do not retry in a loop, just exit\&. +.RE +.PP +\fB\-o \fR\fB\fIname\fR\fR\fB[=\fR\fB\fIvalue\fR\fR\fB]\fR +.br +\fB\-\-option=\fR\fB\fIname\fR\fR\fB[=\fR\fB\fIvalue\fR\fR\fB]\fR +.RS 4 +Pass the option +\fIname\fR +to the output plugin with, if specified, the option value +\fIvalue\fR\&. Which options exist and their effects depends on the used output plugin\&. +.RE +.PP +\fB\-P \fR\fB\fIplugin\fR\fR +.br +\fB\-\-plugin=\fR\fB\fIplugin\fR\fR +.RS 4 +When creating a slot, use the specified logical decoding output plugin\&. See +Chapter\ \&49\&. This option has no effect if the slot already exists\&. +.RE +.PP +\fB\-s \fR\fB\fIinterval_seconds\fR\fR +.br +\fB\-\-status\-interval=\fR\fB\fIinterval_seconds\fR\fR +.RS 4 +This option has the same effect as the option of the same name in +\fBpg_receivewal\fR(1)\&. See the description there\&. +.RE +.PP +\fB\-S \fR\fB\fIslot_name\fR\fR +.br +\fB\-\-slot=\fR\fB\fIslot_name\fR\fR +.RS 4 +In +\fB\-\-start\fR +mode, use the existing logical replication slot named +\fIslot_name\fR\&. In +\fB\-\-create\-slot\fR +mode, create the slot with this name\&. In +\fB\-\-drop\-slot\fR +mode, delete the slot with this name\&. +.RE +.PP +\fB\-t\fR +.br +\fB\-\-two\-phase\fR +.RS 4 +Enables decoding of prepared transactions\&. This option may only be specified with +\fB\-\-create\-slot\fR +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Enables verbose mode\&. +.RE +.PP +The following command\-line options control the database connection parameters\&. +.PP +\fB\-d \fR\fB\fIdbname\fR\fR +.br +\fB\-\-dbname=\fR\fB\fIdbname\fR\fR +.RS 4 +The database to connect to\&. See the description of the actions for what this means in detail\&. The +\fIdbname\fR +can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. Defaults to the user name\&. +.RE +.PP +\fB\-h \fR\fB\fIhostname\-or\-ip\fR\fR +.br +\fB\-\-host=\fR\fB\fIhostname\-or\-ip\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. The default is taken from the +\fBPGHOST\fR +environment variable, if set, else a Unix domain socket connection is attempted\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. Defaults to the +\fBPGPORT\fR +environment variable, if set, or a compiled\-in default\&. +.RE +.PP +\fB\-U \fR\fB\fIuser\fR\fR +.br +\fB\-\-username=\fR\fB\fIuser\fR\fR +.RS 4 +User name to connect as\&. Defaults to current operating system user name\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +pg_recvlogical +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +pg_recvlogical +will automatically prompt for a password if the server demands password authentication\&. However, +pg_recvlogical +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +The following additional options are available: +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_recvlogical +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_recvlogical +command line arguments, and exit\&. +.RE +.SH "ENVIRONMENT" +.PP +This utility, like most other +PostgreSQL +utilities, uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.PP +The environment variable +\fBPG_COLOR\fR +specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.SH "NOTES" +.PP +pg_recvlogical +will preserve group permissions on the received WAL files if group permissions are enabled on the source cluster\&. +.SH "EXAMPLES" +.PP +See +Section\ \&49.1 +for an example\&. +.SH "SEE ALSO" +\fBpg_receivewal\fR(1) diff --git a/doc/src/sgml/man1/pg_resetwal.1 b/doc/src/sgml/man1/pg_resetwal.1 new file mode 100644 index 0000000..8d15d16 --- /dev/null +++ b/doc/src/sgml/man1/pg_resetwal.1 @@ -0,0 +1,287 @@ +'\" t +.\" Title: pg_resetwal +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_RESETWAL" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_resetwal \- reset the write\-ahead log and other control information of a PostgreSQL database cluster +.SH "SYNOPSIS" +.HP \w'\fBpg_resetwal\fR\ 'u +\fBpg_resetwal\fR [\fB\-f\fR | \fB\-\-force\fR] [\fB\-n\fR | \fB\-\-dry\-run\fR] [\fIoption\fR...] [\fB\-D\fR | \fB\-\-pgdata\fR]\fIdatadir\fR +.SH "DESCRIPTION" +.PP +\fBpg_resetwal\fR +clears the write\-ahead log (WAL) and optionally resets some other control information stored in the +pg_control +file\&. This function is sometimes needed if these files have become corrupted\&. It should be used only as a last resort, when the server will not start due to such corruption\&. +.PP +After running this command, it should be possible to start the server, but bear in mind that the database might contain inconsistent data due to partially\-committed transactions\&. You should immediately dump your data, run +\fBinitdb\fR, and restore\&. After restore, check for inconsistencies and repair as needed\&. +.PP +This utility can only be run by the user who installed the server, because it requires read/write access to the data directory\&. For safety reasons, you must specify the data directory on the command line\&. +\fBpg_resetwal\fR +does not use the environment variable +\fBPGDATA\fR\&. +.PP +If +\fBpg_resetwal\fR +complains that it cannot determine valid data for +pg_control, you can force it to proceed anyway by specifying the +\fB\-f\fR +(force) option\&. In this case plausible values will be substituted for the missing data\&. Most of the fields can be expected to match, but manual assistance might be needed for the next OID, next transaction ID and epoch, next multitransaction ID and offset, and WAL starting location fields\&. These fields can be set using the options discussed below\&. If you are not able to determine correct values for all these fields, +\fB\-f\fR +can still be used, but the recovered database must be treated with even more suspicion than usual: an immediate dump and restore is imperative\&. +\fIDo not\fR +execute any data\-modifying operations in the database before you dump, as any such action is likely to make the corruption worse\&. +.SH "OPTIONS" +.PP +\fB\-f\fR +.br +\fB\-\-force\fR +.RS 4 +Force +\fBpg_resetwal\fR +to proceed even if it cannot determine valid data for +pg_control, as explained above\&. +.RE +.PP +\fB\-n\fR +.br +\fB\-\-dry\-run\fR +.RS 4 +The +\fB\-n\fR/\fB\-\-dry\-run\fR +option instructs +\fBpg_resetwal\fR +to print the values reconstructed from +pg_control +and values about to be changed, and then exit without modifying anything\&. This is mainly a debugging tool, but can be useful as a sanity check before allowing +\fBpg_resetwal\fR +to proceed for real\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Display version information, then exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help, then exit\&. +.RE +.PP +The following options are only needed when +\fBpg_resetwal\fR +is unable to determine appropriate values by reading +pg_control\&. Safe values can be determined as described below\&. For values that take numeric arguments, hexadecimal values can be specified by using the prefix +0x\&. +.PP +\fB\-c \fR\fB\fIxid\fR\fR\fB,\fR\fB\fIxid\fR\fR +.br +\fB\-\-commit\-timestamp\-ids=\fR\fB\fIxid\fR\fR\fB,\fR\fB\fIxid\fR\fR +.RS 4 +Manually set the oldest and newest transaction IDs for which the commit time can be retrieved\&. +.sp +A safe value for the oldest transaction ID for which the commit time can be retrieved (first part) can be determined by looking for the numerically smallest file name in the directory +pg_commit_ts +under the data directory\&. Conversely, a safe value for the newest transaction ID for which the commit time can be retrieved (second part) can be determined by looking for the numerically greatest file name in the same directory\&. The file names are in hexadecimal\&. +.RE +.PP +\fB\-e \fR\fB\fIxid_epoch\fR\fR +.br +\fB\-\-epoch=\fR\fB\fIxid_epoch\fR\fR +.RS 4 +Manually set the next transaction ID\*(Aqs epoch\&. +.sp +The transaction ID epoch is not actually stored anywhere in the database except in the field that is set by +\fBpg_resetwal\fR, so any value will work so far as the database itself is concerned\&. You might need to adjust this value to ensure that replication systems such as +Slony\-I +and +Skytools +work correctly \(em if so, an appropriate value should be obtainable from the state of the downstream replicated database\&. +.RE +.PP +\fB\-l \fR\fB\fIwalfile\fR\fR +.br +\fB\-\-next\-wal\-file=\fR\fB\fIwalfile\fR\fR +.RS 4 +Manually set the WAL starting location by specifying the name of the next WAL segment file\&. +.sp +The name of next WAL segment file should be larger than any WAL segment file name currently existing in the directory +pg_wal +under the data directory\&. These names are also in hexadecimal and have three parts\&. The first part is the +\(lqtimeline ID\(rq +and should usually be kept the same\&. For example, if +00000001000000320000004A +is the largest entry in +pg_wal, use +\-l 00000001000000320000004B +or higher\&. +.sp +Note that when using nondefault WAL segment sizes, the numbers in the WAL file names are different from the LSNs that are reported by system functions and system views\&. This option takes a WAL file name, not an LSN\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +\fBpg_resetwal\fR +itself looks at the files in +pg_wal +and chooses a default +\fB\-l\fR +setting beyond the last existing file name\&. Therefore, manual adjustment of +\fB\-l\fR +should only be needed if you are aware of WAL segment files that are not currently present in +pg_wal, such as entries in an offline archive; or if the contents of +pg_wal +have been lost entirely\&. +.sp .5v +.RE +.RE +.PP +\fB\-m \fR\fB\fImxid\fR\fR\fB,\fR\fB\fImxid\fR\fR +.br +\fB\-\-multixact\-ids=\fR\fB\fImxid\fR\fR\fB,\fR\fB\fImxid\fR\fR +.RS 4 +Manually set the next and oldest multitransaction ID\&. +.sp +A safe value for the next multitransaction ID (first part) can be determined by looking for the numerically largest file name in the directory +pg_multixact/offsets +under the data directory, adding one, and then multiplying by 65536 (0x10000)\&. Conversely, a safe value for the oldest multitransaction ID (second part of +\fB\-m\fR) can be determined by looking for the numerically smallest file name in the same directory and multiplying by 65536\&. The file names are in hexadecimal, so the easiest way to do this is to specify the option value in hexadecimal and append four zeroes\&. +.RE +.PP +\fB\-o \fR\fB\fIoid\fR\fR +.br +\fB\-\-next\-oid=\fR\fB\fIoid\fR\fR +.RS 4 +Manually set the next OID\&. +.sp +There is no comparably easy way to determine a next OID that\*(Aqs beyond the largest one in the database, but fortunately it is not critical to get the next\-OID setting right\&. +.RE +.PP +\fB\-O \fR\fB\fImxoff\fR\fR +.br +\fB\-\-multixact\-offset=\fR\fB\fImxoff\fR\fR +.RS 4 +Manually set the next multitransaction offset\&. +.sp +A safe value can be determined by looking for the numerically largest file name in the directory +pg_multixact/members +under the data directory, adding one, and then multiplying by 52352 (0xCC80)\&. The file names are in hexadecimal\&. There is no simple recipe such as the ones for other options of appending zeroes\&. +.RE +.PP +\fB\-\-wal\-segsize=\fR\fB\fIwal_segment_size\fR\fR +.RS 4 +Set the new WAL segment size, in megabytes\&. The value must be set to a power of 2 between 1 and 1024 (megabytes)\&. See the same option of +\fBinitdb\fR(1) +for more information\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +While +\fBpg_resetwal\fR +will set the WAL starting address beyond the latest existing WAL segment file, some segment size changes can cause previous WAL file names to be reused\&. It is recommended to use +\fB\-l\fR +together with this option to manually set the WAL starting address if WAL file name overlap will cause problems with your archiving strategy\&. +.sp .5v +.RE +.RE +.PP +\fB\-u \fR\fB\fIxid\fR\fR +.br +\fB\-\-oldest\-transaction\-id=\fR\fB\fIxid\fR\fR +.RS 4 +Manually set the oldest unfrozen transaction ID\&. +.sp +A safe value can be determined by looking for the numerically smallest file name in the directory +pg_xact +under the data directory and then multiplying by 1048576 (0x100000)\&. Note that the file names are in hexadecimal\&. It is usually easiest to specify the option value in hexadecimal too\&. For example, if +0007 +is the smallest entry in +pg_xact, +\-u 0x700000 +will work (five trailing zeroes provide the proper multiplier)\&. +.RE +.PP +\fB\-x \fR\fB\fIxid\fR\fR +.br +\fB\-\-next\-transaction\-id=\fR\fB\fIxid\fR\fR +.RS 4 +Manually set the next transaction ID\&. +.sp +A safe value can be determined by looking for the numerically largest file name in the directory +pg_xact +under the data directory, adding one, and then multiplying by 1048576 (0x100000)\&. Note that the file names are in hexadecimal\&. It is usually easiest to specify the option value in hexadecimal too\&. For example, if +0011 +is the largest entry in +pg_xact, +\-x 0x1200000 +will work (five trailing zeroes provide the proper multiplier)\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.SH "NOTES" +.PP +This command must not be used when the server is running\&. +\fBpg_resetwal\fR +will refuse to start up if it finds a server lock file in the data directory\&. If the server crashed then a lock file might have been left behind; in that case you can remove the lock file to allow +\fBpg_resetwal\fR +to run\&. But before you do so, make doubly certain that there is no server process still alive\&. +.PP +\fBpg_resetwal\fR +works only with servers of the same major version\&. +.SH "SEE ALSO" +\fBpg_controldata\fR(1) diff --git a/doc/src/sgml/man1/pg_restore.1 b/doc/src/sgml/man1/pg_restore.1 new file mode 100644 index 0000000..560a9f5 --- /dev/null +++ b/doc/src/sgml/man1/pg_restore.1 @@ -0,0 +1,873 @@ +'\" t +.\" Title: pg_restore +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_RESTORE" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_restore \- restore a PostgreSQL database from an archive file created by pg_dump +.SH "SYNOPSIS" +.HP \w'\fBpg_restore\fR\ 'u +\fBpg_restore\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\fIfilename\fR] +.SH "DESCRIPTION" +.PP +pg_restore +is a utility for restoring a +PostgreSQL +database from an archive created by +\fBpg_dump\fR(1) +in one of the non\-plain\-text formats\&. It will issue the commands necessary to reconstruct the database to the state it was in at the time it was saved\&. The archive files also allow +pg_restore +to be selective about what is restored, or even to reorder the items prior to being restored\&. The archive files are designed to be portable across architectures\&. +.PP +pg_restore +can operate in two modes\&. If a database name is specified, +pg_restore +connects to that database and restores archive contents directly into the database\&. Otherwise, a script containing the SQL commands necessary to rebuild the database is created and written to a file or standard output\&. This script output is equivalent to the plain text output format of +pg_dump\&. Some of the options controlling the output are therefore analogous to +pg_dump +options\&. +.PP +Obviously, +pg_restore +cannot restore information that is not present in the archive file\&. For instance, if the archive was made using the +\(lqdump data as \fBINSERT\fR commands\(rq +option, +pg_restore +will not be able to load the data using +\fBCOPY\fR +statements\&. +.SH "OPTIONS" +.PP +pg_restore +accepts the following command line arguments\&. +.PP +\fIfilename\fR +.RS 4 +Specifies the location of the archive file (or directory, for a directory\-format archive) to be restored\&. If not specified, the standard input is used\&. +.RE +.PP +\fB\-a\fR +.br +\fB\-\-data\-only\fR +.RS 4 +Restore only the data, not the schema (data definitions)\&. Table data, large objects, and sequence values are restored, if present in the archive\&. +.sp +This option is similar to, but for historical reasons not identical to, specifying +\fB\-\-section=data\fR\&. +.RE +.PP +\fB\-c\fR +.br +\fB\-\-clean\fR +.RS 4 +Clean (drop) database objects before recreating them\&. (Unless +\fB\-\-if\-exists\fR +is used, this might generate some harmless error messages, if any objects were not present in the destination database\&.) +.RE +.PP +\fB\-C\fR +.br +\fB\-\-create\fR +.RS 4 +Create the database before restoring into it\&. If +\fB\-\-clean\fR +is also specified, drop and recreate the target database before connecting to it\&. +.sp +With +\fB\-\-create\fR, +pg_restore +also restores the database\*(Aqs comment if any, and any configuration variable settings that are specific to this database, that is, any +\fBALTER DATABASE \&.\&.\&. SET \&.\&.\&.\fR +and +\fBALTER ROLE \&.\&.\&. IN DATABASE \&.\&.\&. SET \&.\&.\&.\fR +commands that mention this database\&. Access privileges for the database itself are also restored, unless +\fB\-\-no\-acl\fR +is specified\&. +.sp +When this option is used, the database named with +\fB\-d\fR +is used only to issue the initial +\fBDROP DATABASE\fR +and +\fBCREATE DATABASE\fR +commands\&. All data is restored into the database name that appears in the archive\&. +.RE +.PP +\fB\-d \fR\fB\fIdbname\fR\fR +.br +\fB\-\-dbname=\fR\fB\fIdbname\fR\fR +.RS 4 +Connect to database +\fIdbname\fR +and restore directly into the database\&. The +\fIdbname\fR +can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. +.RE +.PP +\fB\-e\fR +.br +\fB\-\-exit\-on\-error\fR +.RS 4 +Exit if an error is encountered while sending SQL commands to the database\&. The default is to continue and to display a count of errors at the end of the restoration\&. +.RE +.PP +\fB\-f \fR\fB\fIfilename\fR\fR +.br +\fB\-\-file=\fR\fB\fIfilename\fR\fR +.RS 4 +Specify output file for generated script, or for the listing when used with +\fB\-l\fR\&. Use +\- +for +stdout\&. +.RE +.PP +\fB\-F \fR\fB\fIformat\fR\fR +.br +\fB\-\-format=\fR\fB\fIformat\fR\fR +.RS 4 +Specify format of the archive\&. It is not necessary to specify the format, since +pg_restore +will determine the format automatically\&. If specified, it can be one of the following: +.PP +c +.br +custom +.RS 4 +The archive is in the custom format of +pg_dump\&. +.RE +.PP +d +.br +directory +.RS 4 +The archive is a directory archive\&. +.RE +.PP +t +.br +tar +.RS 4 +The archive is a +\fBtar\fR +archive\&. +.RE +.RE +.PP +\fB\-I \fR\fB\fIindex\fR\fR +.br +\fB\-\-index=\fR\fB\fIindex\fR\fR +.RS 4 +Restore definition of named index only\&. Multiple indexes may be specified with multiple +\fB\-I\fR +switches\&. +.RE +.PP +\fB\-j \fR\fB\fInumber\-of\-jobs\fR\fR +.br +\fB\-\-jobs=\fR\fB\fInumber\-of\-jobs\fR\fR +.RS 4 +Run the most time\-consuming steps of +pg_restore +\(em those that load data, create indexes, or create constraints \(em concurrently, using up to +\fInumber\-of\-jobs\fR +concurrent sessions\&. This option can dramatically reduce the time to restore a large database to a server running on a multiprocessor machine\&. This option is ignored when emitting a script rather than connecting directly to a database server\&. +.sp +Each job is one process or one thread, depending on the operating system, and uses a separate connection to the server\&. +.sp +The optimal value for this option depends on the hardware setup of the server, of the client, and of the network\&. Factors include the number of CPU cores and the disk setup\&. A good place to start is the number of CPU cores on the server, but values larger than that can also lead to faster restore times in many cases\&. Of course, values that are too high will lead to decreased performance because of thrashing\&. +.sp +Only the custom and directory archive formats are supported with this option\&. The input must be a regular file or directory (not, for example, a pipe or standard input)\&. Also, multiple jobs cannot be used together with the option +\fB\-\-single\-transaction\fR\&. +.RE +.PP +\fB\-l\fR +.br +\fB\-\-list\fR +.RS 4 +List the table of contents of the archive\&. The output of this operation can be used as input to the +\fB\-L\fR +option\&. Note that if filtering switches such as +\fB\-n\fR +or +\fB\-t\fR +are used with +\fB\-l\fR, they will restrict the items listed\&. +.RE +.PP +\fB\-L \fR\fB\fIlist\-file\fR\fR +.br +\fB\-\-use\-list=\fR\fB\fIlist\-file\fR\fR +.RS 4 +Restore only those archive elements that are listed in +\fIlist\-file\fR, and restore them in the order they appear in the file\&. Note that if filtering switches such as +\fB\-n\fR +or +\fB\-t\fR +are used with +\fB\-L\fR, they will further restrict the items restored\&. +.sp +\fIlist\-file\fR +is normally created by editing the output of a previous +\fB\-l\fR +operation\&. Lines can be moved or removed, and can also be commented out by placing a semicolon (;) at the start of the line\&. See below for examples\&. +.RE +.PP +\fB\-n \fR\fB\fIschema\fR\fR +.br +\fB\-\-schema=\fR\fB\fIschema\fR\fR +.RS 4 +Restore only objects that are in the named schema\&. Multiple schemas may be specified with multiple +\fB\-n\fR +switches\&. This can be combined with the +\fB\-t\fR +option to restore just a specific table\&. +.RE +.PP +\fB\-N \fR\fB\fIschema\fR\fR +.br +\fB\-\-exclude\-schema=\fR\fB\fIschema\fR\fR +.RS 4 +Do not restore objects that are in the named schema\&. Multiple schemas to be excluded may be specified with multiple +\fB\-N\fR +switches\&. +.sp +When both +\fB\-n\fR +and +\fB\-N\fR +are given for the same schema name, the +\fB\-N\fR +switch wins and the schema is excluded\&. +.RE +.PP +\fB\-O\fR +.br +\fB\-\-no\-owner\fR +.RS 4 +Do not output commands to set ownership of objects to match the original database\&. By default, +pg_restore +issues +\fBALTER OWNER\fR +or +\fBSET SESSION AUTHORIZATION\fR +statements to set ownership of created schema elements\&. These statements will fail unless the initial connection to the database is made by a superuser (or the same user that owns all of the objects in the script)\&. With +\fB\-O\fR, any user name can be used for the initial connection, and this user will own all the created objects\&. +.RE +.PP +\fB\-P \fR\fB\fIfunction\-name(argtype [, \&.\&.\&.])\fR\fR +.br +\fB\-\-function=\fR\fB\fIfunction\-name(argtype [, \&.\&.\&.])\fR\fR +.RS 4 +Restore the named function only\&. Be careful to spell the function name and arguments exactly as they appear in the dump file\*(Aqs table of contents\&. Multiple functions may be specified with multiple +\fB\-P\fR +switches\&. +.RE +.PP +\fB\-R\fR +.br +\fB\-\-no\-reconnect\fR +.RS 4 +This option is obsolete but still accepted for backwards compatibility\&. +.RE +.PP +\fB\-s\fR +.br +\fB\-\-schema\-only\fR +.RS 4 +Restore only the schema (data definitions), not data, to the extent that schema entries are present in the archive\&. +.sp +This option is the inverse of +\fB\-\-data\-only\fR\&. It is similar to, but for historical reasons not identical to, specifying +\fB\-\-section=pre\-data \-\-section=post\-data\fR\&. +.sp +(Do not confuse this with the +\fB\-\-schema\fR +option, which uses the word +\(lqschema\(rq +in a different meaning\&.) +.RE +.PP +\fB\-S \fR\fB\fIusername\fR\fR +.br +\fB\-\-superuser=\fR\fB\fIusername\fR\fR +.RS 4 +Specify the superuser user name to use when disabling triggers\&. This is relevant only if +\fB\-\-disable\-triggers\fR +is used\&. +.RE +.PP +\fB\-t \fR\fB\fItable\fR\fR +.br +\fB\-\-table=\fR\fB\fItable\fR\fR +.RS 4 +Restore definition and/or data of only the named table\&. For this purpose, +\(lqtable\(rq +includes views, materialized views, sequences, and foreign tables\&. Multiple tables can be selected by writing multiple +\fB\-t\fR +switches\&. This option can be combined with the +\fB\-n\fR +option to specify table(s) in a particular schema\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +When +\fB\-t\fR +is specified, +pg_restore +makes no attempt to restore any other database objects that the selected table(s) might depend upon\&. Therefore, there is no guarantee that a specific\-table restore into a clean database will succeed\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This flag does not behave identically to the +\fB\-t\fR +flag of +pg_dump\&. There is not currently any provision for wild\-card matching in +pg_restore, nor can you include a schema name within its +\fB\-t\fR\&. And, while +pg_dump\*(Aqs +\fB\-t\fR +flag will also dump subsidiary objects (such as indexes) of the selected table(s), +pg_restore\*(Aqs +\fB\-t\fR +flag does not include such subsidiary objects\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +In versions prior to +PostgreSQL +9\&.6, this flag matched only tables, not any other type of relation\&. +.sp .5v +.RE +.RE +.PP +\fB\-T \fR\fB\fItrigger\fR\fR +.br +\fB\-\-trigger=\fR\fB\fItrigger\fR\fR +.RS 4 +Restore named trigger only\&. Multiple triggers may be specified with multiple +\fB\-T\fR +switches\&. +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Specifies verbose mode\&. This will cause +pg_restore +to output detailed object comments and start/stop times to the output file, and progress messages to standard error\&. Repeating the option causes additional debug\-level messages to appear on standard error\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_restore +version and exit\&. +.RE +.PP +\fB\-x\fR +.br +\fB\-\-no\-privileges\fR +.br +\fB\-\-no\-acl\fR +.RS 4 +Prevent restoration of access privileges (grant/revoke commands)\&. +.RE +.PP +\fB\-1\fR +.br +\fB\-\-single\-transaction\fR +.RS 4 +Execute the restore as a single transaction (that is, wrap the emitted commands in +\fBBEGIN\fR/\fBCOMMIT\fR)\&. This ensures that either all the commands complete successfully, or no changes are applied\&. This option implies +\fB\-\-exit\-on\-error\fR\&. +.RE +.PP +\fB\-\-disable\-triggers\fR +.RS 4 +This option is relevant only when performing a data\-only restore\&. It instructs +pg_restore +to execute commands to temporarily disable triggers on the target tables while the data is restored\&. Use this if you have referential integrity checks or other triggers on the tables that you do not want to invoke during data restore\&. +.sp +Presently, the commands emitted for +\fB\-\-disable\-triggers\fR +must be done as superuser\&. So you should also specify a superuser name with +\fB\-S\fR +or, preferably, run +pg_restore +as a +PostgreSQL +superuser\&. +.RE +.PP +\fB\-\-enable\-row\-security\fR +.RS 4 +This option is relevant only when restoring the contents of a table which has row security\&. By default, +pg_restore +will set +row_security +to off, to ensure that all data is restored in to the table\&. If the user does not have sufficient privileges to bypass row security, then an error is thrown\&. This parameter instructs +pg_restore +to set +row_security +to on instead, allowing the user to attempt to restore the contents of the table with row security enabled\&. This might still fail if the user does not have the right to insert the rows from the dump into the table\&. +.sp +Note that this option currently also requires the dump be in +\fBINSERT\fR +format, as +\fBCOPY FROM\fR +does not support row security\&. +.RE +.PP +\fB\-\-if\-exists\fR +.RS 4 +Use conditional commands (i\&.e\&., add an +IF EXISTS +clause) to drop database objects\&. This option is not valid unless +\fB\-\-clean\fR +is also specified\&. +.RE +.PP +\fB\-\-no\-comments\fR +.RS 4 +Do not output commands to restore comments, even if the archive contains them\&. +.RE +.PP +\fB\-\-no\-data\-for\-failed\-tables\fR +.RS 4 +By default, table data is restored even if the creation command for the table failed (e\&.g\&., because it already exists)\&. With this option, data for such a table is skipped\&. This behavior is useful if the target database already contains the desired table contents\&. For example, auxiliary tables for +PostgreSQL +extensions such as +PostGIS +might already be loaded in the target database; specifying this option prevents duplicate or obsolete data from being loaded into them\&. +.sp +This option is effective only when restoring directly into a database, not when producing SQL script output\&. +.RE +.PP +\fB\-\-no\-publications\fR +.RS 4 +Do not output commands to restore publications, even if the archive contains them\&. +.RE +.PP +\fB\-\-no\-security\-labels\fR +.RS 4 +Do not output commands to restore security labels, even if the archive contains them\&. +.RE +.PP +\fB\-\-no\-subscriptions\fR +.RS 4 +Do not output commands to restore subscriptions, even if the archive contains them\&. +.RE +.PP +\fB\-\-no\-table\-access\-method\fR +.RS 4 +Do not output commands to select table access methods\&. With this option, all objects will be created with whichever access method is the default during restore\&. +.RE +.PP +\fB\-\-no\-tablespaces\fR +.RS 4 +Do not output commands to select tablespaces\&. With this option, all objects will be created in whichever tablespace is the default during restore\&. +.RE +.PP +\fB\-\-section=\fR\fB\fIsectionname\fR\fR +.RS 4 +Only restore the named section\&. The section name can be +\fBpre\-data\fR, +\fBdata\fR, or +\fBpost\-data\fR\&. This option can be specified more than once to select multiple sections\&. The default is to restore all sections\&. +.sp +The data section contains actual table data as well as large\-object definitions\&. Post\-data items consist of definitions of indexes, triggers, rules and constraints other than validated check constraints\&. Pre\-data items consist of all other data definition items\&. +.RE +.PP +\fB\-\-strict\-names\fR +.RS 4 +Require that each schema (\fB\-n\fR/\fB\-\-schema\fR) and table (\fB\-t\fR/\fB\-\-table\fR) qualifier match at least one schema/table in the backup file\&. +.RE +.PP +\fB\-\-use\-set\-session\-authorization\fR +.RS 4 +Output SQL\-standard +\fBSET SESSION AUTHORIZATION\fR +commands instead of +\fBALTER OWNER\fR +commands to determine object ownership\&. This makes the dump more standards\-compatible, but depending on the history of the objects in the dump, might not restore properly\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_restore +command line arguments, and exit\&. +.RE +.PP +pg_restore +also accepts the following command line arguments for connection parameters: +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. The default is taken from the +\fBPGHOST\fR +environment variable, if set, else a Unix domain socket connection is attempted\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. Defaults to the +\fBPGPORT\fR +environment variable, if set, or a compiled\-in default\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +pg_restore +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +pg_restore +will automatically prompt for a password if the server demands password authentication\&. However, +pg_restore +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +\fB\-\-role=\fR\fB\fIrolename\fR\fR +.RS 4 +Specifies a role name to be used to perform the restore\&. This option causes +pg_restore +to issue a +\fBSET ROLE\fR +\fIrolename\fR +command after connecting to the database\&. It is useful when the authenticated user (specified by +\fB\-U\fR) lacks privileges needed by +pg_restore, but can switch to a role with the required rights\&. Some installations have a policy against logging in directly as a superuser, and use of this option allows restores to be performed without violating the policy\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGHOST\fR +.br +\fBPGOPTIONS\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. However, it does not read +\fBPGDATABASE\fR +when a database name is not supplied\&. +.SH "DIAGNOSTICS" +.PP +When a direct database connection is specified using the +\fB\-d\fR +option, +pg_restore +internally executes +SQL +statements\&. If you have problems running +pg_restore, make sure you are able to select information from the database using, for example, +\fBpsql\fR(1)\&. Also, any default connection settings and environment variables used by the +libpq +front\-end library will apply\&. +.SH "NOTES" +.PP +If your installation has any local additions to the +template1 +database, be careful to load the output of +pg_restore +into a truly empty database; otherwise you are likely to get errors due to duplicate definitions of the added objects\&. To make an empty database without any local additions, copy from +template0 +not +template1, for example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE DATABASE foo WITH TEMPLATE template0; +.fi +.if n \{\ +.RE +.\} +.PP +The limitations of +pg_restore +are detailed below\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +When restoring data to a pre\-existing table and the option +\fB\-\-disable\-triggers\fR +is used, +pg_restore +emits commands to disable triggers on user tables before inserting the data, then emits commands to re\-enable them after the data has been inserted\&. If the restore is stopped in the middle, the system catalogs might be left in the wrong state\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +pg_restore +cannot restore large objects selectively; for instance, only those for a specific table\&. If an archive contains large objects, then all large objects will be restored, or none of them if they are excluded via +\fB\-L\fR, +\fB\-t\fR, or other options\&. +.RE +.PP +See also the +\fBpg_dump\fR(1) +documentation for details on limitations of +pg_dump\&. +.PP +Once restored, it is wise to run +\fBANALYZE\fR +on each restored table so the optimizer has useful statistics; see +Section\ \&25.1.3 +and +Section\ \&25.1.6 +for more information\&. +.SH "EXAMPLES" +.PP +Assume we have dumped a database called +mydb +into a custom\-format dump file: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_dump \-Fc mydb > db\&.dump\fR +.fi +.if n \{\ +.RE +.\} +.PP +To drop the database and recreate it from the dump: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBdropdb mydb\fR +$ \fBpg_restore \-C \-d postgres db\&.dump\fR +.fi +.if n \{\ +.RE +.\} +.sp +The database named in the +\fB\-d\fR +switch can be any database existing in the cluster; +pg_restore +only uses it to issue the +\fBCREATE DATABASE\fR +command for +mydb\&. With +\fB\-C\fR, data is always restored into the database name that appears in the dump file\&. +.PP +To restore the dump into a new database called +newdb: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBcreatedb \-T template0 newdb\fR +$ \fBpg_restore \-d newdb db\&.dump\fR +.fi +.if n \{\ +.RE +.\} +.sp +Notice we don\*(Aqt use +\fB\-C\fR, and instead connect directly to the database to be restored into\&. Also note that we clone the new database from +template0 +not +template1, to ensure it is initially empty\&. +.PP +To reorder database items, it is first necessary to dump the table of contents of the archive: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_restore \-l db\&.dump > db\&.list\fR +.fi +.if n \{\ +.RE +.\} +.sp +The listing file consists of a header and one line for each item, e\&.g\&.: +.sp +.if n \{\ +.RS 4 +.\} +.nf +; +; Archive created at Mon Sep 14 13:55:39 2009 +; dbname: DBDEMOS +; TOC Entries: 81 +; Compression: 9 +; Dump Version: 1\&.10\-0 +; Format: CUSTOM +; Integer: 4 bytes +; Offset: 8 bytes +; Dumped from database version: 8\&.3\&.5 +; Dumped by pg_dump version: 8\&.3\&.8 +; +; +; Selected TOC Entries: +; +3; 2615 2200 SCHEMA \- public pasha +1861; 0 0 COMMENT \- SCHEMA public pasha +1862; 0 0 ACL \- public pasha +317; 1247 17715 TYPE public composite pasha +319; 1247 25899 DOMAIN public domain0 pasha +.fi +.if n \{\ +.RE +.\} +.sp +Semicolons start a comment, and the numbers at the start of lines refer to the internal archive ID assigned to each item\&. +.PP +Lines in the file can be commented out, deleted, and reordered\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +10; 145433 TABLE map_resolutions postgres +;2; 145344 TABLE species postgres +;4; 145359 TABLE nt_header postgres +6; 145402 TABLE species_records postgres +;8; 145416 TABLE ss_old postgres +.fi +.if n \{\ +.RE +.\} +.sp +could be used as input to +pg_restore +and would only restore items 10 and 6, in that order: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_restore \-L db\&.list db\&.dump\fR +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBpg_dump\fR(1), \fBpg_dumpall\fR(1), \fBpsql\fR(1) diff --git a/doc/src/sgml/man1/pg_rewind.1 b/doc/src/sgml/man1/pg_rewind.1 new file mode 100644 index 0000000..e3a0064 --- /dev/null +++ b/doc/src/sgml/man1/pg_rewind.1 @@ -0,0 +1,357 @@ +'\" t +.\" Title: pg_rewind +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_REWIND" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_rewind \- synchronize a PostgreSQL data directory with another data directory that was forked from it +.SH "SYNOPSIS" +.HP \w'\fBpg_rewind\fR\ 'u +\fBpg_rewind\fR [\fIoption\fR...] {\fB\-D\fR | \fB\-\-target\-pgdata\fR}\fI directory\fR {\fB\-\-source\-pgdata=\fR\fB\fIdirectory\fR\fR | \fB\-\-source\-server=\fR\fB\fIconnstr\fR\fR} +.SH "DESCRIPTION" +.PP +pg_rewind +is a tool for synchronizing a PostgreSQL cluster with another copy of the same cluster, after the clusters\*(Aq timelines have diverged\&. A typical scenario is to bring an old primary server back online after failover as a standby that follows the new primary\&. +.PP +After a successful rewind, the state of the target data directory is analogous to a base backup of the source data directory\&. Unlike taking a new base backup or using a tool like +rsync, +pg_rewind +does not require comparing or copying unchanged relation blocks in the cluster\&. Only changed blocks from existing relation files are copied; all other files, including new relation files, configuration files, and WAL segments, are copied in full\&. As such the rewind operation is significantly faster than other approaches when the database is large and only a small fraction of blocks differ between the clusters\&. +.PP +pg_rewind +examines the timeline histories of the source and target clusters to determine the point where they diverged, and expects to find WAL in the target cluster\*(Aqs +pg_wal +directory reaching all the way back to the point of divergence\&. The point of divergence can be found either on the target timeline, the source timeline, or their common ancestor\&. In the typical failover scenario where the target cluster was shut down soon after the divergence, this is not a problem, but if the target cluster ran for a long time after the divergence, its old WAL files might no longer be present\&. In this case, you can manually copy them from the WAL archive to the +pg_wal +directory, or run +pg_rewind +with the +\-c +option to automatically retrieve them from the WAL archive\&. The use of +pg_rewind +is not limited to failover, e\&.g\&., a standby server can be promoted, run some write transactions, and then rewound to become a standby again\&. +.PP +After running +pg_rewind, WAL replay needs to complete for the data directory to be in a consistent state\&. When the target server is started again it will enter archive recovery and replay all WAL generated in the source server from the last checkpoint before the point of divergence\&. If some of the WAL was no longer available in the source server when +pg_rewind +was run, and therefore could not be copied by the +pg_rewind +session, it must be made available when the target server is started\&. This can be done by creating a +recovery\&.signal +file in the target data directory and by configuring a suitable +restore_command +in +postgresql\&.conf\&. +.PP +pg_rewind +requires that the target server either has the +wal_log_hints +option enabled in +postgresql\&.conf +or data checksums enabled when the cluster was initialized with +initdb\&. Neither of these are currently on by default\&. +full_page_writes +must also be set to +on, but is enabled by default\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +.PP +If +pg_rewind +fails while processing, then the data folder of the target is likely not in a state that can be recovered\&. In such a case, taking a new fresh backup is recommended\&. +.PP +As +pg_rewind +copies configuration files entirely from the source, it may be required to correct the configuration used for recovery before restarting the target server, especially if the target is reintroduced as a standby of the source\&. If you restart the server after the rewind operation has finished but without configuring recovery, the target may again diverge from the primary\&. +.PP +pg_rewind +will fail immediately if it finds files it cannot write directly to\&. This can happen for example when the source and the target server use the same file mapping for read\-only SSL keys and certificates\&. If such files are present on the target server it is recommended to remove them before running +pg_rewind\&. After doing the rewind, some of those files may have been copied from the source, in which case it may be necessary to remove the data copied and restore back the set of links used before the rewind\&. +.sp .5v +.RE +.SH "OPTIONS" +.PP +pg_rewind +accepts the following command\-line arguments: +.PP +\fB\-D \fR\fB\fIdirectory\fR\fR +.br +\fB\-\-target\-pgdata=\fR\fB\fIdirectory\fR\fR +.RS 4 +This option specifies the target data directory that is synchronized with the source\&. The target server must be shut down cleanly before running +pg_rewind +.RE +.PP +\fB\-\-source\-pgdata=\fR\fB\fIdirectory\fR\fR +.RS 4 +Specifies the file system path to the data directory of the source server to synchronize the target with\&. This option requires the source server to be cleanly shut down\&. +.RE +.PP +\fB\-\-source\-server=\fR\fB\fIconnstr\fR\fR +.RS 4 +Specifies a libpq connection string to connect to the source +PostgreSQL +server to synchronize the target with\&. The connection must be a normal (non\-replication) connection with a role having sufficient permissions to execute the functions used by +pg_rewind +on the source server (see Notes section for details) or a superuser role\&. This option requires the source server to be running and accepting connections\&. +.RE +.PP +\fB\-R\fR +.br +\fB\-\-write\-recovery\-conf\fR +.RS 4 +Create +standby\&.signal +and append connection settings to +postgresql\&.auto\&.conf +in the output directory\&. +\-\-source\-server +is mandatory with this option\&. +.RE +.PP +\fB\-n\fR +.br +\fB\-\-dry\-run\fR +.RS 4 +Do everything except actually modifying the target directory\&. +.RE +.PP +\fB\-N\fR +.br +\fB\-\-no\-sync\fR +.RS 4 +By default, +\fBpg_rewind\fR +will wait for all files to be written safely to disk\&. This option causes +\fBpg_rewind\fR +to return without waiting, which is faster, but means that a subsequent operating system crash can leave the data directory corrupt\&. Generally, this option is useful for testing but should not be used on a production installation\&. +.RE +.PP +\fB\-P\fR +.br +\fB\-\-progress\fR +.RS 4 +Enables progress reporting\&. Turning this on will deliver an approximate progress report while copying data from the source cluster\&. +.RE +.PP +\fB\-c\fR +.br +\fB\-\-restore\-target\-wal\fR +.RS 4 +Use +\fIrestore_command\fR +defined in the target cluster configuration to retrieve WAL files from the WAL archive if these files are no longer available in the +pg_wal +directory\&. +.RE +.PP +\fB\-\-config\-file=\fR\fB\fIfilename\fR\fR +.RS 4 +Use the specified main server configuration file for the target cluster\&. This affects +pg_rewind +when it uses internally the +postgres +command for the rewind operation on this cluster (when retrieving +\fIrestore_command\fR +with the option +\fB\-c/\-\-restore\-target\-wal\fR +and when forcing a completion of crash recovery)\&. +.RE +.PP +\fB\-\-debug\fR +.RS 4 +Print verbose debugging output that is mostly useful for developers debugging +pg_rewind\&. +.RE +.PP +\fB\-\-no\-ensure\-shutdown\fR +.RS 4 +pg_rewind +requires that the target server is cleanly shut down before rewinding\&. By default, if the target server is not shut down cleanly, +pg_rewind +starts the target server in single\-user mode to complete crash recovery first, and stops it\&. By passing this option, +pg_rewind +skips this and errors out immediately if the server is not cleanly shut down\&. Users are expected to handle the situation themselves in that case\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Display version information, then exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help, then exit\&. +.RE +.SH "ENVIRONMENT" +.PP +When +\fB\-\-source\-server\fR +option is used, +pg_rewind +also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.PP +The environment variable +\fBPG_COLOR\fR +specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.SH "NOTES" +.PP +When executing +pg_rewind +using an online cluster as source, a role having sufficient permissions to execute the functions used by +pg_rewind +on the source cluster can be used instead of a superuser\&. Here is how to create such a role, named +rewind_user +here: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE USER rewind_user LOGIN; +GRANT EXECUTE ON function pg_catalog\&.pg_ls_dir(text, boolean, boolean) TO rewind_user; +GRANT EXECUTE ON function pg_catalog\&.pg_stat_file(text, boolean) TO rewind_user; +GRANT EXECUTE ON function pg_catalog\&.pg_read_binary_file(text) TO rewind_user; +GRANT EXECUTE ON function pg_catalog\&.pg_read_binary_file(text, bigint, bigint, boolean) TO rewind_user; +.fi +.if n \{\ +.RE +.\} +.PP +When executing +pg_rewind +using an online cluster as source which has been recently promoted, it is necessary to execute a +\fBCHECKPOINT\fR +after promotion such that its control file reflects up\-to\-date timeline information, which is used by +pg_rewind +to check if the target cluster can be rewound using the designated source cluster\&. +.SS "How It Works" +.PP +The basic idea is to copy all file system\-level changes from the source cluster to the target cluster: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +Scan the WAL log of the target cluster, starting from the last checkpoint before the point where the source cluster\*(Aqs timeline history forked off from the target cluster\&. For each WAL record, record each data block that was touched\&. This yields a list of all the data blocks that were changed in the target cluster, after the source cluster forked off\&. If some of the WAL files are no longer available, try re\-running +pg_rewind +with the +\fB\-c\fR +option to search for the missing files in the WAL archive\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +Copy all those changed blocks from the source cluster to the target cluster, either using direct file system access (\fB\-\-source\-pgdata\fR) or SQL (\fB\-\-source\-server\fR)\&. Relation files are now in a state equivalent to the moment of the last completed checkpoint prior to the point at which the WAL timelines of the source and target diverged plus the current state on the source of any blocks changed on the target after that divergence\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +Copy all other files, including new relation files, WAL segments, +pg_xact, and configuration files from the source cluster to the target cluster\&. Similarly to base backups, the contents of the directories +pg_dynshmem/, +pg_notify/, +pg_replslot/, +pg_serial/, +pg_snapshots/, +pg_stat_tmp/, and +pg_subtrans/ +are omitted from the data copied from the source cluster\&. The files +backup_label, +tablespace_map, +pg_internal\&.init, +postmaster\&.opts, and +postmaster\&.pid, as well as any file or directory beginning with +pgsql_tmp, are omitted\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +Create a +backup_label +file to begin WAL replay at the checkpoint created at failover and configure the +pg_control +file with a minimum consistency LSN defined as the result of +pg_current_wal_insert_lsn() +when rewinding from a live source or the last checkpoint LSN when rewinding from a stopped source\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +When starting the target, +PostgreSQL +replays all the required WAL, resulting in a data directory in a consistent state\&. +.RE diff --git a/doc/src/sgml/man1/pg_test_fsync.1 b/doc/src/sgml/man1/pg_test_fsync.1 new file mode 100644 index 0000000..f7984bb --- /dev/null +++ b/doc/src/sgml/man1/pg_test_fsync.1 @@ -0,0 +1,100 @@ +'\" t +.\" Title: pg_test_fsync +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_TEST_FSYNC" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_test_fsync \- determine fastest \fIwal_sync_method\fR for PostgreSQL +.SH "SYNOPSIS" +.HP \w'\fBpg_test_fsync\fR\ 'u +\fBpg_test_fsync\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +pg_test_fsync +is intended to give you a reasonable idea of what the fastest +wal_sync_method +is on your specific system, as well as supplying diagnostic information in the event of an identified I/O problem\&. However, differences shown by +pg_test_fsync +might not make any significant difference in real database throughput, especially since many database servers are not speed\-limited by their write\-ahead logs\&. +pg_test_fsync +reports average file sync operation time in microseconds for each +wal_sync_method, which can also be used to inform efforts to optimize the value of +commit_delay\&. +.SH "OPTIONS" +.PP +pg_test_fsync +accepts the following command\-line options: +.PP +\fB\-f\fR +.br +\fB\-\-filename\fR +.RS 4 +Specifies the file name to write test data in\&. This file should be in the same file system that the +pg_wal +directory is or will be placed in\&. (pg_wal +contains the +WAL +files\&.) The default is +pg_test_fsync\&.out +in the current directory\&. +.RE +.PP +\fB\-s\fR +.br +\fB\-\-secs\-per\-test\fR +.RS 4 +Specifies the number of seconds for each test\&. The more time per test, the greater the test\*(Aqs accuracy, but the longer it takes to run\&. The default is 5 seconds, which allows the program to complete in under 2 minutes\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_test_fsync +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_test_fsync +command line arguments, and exit\&. +.RE +.SH "ENVIRONMENT" +.PP +The environment variable +\fBPG_COLOR\fR +specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.SH "SEE ALSO" +\fBpostgres\fR(1) diff --git a/doc/src/sgml/man1/pg_test_timing.1 b/doc/src/sgml/man1/pg_test_timing.1 new file mode 100644 index 0000000..40c3bd9 --- /dev/null +++ b/doc/src/sgml/man1/pg_test_timing.1 @@ -0,0 +1,208 @@ +'\" t +.\" Title: pg_test_timing +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_TEST_TIMING" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_test_timing \- measure timing overhead +.SH "SYNOPSIS" +.HP \w'\fBpg_test_timing\fR\ 'u +\fBpg_test_timing\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +pg_test_timing +is a tool to measure the timing overhead on your system and confirm that the system time never moves backwards\&. Systems that are slow to collect timing data can give less accurate +\fBEXPLAIN ANALYZE\fR +results\&. +.SH "OPTIONS" +.PP +pg_test_timing +accepts the following command\-line options: +.PP +\fB\-d \fR\fB\fIduration\fR\fR +.br +\fB\-\-duration=\fR\fB\fIduration\fR\fR +.RS 4 +Specifies the test duration, in seconds\&. Longer durations give slightly better accuracy, and are more likely to discover problems with the system clock moving backwards\&. The default test duration is 3 seconds\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_test_timing +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_test_timing +command line arguments, and exit\&. +.RE +.SH "USAGE" +.SS "Interpreting Results" +.PP +Good results will show most (>90%) individual timing calls take less than one microsecond\&. Average per loop overhead will be even lower, below 100 nanoseconds\&. This example from an Intel i7\-860 system using a TSC clock source shows excellent performance: +.sp +.if n \{\ +.RS 4 +.\} +.nf +Testing timing overhead for 3 seconds\&. +Per loop time including overhead: 35\&.96 ns +Histogram of timing durations: + < us % of total count + 1 96\&.40465 80435604 + 2 3\&.59518 2999652 + 4 0\&.00015 126 + 8 0\&.00002 13 + 16 0\&.00000 2 +.fi +.if n \{\ +.RE +.\} +.PP +Note that different units are used for the per loop time than the histogram\&. The loop can have resolution within a few nanoseconds (ns), while the individual timing calls can only resolve down to one microsecond (us)\&. +.SS "Measuring Executor Timing Overhead" +.PP +When the query executor is running a statement using +\fBEXPLAIN ANALYZE\fR, individual operations are timed as well as showing a summary\&. The overhead of your system can be checked by counting rows with the +psql +program: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE t AS SELECT * FROM generate_series(1,100000); +\etiming +SELECT COUNT(*) FROM t; +EXPLAIN ANALYZE SELECT COUNT(*) FROM t; +.fi +.if n \{\ +.RE +.\} +.PP +The i7\-860 system measured runs the count query in 9\&.8 ms while the +\fBEXPLAIN ANALYZE\fR +version takes 16\&.6 ms, each processing just over 100,000 rows\&. That 6\&.8 ms difference means the timing overhead per row is 68 ns, about twice what pg_test_timing estimated it would be\&. Even that relatively small amount of overhead is making the fully timed count statement take almost 70% longer\&. On more substantial queries, the timing overhead would be less problematic\&. +.SS "Changing Time Sources" +.PP +On some newer Linux systems, it\*(Aqs possible to change the clock source used to collect timing data at any time\&. A second example shows the slowdown possible from switching to the slower acpi_pm time source, on the same system used for the fast results above: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# cat /sys/devices/system/clocksource/clocksource0/available_clocksource +tsc hpet acpi_pm +# echo acpi_pm > /sys/devices/system/clocksource/clocksource0/current_clocksource +# pg_test_timing +Per loop time including overhead: 722\&.92 ns +Histogram of timing durations: + < us % of total count + 1 27\&.84870 1155682 + 2 72\&.05956 2990371 + 4 0\&.07810 3241 + 8 0\&.01357 563 + 16 0\&.00007 3 +.fi +.if n \{\ +.RE +.\} +.PP +In this configuration, the sample +\fBEXPLAIN ANALYZE\fR +above takes 115\&.9 ms\&. That\*(Aqs 1061 ns of timing overhead, again a small multiple of what\*(Aqs measured directly by this utility\&. That much timing overhead means the actual query itself is only taking a tiny fraction of the accounted for time, most of it is being consumed in overhead instead\&. In this configuration, any +\fBEXPLAIN ANALYZE\fR +totals involving many timed operations would be inflated significantly by timing overhead\&. +.PP +FreeBSD also allows changing the time source on the fly, and it logs information about the timer selected during boot: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# dmesg | grep "Timecounter" +Timecounter "ACPI\-fast" frequency 3579545 Hz quality 900 +Timecounter "i8254" frequency 1193182 Hz quality 0 +Timecounters tick every 10\&.000 msec +Timecounter "TSC" frequency 2531787134 Hz quality 800 +# sysctl kern\&.timecounter\&.hardware=TSC +kern\&.timecounter\&.hardware: ACPI\-fast \-> TSC +.fi +.if n \{\ +.RE +.\} +.PP +Other systems may only allow setting the time source on boot\&. On older Linux systems the "clock" kernel setting is the only way to make this sort of change\&. And even on some more recent ones, the only option you\*(Aqll see for a clock source is "jiffies"\&. Jiffies are the older Linux software clock implementation, which can have good resolution when it\*(Aqs backed by fast enough timing hardware, as in this example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ cat /sys/devices/system/clocksource/clocksource0/available_clocksource +jiffies +$ dmesg | grep time\&.c +time\&.c: Using 3\&.579545 MHz WALL PM GTOD PIT/TSC timer\&. +time\&.c: Detected 2400\&.153 MHz processor\&. +$ pg_test_timing +Testing timing overhead for 3 seconds\&. +Per timing duration including loop overhead: 97\&.75 ns +Histogram of timing durations: + < us % of total count + 1 90\&.23734 27694571 + 2 9\&.75277 2993204 + 4 0\&.00981 3010 + 8 0\&.00007 22 + 16 0\&.00000 1 + 32 0\&.00000 1 +.fi +.if n \{\ +.RE +.\} +.SS "Clock Hardware and Timing Accuracy" +.PP +Collecting accurate timing information is normally done on computers using hardware clocks with various levels of accuracy\&. With some hardware the operating systems can pass the system clock time almost directly to programs\&. A system clock can also be derived from a chip that simply provides timing interrupts, periodic ticks at some known time interval\&. In either case, operating system kernels provide a clock source that hides these details\&. But the accuracy of that clock source and how quickly it can return results varies based on the underlying hardware\&. +.PP +Inaccurate time keeping can result in system instability\&. Test any change to the clock source very carefully\&. Operating system defaults are sometimes made to favor reliability over best accuracy\&. And if you are using a virtual machine, look into the recommended time sources compatible with it\&. Virtual hardware faces additional difficulties when emulating timers, and there are often per operating system settings suggested by vendors\&. +.PP +The Time Stamp Counter (TSC) clock source is the most accurate one available on current generation CPUs\&. It\*(Aqs the preferred way to track the system time when it\*(Aqs supported by the operating system and the TSC clock is reliable\&. There are several ways that TSC can fail to provide an accurate timing source, making it unreliable\&. Older systems can have a TSC clock that varies based on the CPU temperature, making it unusable for timing\&. Trying to use TSC on some older multicore CPUs can give a reported time that\*(Aqs inconsistent among multiple cores\&. This can result in the time going backwards, a problem this program checks for\&. And even the newest systems can fail to provide accurate TSC timing with very aggressive power saving configurations\&. +.PP +Newer operating systems may check for the known TSC problems and switch to a slower, more stable clock source when they are seen\&. If your system supports TSC time but doesn\*(Aqt default to that, it may be disabled for a good reason\&. And some operating systems may not detect all the possible problems correctly, or will allow using TSC even in situations where it\*(Aqs known to be inaccurate\&. +.PP +The High Precision Event Timer (HPET) is the preferred timer on systems where it\*(Aqs available and TSC is not accurate\&. The timer chip itself is programmable to allow up to 100 nanosecond resolution, but you may not see that much accuracy in your system clock\&. +.PP +Advanced Configuration and Power Interface (ACPI) provides a Power Management (PM) Timer, which Linux refers to as the acpi_pm\&. The clock derived from acpi_pm will at best provide 300 nanosecond resolution\&. +.PP +Timers used on older PC hardware include the 8254 Programmable Interval Timer (PIT), the real\-time clock (RTC), the Advanced Programmable Interrupt Controller (APIC) timer, and the Cyclone timer\&. These timers aim for millisecond resolution\&. +.SH "SEE ALSO" +\fBEXPLAIN\fR(7) diff --git a/doc/src/sgml/man1/pg_upgrade.1 b/doc/src/sgml/man1/pg_upgrade.1 new file mode 100644 index 0000000..1e80231 --- /dev/null +++ b/doc/src/sgml/man1/pg_upgrade.1 @@ -0,0 +1,944 @@ +'\" t +.\" Title: pg_upgrade +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_UPGRADE" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_upgrade \- upgrade a PostgreSQL server instance +.SH "SYNOPSIS" +.HP \w'\fBpg_upgrade\fR\ 'u +\fBpg_upgrade\fR \fB\-b\fR \fIoldbindir\fR [\fB\-B\fR\ \fInewbindir\fR] \fB\-d\fR \fIoldconfigdir\fR \fB\-D\fR \fInewconfigdir\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +pg_upgrade +(formerly called +pg_migrator) allows data stored in +PostgreSQL +data files to be upgraded to a later +PostgreSQL +major version without the data dump/restore typically required for major version upgrades, e\&.g\&., from 9\&.5\&.8 to 9\&.6\&.4 or from 10\&.7 to 11\&.2\&. It is not required for minor version upgrades, e\&.g\&., from 9\&.6\&.2 to 9\&.6\&.3 or from 10\&.1 to 10\&.2\&. +.PP +Major PostgreSQL releases regularly add new features that often change the layout of the system tables, but the internal data storage format rarely changes\&. +pg_upgrade +uses this fact to perform rapid upgrades by creating new system tables and simply reusing the old user data files\&. If a future major release ever changes the data storage format in a way that makes the old data format unreadable, +pg_upgrade +will not be usable for such upgrades\&. (The community will attempt to avoid such situations\&.) +.PP +pg_upgrade +does its best to make sure the old and new clusters are binary\-compatible, e\&.g\&., by checking for compatible compile\-time settings, including 32/64\-bit binaries\&. It is important that any external modules are also binary compatible, though this cannot be checked by +pg_upgrade\&. +.PP +pg_upgrade supports upgrades from 9\&.2\&.X and later to the current major release of +PostgreSQL, including snapshot and beta releases\&. +.SH "OPTIONS" +.PP +pg_upgrade +accepts the following command\-line arguments: +.PP +\fB\-b\fR \fIbindir\fR +.br +\fB\-\-old\-bindir=\fR\fIbindir\fR +.RS 4 +the old PostgreSQL executable directory; environment variable +\fBPGBINOLD\fR +.RE +.PP +\fB\-B\fR \fIbindir\fR +.br +\fB\-\-new\-bindir=\fR\fIbindir\fR +.RS 4 +the new PostgreSQL executable directory; default is the directory where +pg_upgrade +resides; environment variable +\fBPGBINNEW\fR +.RE +.PP +\fB\-c\fR +.br +\fB\-\-check\fR +.RS 4 +check clusters only, don\*(Aqt change any data +.RE +.PP +\fB\-d\fR \fIconfigdir\fR +.br +\fB\-\-old\-datadir=\fR\fIconfigdir\fR +.RS 4 +the old database cluster configuration directory; environment variable +\fBPGDATAOLD\fR +.RE +.PP +\fB\-D\fR \fIconfigdir\fR +.br +\fB\-\-new\-datadir=\fR\fIconfigdir\fR +.RS 4 +the new database cluster configuration directory; environment variable +\fBPGDATANEW\fR +.RE +.PP +\fB\-j \fR\fB\fInjobs\fR\fR +.br +\fB\-\-jobs=\fR\fB\fInjobs\fR\fR +.RS 4 +number of simultaneous processes or threads to use +.RE +.PP +\fB\-k\fR +.br +\fB\-\-link\fR +.RS 4 +use hard links instead of copying files to the new cluster +.RE +.PP +\fB\-N\fR +.br +\fB\-\-no\-sync\fR +.RS 4 +By default, +\fBpg_upgrade\fR +will wait for all files of the upgraded cluster to be written safely to disk\&. This option causes +\fBpg_upgrade\fR +to return without waiting, which is faster, but means that a subsequent operating system crash can leave the data directory corrupt\&. Generally, this option is useful for testing but should not be used on a production installation\&. +.RE +.PP +\fB\-o\fR \fIoptions\fR +.br +\fB\-\-old\-options\fR \fIoptions\fR +.RS 4 +options to be passed directly to the old +\fBpostgres\fR +command; multiple option invocations are appended +.RE +.PP +\fB\-O\fR \fIoptions\fR +.br +\fB\-\-new\-options\fR \fIoptions\fR +.RS 4 +options to be passed directly to the new +\fBpostgres\fR +command; multiple option invocations are appended +.RE +.PP +\fB\-p\fR \fIport\fR +.br +\fB\-\-old\-port=\fR\fIport\fR +.RS 4 +the old cluster port number; environment variable +\fBPGPORTOLD\fR +.RE +.PP +\fB\-P\fR \fIport\fR +.br +\fB\-\-new\-port=\fR\fIport\fR +.RS 4 +the new cluster port number; environment variable +\fBPGPORTNEW\fR +.RE +.PP +\fB\-r\fR +.br +\fB\-\-retain\fR +.RS 4 +retain SQL and log files even after successful completion +.RE +.PP +\fB\-s\fR \fIdir\fR +.br +\fB\-\-socketdir=\fR\fIdir\fR +.RS 4 +directory to use for postmaster sockets during upgrade; default is current working directory; environment variable +\fBPGSOCKETDIR\fR +.RE +.PP +\fB\-U\fR \fIusername\fR +.br +\fB\-\-username=\fR\fIusername\fR +.RS 4 +cluster\*(Aqs install user name; environment variable +\fBPGUSER\fR +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +enable verbose internal logging +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +display version information, then exit +.RE +.PP +\fB\-\-clone\fR +.RS 4 +Use efficient file cloning (also known as +\(lqreflinks\(rq +on some systems) instead of copying files to the new cluster\&. This can result in near\-instantaneous copying of the data files, giving the speed advantages of +\fB\-k\fR/\fB\-\-link\fR +while leaving the old cluster untouched\&. +.sp +File cloning is only supported on some operating systems and file systems\&. If it is selected but not supported, the +pg_upgrade +run will error\&. At present, it is supported on Linux (kernel 4\&.5 or later) with Btrfs and XFS (on file systems created with reflink support), and on macOS with APFS\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +show help, then exit +.RE +.SH "USAGE" +.PP +These are the steps to perform an upgrade with +pg_upgrade: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +Optionally move the old cluster: If you are using a version\-specific installation directory, e\&.g\&., +/opt/PostgreSQL/15, you do not need to move the old cluster\&. The graphical installers all use version\-specific installation directories\&. +.sp +If your installation directory is not version\-specific, e\&.g\&., +/usr/local/pgsql, it is necessary to move the current PostgreSQL install directory so it does not interfere with the new +PostgreSQL +installation\&. Once the current +PostgreSQL +server is shut down, it is safe to rename the PostgreSQL installation directory; assuming the old directory is +/usr/local/pgsql, you can do: +.sp +.if n \{\ +.RS 4 +.\} +.nf +mv /usr/local/pgsql /usr/local/pgsql\&.old +.fi +.if n \{\ +.RE +.\} +.sp +to rename the directory\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +For source installs, build the new version: Build the new PostgreSQL source with +\fBconfigure\fR +flags that are compatible with the old cluster\&. +pg_upgrade +will check +\fBpg_controldata\fR +to make sure all settings are compatible before starting the upgrade\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +Install the new PostgreSQL binaries: Install the new server\*(Aqs binaries and support files\&. +pg_upgrade +is included in a default installation\&. +.sp +For source installs, if you wish to install the new server in a custom location, use the +prefix +variable: +.sp +.if n \{\ +.RS 4 +.\} +.nf +make prefix=/usr/local/pgsql\&.new install +.fi +.if n \{\ +.RE +.\} +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +Initialize the new PostgreSQL cluster: Initialize the new cluster using +\fBinitdb\fR\&. Again, use compatible +\fBinitdb\fR +flags that match the old cluster\&. Many prebuilt installers do this step automatically\&. There is no need to start the new cluster\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +Install extension shared object files: Many extensions and custom modules, whether from +contrib +or another source, use shared object files (or DLLs), e\&.g\&., +pgcrypto\&.so\&. If the old cluster used these, shared object files matching the new server binary must be installed in the new cluster, usually via operating system commands\&. Do not load the schema definitions, e\&.g\&., +\fBCREATE EXTENSION pgcrypto\fR, because these will be duplicated from the old cluster\&. If extension updates are available, +pg_upgrade +will report this and create a script that can be run later to update them\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 6." 4.2 +.\} +Copy custom full\-text search files: Copy any custom full text search files (dictionary, synonym, thesaurus, stop words) from the old to the new cluster\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 7." 4.2 +.\} +Adjust authentication: \fBpg_upgrade\fR +will connect to the old and new servers several times, so you might want to set authentication to +peer +in +pg_hba\&.conf +or use a +~/\&.pgpass +file (see +Section\ \&34.16)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 8.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 8." 4.2 +.\} +Stop both servers: Make sure both database servers are stopped using, on Unix, e\&.g\&.: +.sp +.if n \{\ +.RS 4 +.\} +.nf +pg_ctl \-D /opt/PostgreSQL/9\&.6 stop +pg_ctl \-D /opt/PostgreSQL/15 stop +.fi +.if n \{\ +.RE +.\} +.sp +or on Windows, using the proper service names: +.sp +.if n \{\ +.RS 4 +.\} +.nf +NET STOP postgresql\-9\&.6 +NET STOP postgresql\-15 +.fi +.if n \{\ +.RE +.\} +.sp +Streaming replication and log\-shipping standby servers can remain running until a later step\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 9.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 9." 4.2 +.\} +Prepare for standby server upgrades: If you are upgrading standby servers using methods outlined in section +Step 11, verify that the old standby servers are caught up by running +pg_controldata +against the old primary and standby clusters\&. Verify that the +\(lqLatest checkpoint location\(rq +values match in all clusters\&. (There will be a mismatch if old standby servers were shut down before the old primary or if the old standby servers are still running\&.) Also, make sure +\fIwal_level\fR +is not set to +minimal +in the +postgresql\&.conf +file on the new primary cluster\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 10.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 10." 4.2 +.\} +Run pg_upgrade: Always run the +pg_upgrade +binary of the new server, not the old one\&. +pg_upgrade +requires the specification of the old and new cluster\*(Aqs data and executable (bin) directories\&. You can also specify user and port values, and whether you want the data files linked or cloned instead of the default copy behavior\&. +.sp +If you use link mode, the upgrade will be much faster (no file copying) and use less disk space, but you will not be able to access your old cluster once you start the new cluster after the upgrade\&. Link mode also requires that the old and new cluster data directories be in the same file system\&. (Tablespaces and +pg_wal +can be on different file systems\&.) Clone mode provides the same speed and disk space advantages but does not cause the old cluster to be unusable once the new cluster is started\&. Clone mode also requires that the old and new data directories be in the same file system\&. This mode is only available on certain operating systems and file systems\&. +.sp +The +\fB\-\-jobs\fR +option allows multiple CPU cores to be used for copying/linking of files and to dump and restore database schemas in parallel; a good place to start is the maximum of the number of CPU cores and tablespaces\&. This option can dramatically reduce the time to upgrade a multi\-database server running on a multiprocessor machine\&. +.sp +For Windows users, you must be logged into an administrative account, and then start a shell as the +postgres +user and set the proper path: +.sp +.if n \{\ +.RS 4 +.\} +.nf +RUNAS /USER:postgres "CMD\&.EXE" +SET PATH=%PATH%;C:\eProgram Files\ePostgreSQL\e15\ebin; +.fi +.if n \{\ +.RE +.\} +.sp +and then run +pg_upgrade +with quoted directories, e\&.g\&.: +.sp +.if n \{\ +.RS 4 +.\} +.nf +pg_upgrade\&.exe + \-\-old\-datadir "C:/Program Files/PostgreSQL/9\&.6/data" + \-\-new\-datadir "C:/Program Files/PostgreSQL/15/data" + \-\-old\-bindir "C:/Program Files/PostgreSQL/9\&.6/bin" + \-\-new\-bindir "C:/Program Files/PostgreSQL/15/bin" +.fi +.if n \{\ +.RE +.\} +.sp +Once started, +\fBpg_upgrade\fR +will verify the two clusters are compatible and then do the upgrade\&. You can use +\fBpg_upgrade \-\-check\fR +to perform only the checks, even if the old server is still running\&. +\fBpg_upgrade \-\-check\fR +will also outline any manual adjustments you will need to make after the upgrade\&. If you are going to be using link or clone mode, you should use the option +\fB\-\-link\fR +or +\fB\-\-clone\fR +with +\fB\-\-check\fR +to enable mode\-specific checks\&. +\fBpg_upgrade\fR +requires write permission in the current directory\&. +.sp +Obviously, no one should be accessing the clusters during the upgrade\&. +pg_upgrade +defaults to running servers on port 50432 to avoid unintended client connections\&. You can use the same port number for both clusters when doing an upgrade because the old and new clusters will not be running at the same time\&. However, when checking an old running server, the old and new port numbers must be different\&. +.sp +If an error occurs while restoring the database schema, +\fBpg_upgrade\fR +will exit and you will have to revert to the old cluster as outlined in +Step 17 +below\&. To try +\fBpg_upgrade\fR +again, you will need to modify the old cluster so the pg_upgrade schema restore succeeds\&. If the problem is a +contrib +module, you might need to uninstall the +contrib +module from the old cluster and install it in the new cluster after the upgrade, assuming the module is not being used to store user data\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 11.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 11." 4.2 +.\} +Upgrade streaming replication and log\-shipping standby servers: If you used link mode and have Streaming Replication (see +Section\ \&27.2.5) or Log\-Shipping (see +Section\ \&27.2) standby servers, you can follow these steps to quickly upgrade them\&. You will not be running +pg_upgrade +on the standby servers, but rather +rsync +on the primary\&. Do not start any servers yet\&. +.sp +If you did +\fInot\fR +use link mode, do not have or do not want to use +rsync, or want an easier solution, skip the instructions in this section and simply recreate the standby servers once +pg_upgrade +completes and the new primary is running\&. +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +Install the new PostgreSQL binaries on standby servers: Make sure the new binaries and support files are installed on all standby servers\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +Make sure the new standby data directories do \fInot\fR exist: Make sure the new standby data directories do +\fInot\fR +exist or are empty\&. If +initdb +was run, delete the standby servers\*(Aq new data directories\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +Install extension shared object files: Install the same extension shared object files on the new standbys that you installed in the new primary cluster\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +Stop standby servers: If the standby servers are still running, stop them now using the above instructions\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +Save configuration files: Save any configuration files from the old standbys\*(Aq configuration directories you need to keep, e\&.g\&., +postgresql\&.conf +(and any files included by it), +postgresql\&.auto\&.conf, +pg_hba\&.conf, because these will be overwritten or removed in the next step\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 6." 4.2 +.\} +Run rsync: When using link mode, standby servers can be quickly upgraded using +rsync\&. To accomplish this, from a directory on the primary server that is above the old and new database cluster directories, run this on the +\fIprimary\fR +for each standby server: +.sp +.if n \{\ +.RS 4 +.\} +.nf +rsync \-\-archive \-\-delete \-\-hard\-links \-\-size\-only \-\-no\-inc\-recursive old_cluster new_cluster remote_dir +.fi +.if n \{\ +.RE +.\} +.sp +where +\fBold_cluster\fR +and +\fBnew_cluster\fR +are relative to the current directory on the primary, and +\fBremote_dir\fR +is +\fIabove\fR +the old and new cluster directories on the standby\&. The directory structure under the specified directories on the primary and standbys must match\&. Consult the +rsync +manual page for details on specifying the remote directory, e\&.g\&., +.sp +.if n \{\ +.RS 4 +.\} +.nf +rsync \-\-archive \-\-delete \-\-hard\-links \-\-size\-only \-\-no\-inc\-recursive /opt/PostgreSQL/9\&.5 \e + /opt/PostgreSQL/9\&.6 standby\&.example\&.com:/opt/PostgreSQL +.fi +.if n \{\ +.RE +.\} +.sp +You can verify what the command will do using +rsync\*(Aqs +\fB\-\-dry\-run\fR +option\&. While +rsync +must be run on the primary for at least one standby, it is possible to run +rsync +on an upgraded standby to upgrade other standbys, as long as the upgraded standby has not been started\&. +.sp +What this does is to record the links created by +pg_upgrade\*(Aqs link mode that connect files in the old and new clusters on the primary server\&. It then finds matching files in the standby\*(Aqs old cluster and creates links for them in the standby\*(Aqs new cluster\&. Files that were not linked on the primary are copied from the primary to the standby\&. (They are usually small\&.) This provides rapid standby upgrades\&. Unfortunately, +rsync +needlessly copies files associated with temporary and unlogged tables because these files don\*(Aqt normally exist on standby servers\&. +.sp +If you have tablespaces, you will need to run a similar +rsync +command for each tablespace directory, e\&.g\&.: +.sp +.if n \{\ +.RS 4 +.\} +.nf +rsync \-\-archive \-\-delete \-\-hard\-links \-\-size\-only \-\-no\-inc\-recursive /vol1/pg_tblsp/PG_9\&.5_201510051 \e + /vol1/pg_tblsp/PG_9\&.6_201608131 standby\&.example\&.com:/vol1/pg_tblsp +.fi +.if n \{\ +.RE +.\} +.sp +If you have relocated +pg_wal +outside the data directories, +rsync +must be run on those directories too\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 7." 4.2 +.\} +Configure streaming replication and log\-shipping standby servers: Configure the servers for log shipping\&. (You do not need to run +\fBpg_backup_start()\fR +and +\fBpg_backup_stop()\fR +or take a file system backup as the standbys are still synchronized with the primary\&.) Replication slots are not copied and must be recreated\&. +.RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 12.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 12." 4.2 +.\} +Restore pg_hba\&.conf: If you modified +pg_hba\&.conf, restore its original settings\&. It might also be necessary to adjust other configuration files in the new cluster to match the old cluster, e\&.g\&., +postgresql\&.conf +(and any files included by it), +postgresql\&.auto\&.conf\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 13.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 13." 4.2 +.\} +Start the new server: The new server can now be safely started, and then any +rsync\*(Aqed standby servers\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 14.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 14." 4.2 +.\} +Post\-upgrade processing: If any post\-upgrade processing is required, pg_upgrade will issue warnings as it completes\&. It will also generate script files that must be run by the administrator\&. The script files will connect to each database that needs post\-upgrade processing\&. Each script should be run using: +.sp +.if n \{\ +.RS 4 +.\} +.nf +psql \-\-username=postgres \-\-file=script\&.sql postgres +.fi +.if n \{\ +.RE +.\} +.sp +The scripts can be run in any order and can be deleted once they have been run\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +In general it is unsafe to access tables referenced in rebuild scripts until the rebuild scripts have run to completion; doing so could yield incorrect results or poor performance\&. Tables not referenced in rebuild scripts can be accessed immediately\&. +.sp .5v +.RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 15.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 15." 4.2 +.\} +Statistics: Because optimizer statistics are not transferred by +\fBpg_upgrade\fR, you will be instructed to run a command to regenerate that information at the end of the upgrade\&. You might need to set connection parameters to match your new cluster\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 16.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 16." 4.2 +.\} +Delete old cluster: Once you are satisfied with the upgrade, you can delete the old cluster\*(Aqs data directories by running the script mentioned when +\fBpg_upgrade\fR +completes\&. (Automatic deletion is not possible if you have user\-defined tablespaces inside the old data directory\&.) You can also delete the old installation directories (e\&.g\&., +bin, +share)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 17.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 17." 4.2 +.\} +Reverting to old cluster: If, after running +\fBpg_upgrade\fR, you wish to revert to the old cluster, there are several options: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If the +\fB\-\-check\fR +option was used, the old cluster was unmodified; it can be restarted\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If the +\fB\-\-link\fR +option was +\fInot\fR +used, the old cluster was unmodified; it can be restarted\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If the +\fB\-\-link\fR +option was used, the data files might be shared between the old and new cluster: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If +\fBpg_upgrade\fR +aborted before linking started, the old cluster was unmodified; it can be restarted\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If you did +\fInot\fR +start the new cluster, the old cluster was unmodified except that, when linking started, a +\&.old +suffix was appended to +$PGDATA/global/pg_control\&. To reuse the old cluster, remove the +\&.old +suffix from +$PGDATA/global/pg_control; you can then restart the old cluster\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If you did start the new cluster, it has written to shared files and it is unsafe to use the old cluster\&. The old cluster will need to be restored from backup in this case\&. +.RE +.RE +.RE +.SH "NOTES" +.PP +pg_upgrade +creates various working files, such as schema dumps, stored within +pg_upgrade_output\&.d +in the directory of the new cluster\&. Each run creates a new subdirectory named with a timestamp formatted as per ISO 8601 (%Y%m%dT%H%M%S), where all its generated files are stored\&. +pg_upgrade_output\&.d +and its contained files will be removed automatically if +pg_upgrade +completes successfully; but in the event of trouble, the files there may provide useful debugging information\&. +.PP +pg_upgrade +launches short\-lived postmasters in the old and new data directories\&. Temporary Unix socket files for communication with these postmasters are, by default, made in the current working directory\&. In some situations the path name for the current directory might be too long to be a valid socket name\&. In that case you can use the +\fB\-s\fR +option to put the socket files in some directory with a shorter path name\&. For security, be sure that that directory is not readable or writable by any other users\&. (This is not supported on Windows\&.) +.PP +All failure, rebuild, and reindex cases will be reported by +pg_upgrade +if they affect your installation; post\-upgrade scripts to rebuild tables and indexes will be generated automatically\&. If you are trying to automate the upgrade of many clusters, you should find that clusters with identical database schemas require the same post\-upgrade steps for all cluster upgrades; this is because the post\-upgrade steps are based on the database schemas, and not user data\&. +.PP +For deployment testing, create a schema\-only copy of the old cluster, insert dummy data, and upgrade that\&. +.PP +pg_upgrade +does not support upgrading of databases containing table columns using these +reg* +OID\-referencing system data types: +.RS 4 +regcollation +.RE +.RS 4 +regconfig +.RE +.RS 4 +regdictionary +.RE +.RS 4 +regnamespace +.RE +.RS 4 +regoper +.RE +.RS 4 +regoperator +.RE +.RS 4 +regproc +.RE +.RS 4 +regprocedure +.RE +(regclass, +regrole, and +regtype +can be upgraded\&.) +.PP +If you want to use link mode and you do not want your old cluster to be modified when the new cluster is started, consider using the clone mode\&. If that is not available, make a copy of the old cluster and upgrade that in link mode\&. To make a valid copy of the old cluster, use +\fBrsync\fR +to create a dirty copy of the old cluster while the server is running, then shut down the old server and run +\fBrsync \-\-checksum\fR +again to update the copy with any changes to make it consistent\&. (\fB\-\-checksum\fR +is necessary because +\fBrsync\fR +only has file modification\-time granularity of one second\&.) You might want to exclude some files, e\&.g\&., +postmaster\&.pid, as documented in +Section\ \&26.3.3\&. If your file system supports file system snapshots or copy\-on\-write file copies, you can use that to make a backup of the old cluster and tablespaces, though the snapshot and copies must be created simultaneously or while the database server is down\&. +.SH "SEE ALSO" +\fBinitdb\fR(1), \fBpg_ctl\fR(1), \fBpg_dump\fR(1), \fBpostgres\fR(1) diff --git a/doc/src/sgml/man1/pg_verifybackup.1 b/doc/src/sgml/man1/pg_verifybackup.1 new file mode 100644 index 0000000..e9eeb44 --- /dev/null +++ b/doc/src/sgml/man1/pg_verifybackup.1 @@ -0,0 +1,217 @@ +'\" t +.\" Title: pg_verifybackup +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_VERIFYBACKUP" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_verifybackup \- verify the integrity of a base backup of a PostgreSQL cluster +.SH "SYNOPSIS" +.HP \w'\fBpg_verifybackup\fR\ 'u +\fBpg_verifybackup\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +pg_verifybackup +is used to check the integrity of a database cluster backup taken using +\fBpg_basebackup\fR +against a +backup_manifest +generated by the server at the time of the backup\&. The backup must be stored in the "plain" format; a "tar" format backup can be checked after extracting it\&. +.PP +It is important to note that the validation which is performed by +pg_verifybackup +does not and cannot include every check which will be performed by a running server when attempting to make use of the backup\&. Even if you use this tool, you should still perform test restores and verify that the resulting databases work as expected and that they appear to contain the correct data\&. However, +pg_verifybackup +can detect many problems that commonly occur due to storage problems or user error\&. +.PP +Backup verification proceeds in four stages\&. First, +pg_verifybackup +reads the +backup_manifest +file\&. If that file does not exist, cannot be read, is malformed, or fails verification against its own internal checksum, +pg_verifybackup +will terminate with a fatal error\&. +.PP +Second, +pg_verifybackup +will attempt to verify that the data files currently stored on disk are exactly the same as the data files which the server intended to send, with some exceptions that are described below\&. Extra and missing files will be detected, with a few exceptions\&. This step will ignore the presence or absence of, or any modifications to, +postgresql\&.auto\&.conf, +standby\&.signal, and +recovery\&.signal, because it is expected that these files may have been created or modified as part of the process of taking the backup\&. It also won\*(Aqt complain about a +backup_manifest +file in the target directory or about anything inside +pg_wal, even though these files won\*(Aqt be listed in the backup manifest\&. Only files are checked; the presence or absence of directories is not verified, except indirectly: if a directory is missing, any files it should have contained will necessarily also be missing\&. +.PP +Next, +pg_verifybackup +will checksum all the files, compare the checksums against the values in the manifest, and emit errors for any files for which the computed checksum does not match the checksum stored in the manifest\&. This step is not performed for any files which produced errors in the previous step, since they are already known to have problems\&. Files which were ignored in the previous step are also ignored in this step\&. +.PP +Finally, +pg_verifybackup +will use the manifest to verify that the write\-ahead log records which will be needed to recover the backup are present and that they can be read and parsed\&. The +backup_manifest +contains information about which write\-ahead log records will be needed, and +pg_verifybackup +will use that information to invoke +pg_waldump +to parse those write\-ahead log records\&. The +\-\-quiet +flag will be used, so that +pg_waldump +will only report errors, without producing any other output\&. While this level of verification is sufficient to detect obvious problems such as a missing file or one whose internal checksums do not match, they aren\*(Aqt extensive enough to detect every possible problem that might occur when attempting to recover\&. For instance, a server bug that produces write\-ahead log records that have the correct checksums but specify nonsensical actions can\*(Aqt be detected by this method\&. +.PP +Note that if extra WAL files which are not required to recover the backup are present, they will not be checked by this tool, although a separate invocation of +pg_waldump +could be used for that purpose\&. Also note that WAL verification is version\-specific: you must use the version of +pg_verifybackup, and thus of +pg_waldump, which pertains to the backup being checked\&. In contrast, the data file integrity checks should work with any version of the server that generates a +backup_manifest +file\&. +.SH "OPTIONS" +.PP +pg_verifybackup +accepts the following command\-line arguments: +.PP +\fB\-e\fR +.br +\fB\-\-exit\-on\-error\fR +.RS 4 +Exit as soon as a problem with the backup is detected\&. If this option is not specified, +pg_verifybackup +will continue checking the backup even after a problem has been detected, and will report all problems detected as errors\&. +.RE +.PP +\fB\-i \fR\fB\fIpath\fR\fR +.br +\fB\-\-ignore=\fR\fB\fIpath\fR\fR +.RS 4 +Ignore the specified file or directory, which should be expressed as a relative path name, when comparing the list of data files actually present in the backup to those listed in the +backup_manifest +file\&. If a directory is specified, this option affects the entire subtree rooted at that location\&. Complaints about extra files, missing files, file size differences, or checksum mismatches will be suppressed if the relative path name matches the specified path name\&. This option can be specified multiple times\&. +.RE +.PP +\fB\-m \fR\fB\fIpath\fR\fR +.br +\fB\-\-manifest\-path=\fR\fB\fIpath\fR\fR +.RS 4 +Use the manifest file at the specified path, rather than one located in the root of the backup directory\&. +.RE +.PP +\fB\-n\fR +.br +\fB\-\-no\-parse\-wal\fR +.RS 4 +Don\*(Aqt attempt to parse write\-ahead log data that will be needed to recover from this backup\&. +.RE +.PP +\fB\-q\fR +.br +\fB\-\-quiet\fR +.RS 4 +Don\*(Aqt print anything when a backup is successfully verified\&. +.RE +.PP +\fB\-s\fR +.br +\fB\-\-skip\-checksums\fR +.RS 4 +Do not verify data file checksums\&. The presence or absence of files and the sizes of those files will still be checked\&. This is much faster, because the files themselves do not need to be read\&. +.RE +.PP +\fB\-w \fR\fB\fIpath\fR\fR +.br +\fB\-\-wal\-directory=\fR\fB\fIpath\fR\fR +.RS 4 +Try to parse WAL files stored in the specified directory, rather than in +pg_wal\&. This may be useful if the backup is stored in a separate location from the WAL archive\&. +.RE +.PP +Other options are also available: +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_verifybackup +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_verifybackup +command line arguments, and exit\&. +.RE +.SH "EXAMPLES" +.PP +To create a base backup of the server at +mydbserver +and verify the integrity of the backup: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_basebackup \-h mydbserver \-D /usr/local/pgsql/data\fR +$ \fBpg_verifybackup /usr/local/pgsql/data\fR +.fi +.if n \{\ +.RE +.\} +.PP +To create a base backup of the server at +mydbserver, move the manifest somewhere outside the backup directory, and verify the backup: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_basebackup \-h mydbserver \-D /usr/local/pgsql/backup1234\fR +$ \fBmv /usr/local/pgsql/backup1234/backup_manifest /my/secure/location/backup_manifest\&.1234\fR +$ \fBpg_verifybackup \-m /my/secure/location/backup_manifest\&.1234 /usr/local/pgsql/backup1234\fR +.fi +.if n \{\ +.RE +.\} +.PP +To verify a backup while ignoring a file that was added manually to the backup directory, and also skipping checksum verification: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpg_basebackup \-h mydbserver \-D /usr/local/pgsql/data\fR +$ \fBedit /usr/local/pgsql/data/note\&.to\&.self\fR +$ \fBpg_verifybackup \-\-ignore=note\&.to\&.self \-\-skip\-checksums /usr/local/pgsql/data\fR +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBpg_basebackup\fR(1) diff --git a/doc/src/sgml/man1/pg_waldump.1 b/doc/src/sgml/man1/pg_waldump.1 new file mode 100644 index 0000000..816b9e4 --- /dev/null +++ b/doc/src/sgml/man1/pg_waldump.1 @@ -0,0 +1,239 @@ +'\" t +.\" Title: pg_waldump +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PG_WALDUMP" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pg_waldump \- display a human\-readable rendering of the write\-ahead log of a PostgreSQL database cluster +.SH "SYNOPSIS" +.HP \w'\fBpg_waldump\fR\ 'u +\fBpg_waldump\fR [\fBoption\fR...] [\fBstartseg\fR\ [\fBendseg\fR]] +.SH "DESCRIPTION" +.PP +\fBpg_waldump\fR +displays the write\-ahead log (WAL) and is mainly useful for debugging or educational purposes\&. +.PP +This utility can only be run by the user who installed the server, because it requires read\-only access to the data directory\&. +.SH "OPTIONS" +.PP +The following command\-line options control the location and format of the output: +.PP +\fIstartseg\fR +.RS 4 +Start reading at the specified log segment file\&. This implicitly determines the path in which files will be searched for, and the timeline to use\&. +.RE +.PP +\fIendseg\fR +.RS 4 +Stop after reading the specified log segment file\&. +.RE +.PP +\fB\-b\fR +.br +\fB\-\-bkp\-details\fR +.RS 4 +Output detailed information about backup blocks\&. +.RE +.PP +\fB\-B \fR\fB\fIblock\fR\fR +.br +\fB\-\-block=\fR\fB\fIblock\fR\fR +.RS 4 +Only display records that modify the given block\&. The relation must also be provided with +\fB\-\-relation\fR +or +\fB\-R\fR\&. +.RE +.PP +\fB\-e \fR\fB\fIend\fR\fR +.br +\fB\-\-end=\fR\fB\fIend\fR\fR +.RS 4 +Stop reading at the specified WAL location, instead of reading to the end of the log stream\&. +.RE +.PP +\fB\-f\fR +.br +\fB\-\-follow\fR +.RS 4 +After reaching the end of valid WAL, keep polling once per second for new WAL to appear\&. +.RE +.PP +\fB\-F \fR\fB\fIfork\fR\fR +.br +\fB\-\-fork=\fR\fB\fIfork\fR\fR +.RS 4 +If provided, only display records that modify blocks in the given fork\&. The valid values are +main +for the main fork, +fsm +for the free space map, +vm +for the visibility map, and +init +for the init fork\&. +.RE +.PP +\fB\-n \fR\fB\fIlimit\fR\fR +.br +\fB\-\-limit=\fR\fB\fIlimit\fR\fR +.RS 4 +Display the specified number of records, then stop\&. +.RE +.PP +\fB\-p \fR\fB\fIpath\fR\fR +.br +\fB\-\-path=\fR\fB\fIpath\fR\fR +.RS 4 +Specifies a directory to search for log segment files or a directory with a +pg_wal +subdirectory that contains such files\&. The default is to search in the current directory, the +pg_wal +subdirectory of the current directory, and the +pg_wal +subdirectory of +\fBPGDATA\fR\&. +.RE +.PP +\fB\-q\fR +.br +\fB\-\-quiet\fR +.RS 4 +Do not print any output, except for errors\&. This option can be useful when you want to know whether a range of WAL records can be successfully parsed but don\*(Aqt care about the record contents\&. +.RE +.PP +\fB\-r \fR\fB\fIrmgr\fR\fR +.br +\fB\-\-rmgr=\fR\fB\fIrmgr\fR\fR +.RS 4 +Only display records generated by the specified resource manager\&. You can specify the option multiple times to select multiple resource managers\&. If +list +is passed as name, print a list of valid resource manager names, and exit\&. +.sp +Extensions may define custom resource managers, but pg_waldump does not load the extension module and therefore does not recognize custom resource managers by name\&. Instead, you can specify the custom resource managers as +custom### +where "###" is the three\-digit resource manager ID\&. Names of this form will always be considered valid\&. +.RE +.PP +\fB\-R \fR\fB\fItblspc\fR\fR\fB/\fR\fB\fIdb\fR\fR\fB/\fR\fB\fIrel\fR\fR +.br +\fB\-\-relation=\fR\fB\fItblspc\fR\fR\fB/\fR\fB\fIdb\fR\fR\fB/\fR\fB\fIrel\fR\fR +.RS 4 +Only display records that modify blocks in the given relation\&. The relation is specified with tablespace OID, database OID, and relfilenode separated by slashes, for example +1234/12345/12345\&. This is the same format used for relations in the program\*(Aqs output\&. +.RE +.PP +\fB\-s \fR\fB\fIstart\fR\fR +.br +\fB\-\-start=\fR\fB\fIstart\fR\fR +.RS 4 +WAL location at which to start reading\&. The default is to start reading the first valid log record found in the earliest file found\&. +.RE +.PP +\fB\-t \fR\fB\fItimeline\fR\fR +.br +\fB\-\-timeline=\fR\fB\fItimeline\fR\fR +.RS 4 +Timeline from which to read log records\&. The default is to use the value in +\fIstartseg\fR, if that is specified; otherwise, the default is 1\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pg_waldump +version and exit\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-fullpage\fR +.RS 4 +Only display records that include full page images\&. +.RE +.PP +\fB\-x \fR\fB\fIxid\fR\fR +.br +\fB\-\-xid=\fR\fB\fIxid\fR\fR +.RS 4 +Only display records marked with the given transaction ID\&. +.RE +.PP +\fB\-z\fR +.br +\fB\-\-stats[=record]\fR +.RS 4 +Display summary statistics (number and size of records and full\-page images) instead of individual records\&. Optionally generate statistics per\-record instead of per\-rmgr\&. +.sp +If +pg_waldump +is terminated by signal +SIGINT +(Control+C), the summary of the statistics computed is displayed up to the termination point\&. This operation is not supported on +Windows\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pg_waldump +command line arguments, and exit\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGDATA\fR +.RS 4 +Data directory; see also the +\fB\-p\fR +option\&. +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.SH "NOTES" +.PP +Can give wrong results when the server is running\&. +.PP +Only the specified timeline is displayed (or the default, if none is specified)\&. Records in other timelines are ignored\&. +.PP +pg_waldump +cannot read WAL files with suffix +\&.partial\&. If those files need to be read, +\&.partial +suffix needs to be removed from the file name\&. +.SH "SEE ALSO" +Section\ \&30.6 diff --git a/doc/src/sgml/man1/pgbench.1 b/doc/src/sgml/man1/pgbench.1 new file mode 100644 index 0000000..a0bdc16 --- /dev/null +++ b/doc/src/sgml/man1/pgbench.1 @@ -0,0 +1,2897 @@ +'\" t +.\" Title: pgbench +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PGBENCH" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +pgbench \- run a benchmark test on PostgreSQL +.SH "SYNOPSIS" +.HP \w'\fBpgbench\fR\ 'u +\fBpgbench\fR \fB\-i\fR [\fIoption\fR...] [\fIdbname\fR] +.HP \w'\fBpgbench\fR\ 'u +\fBpgbench\fR [\fIoption\fR...] [\fIdbname\fR] +.SH "DESCRIPTION" +.PP +pgbench +is a simple program for running benchmark tests on +PostgreSQL\&. It runs the same sequence of SQL commands over and over, possibly in multiple concurrent database sessions, and then calculates the average transaction rate (transactions per second)\&. By default, +pgbench +tests a scenario that is loosely based on TPC\-B, involving five +\fBSELECT\fR, +\fBUPDATE\fR, and +\fBINSERT\fR +commands per transaction\&. However, it is easy to test other cases by writing your own transaction script files\&. +.PP +Typical output from +pgbench +looks like: +.sp +.if n \{\ +.RS 4 +.\} +.nf +transaction type: <builtin: TPC\-B (sort of)> +scaling factor: 10 +query mode: simple +number of clients: 10 +number of threads: 1 +maximum number of tries: 1 +number of transactions per client: 1000 +number of transactions actually processed: 10000/10000 +number of failed transactions: 0 (0\&.000%) +latency average = 11\&.013 ms +latency stddev = 7\&.351 ms +initial connection time = 45\&.758 ms +tps = 896\&.967014 (without initial connection time) +.fi +.if n \{\ +.RE +.\} +.sp +The first seven lines report some of the most important parameter settings\&. The sixth line reports the maximum number of tries for transactions with serialization or deadlock errors (see +Failures and Serialization/Deadlock Retries +for more information)\&. The eighth line reports the number of transactions completed and intended (the latter being just the product of number of clients and number of transactions per client); these will be equal unless the run failed before completion or some SQL command(s) failed\&. (In +\fB\-T\fR +mode, only the actual number of transactions is printed\&.) The next line reports the number of failed transactions due to serialization or deadlock errors (see +Failures and Serialization/Deadlock Retries +for more information)\&. The last line reports the number of transactions per second\&. +.PP +The default TPC\-B\-like transaction test requires specific tables to be set up beforehand\&. +pgbench +should be invoked with the +\fB\-i\fR +(initialize) option to create and populate these tables\&. (When you are testing a custom script, you don\*(Aqt need this step, but will instead need to do whatever setup your test needs\&.) Initialization looks like: +.sp +.if n \{\ +.RS 4 +.\} +.nf +pgbench \-i [ \fIother\-options\fR ] \fIdbname\fR +.fi +.if n \{\ +.RE +.\} +.sp +where +\fIdbname\fR +is the name of the already\-created database to test in\&. (You may also need +\fB\-h\fR, +\fB\-p\fR, and/or +\fB\-U\fR +options to specify how to connect to the database server\&.) +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.PP +pgbench \-i +creates four tables +pgbench_accounts, +pgbench_branches, +pgbench_history, and +pgbench_tellers, destroying any existing tables of these names\&. Be very careful to use another database if you have tables having these names! +.sp .5v +.RE +.PP +At the default +\(lqscale factor\(rq +of 1, the tables initially contain this many rows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +table # of rows +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +pgbench_branches 1 +pgbench_tellers 10 +pgbench_accounts 100000 +pgbench_history 0 +.fi +.if n \{\ +.RE +.\} +.sp +You can (and, for most purposes, probably should) increase the number of rows by using the +\fB\-s\fR +(scale factor) option\&. The +\fB\-F\fR +(fillfactor) option might also be used at this point\&. +.PP +Once you have done the necessary setup, you can run your benchmark with a command that doesn\*(Aqt include +\fB\-i\fR, that is +.sp +.if n \{\ +.RS 4 +.\} +.nf +pgbench [ \fIoptions\fR ] \fIdbname\fR +.fi +.if n \{\ +.RE +.\} +.sp +In nearly all cases, you\*(Aqll need some options to make a useful test\&. The most important options are +\fB\-c\fR +(number of clients), +\fB\-t\fR +(number of transactions), +\fB\-T\fR +(time limit), and +\fB\-f\fR +(specify a custom script file)\&. See below for a full list\&. +.SH "OPTIONS" +.PP +The following is divided into three subsections\&. Different options are used during database initialization and while running benchmarks, but some options are useful in both cases\&. +.SS "Initialization Options" +.PP +pgbench +accepts the following command\-line initialization arguments: +.PP +\fIdbname\fR +.RS 4 +Specifies the name of the database to test in\&. If this is not specified, the environment variable +\fBPGDATABASE\fR +is used\&. If that is not set, the user name specified for the connection is used\&. +.RE +.PP +\fB\-i\fR +.br +\fB\-\-initialize\fR +.RS 4 +Required to invoke initialization mode\&. +.RE +.PP +\fB\-I \fR\fB\fIinit_steps\fR\fR +.br +\fB\-\-init\-steps=\fR\fB\fIinit_steps\fR\fR +.RS 4 +Perform just a selected set of the normal initialization steps\&. +\fIinit_steps\fR +specifies the initialization steps to be performed, using one character per step\&. Each step is invoked in the specified order\&. The default is +dtgvp\&. The available steps are: +.PP +d (Drop) +.RS 4 +Drop any existing +pgbench +tables\&. +.RE +.PP +t (create Tables) +.RS 4 +Create the tables used by the standard +pgbench +scenario, namely +pgbench_accounts, +pgbench_branches, +pgbench_history, and +pgbench_tellers\&. +.RE +.PP +g or G (Generate data, client\-side or server\-side) +.RS 4 +Generate data and load it into the standard tables, replacing any data already present\&. +.sp +With +g +(client\-side data generation), data is generated in +\fBpgbench\fR +client and then sent to the server\&. This uses the client/server bandwidth extensively through a +\fBCOPY\fR\&. +\fBpgbench\fR +uses the FREEZE option with version 14 or later of +PostgreSQL +to speed up subsequent +\fBVACUUM\fR, unless partitions are enabled\&. Using +g +causes logging to print one message every 100,000 rows while generating data for the +pgbench_accounts +table\&. +.sp +With +G +(server\-side data generation), only small queries are sent from the +\fBpgbench\fR +client and then data is actually generated in the server\&. No significant bandwidth is required for this variant, but the server will do more work\&. Using +G +causes logging not to print any progress message while generating data\&. +.sp +The default initialization behavior uses client\-side data generation (equivalent to +g)\&. +.RE +.PP +v (Vacuum) +.RS 4 +Invoke +\fBVACUUM\fR +on the standard tables\&. +.RE +.PP +p (create Primary keys) +.RS 4 +Create primary key indexes on the standard tables\&. +.RE +.PP +f (create Foreign keys) +.RS 4 +Create foreign key constraints between the standard tables\&. (Note that this step is not performed by default\&.) +.RE +.RE +.PP +\fB\-F\fR \fIfillfactor\fR +.br +\fB\-\-fillfactor=\fR\fIfillfactor\fR +.RS 4 +Create the +pgbench_accounts, +pgbench_tellers +and +pgbench_branches +tables with the given fillfactor\&. Default is 100\&. +.RE +.PP +\fB\-n\fR +.br +\fB\-\-no\-vacuum\fR +.RS 4 +Perform no vacuuming during initialization\&. (This option suppresses the +v +initialization step, even if it was specified in +\fB\-I\fR\&.) +.RE +.PP +\fB\-q\fR +.br +\fB\-\-quiet\fR +.RS 4 +Switch logging to quiet mode, producing only one progress message per 5 seconds\&. The default logging prints one message each 100,000 rows, which often outputs many lines per second (especially on good hardware)\&. +.sp +This setting has no effect if +G +is specified in +\fB\-I\fR\&. +.RE +.PP +\fB\-s\fR \fIscale_factor\fR +.br +\fB\-\-scale=\fR\fIscale_factor\fR +.RS 4 +Multiply the number of rows generated by the scale factor\&. For example, +\-s 100 +will create 10,000,000 rows in the +pgbench_accounts +table\&. Default is 1\&. When the scale is 20,000 or larger, the columns used to hold account identifiers (aid +columns) will switch to using larger integers (bigint), in order to be big enough to hold the range of account identifiers\&. +.RE +.PP +\fB\-\-foreign\-keys\fR +.RS 4 +Create foreign key constraints between the standard tables\&. (This option adds the +f +step to the initialization step sequence, if it is not already present\&.) +.RE +.PP +\fB\-\-index\-tablespace=\fR\fB\fIindex_tablespace\fR\fR +.RS 4 +Create indexes in the specified tablespace, rather than the default tablespace\&. +.RE +.PP +\fB\-\-partition\-method=\fR\fB\fINAME\fR\fR +.RS 4 +Create a partitioned +pgbench_accounts +table with +\fINAME\fR +method\&. Expected values are +range +or +hash\&. This option requires that +\fB\-\-partitions\fR +is set to non\-zero\&. If unspecified, default is +range\&. +.RE +.PP +\fB\-\-partitions=\fR\fB\fINUM\fR\fR +.RS 4 +Create a partitioned +pgbench_accounts +table with +\fINUM\fR +partitions of nearly equal size for the scaled number of accounts\&. Default is +0, meaning no partitioning\&. +.RE +.PP +\fB\-\-tablespace=\fR\fB\fItablespace\fR\fR +.RS 4 +Create tables in the specified tablespace, rather than the default tablespace\&. +.RE +.PP +\fB\-\-unlogged\-tables\fR +.RS 4 +Create all tables as unlogged tables, rather than permanent tables\&. +.RE +.SS "Benchmarking Options" +.PP +pgbench +accepts the following command\-line benchmarking arguments: +.PP +\fB\-b\fR \fIscriptname[@weight]\fR +.br +\fB\-\-builtin\fR=\fIscriptname[@weight]\fR +.RS 4 +Add the specified built\-in script to the list of scripts to be executed\&. Available built\-in scripts are: +tpcb\-like, +simple\-update +and +select\-only\&. Unambiguous prefixes of built\-in names are accepted\&. With the special name +list, show the list of built\-in scripts and exit immediately\&. +.sp +Optionally, write an integer weight after +@ +to adjust the probability of selecting this script versus other ones\&. The default weight is 1\&. See below for details\&. +.RE +.PP +\fB\-c\fR \fIclients\fR +.br +\fB\-\-client=\fR\fIclients\fR +.RS 4 +Number of clients simulated, that is, number of concurrent database sessions\&. Default is 1\&. +.RE +.PP +\fB\-C\fR +.br +\fB\-\-connect\fR +.RS 4 +Establish a new connection for each transaction, rather than doing it just once per client session\&. This is useful to measure the connection overhead\&. +.RE +.PP +\fB\-d\fR +.br +\fB\-\-debug\fR +.RS 4 +Print debugging output\&. +.RE +.PP +\fB\-D\fR \fIvarname\fR=\fIvalue\fR +.br +\fB\-\-define=\fR\fIvarname\fR=\fIvalue\fR +.RS 4 +Define a variable for use by a custom script (see below)\&. Multiple +\fB\-D\fR +options are allowed\&. +.RE +.PP +\fB\-f\fR \fIfilename[@weight]\fR +.br +\fB\-\-file=\fR\fIfilename[@weight]\fR +.RS 4 +Add a transaction script read from +\fIfilename\fR +to the list of scripts to be executed\&. +.sp +Optionally, write an integer weight after +@ +to adjust the probability of selecting this script versus other ones\&. The default weight is 1\&. (To use a script file name that includes an +@ +character, append a weight so that there is no ambiguity, for example +filen@me@1\&.) See below for details\&. +.RE +.PP +\fB\-j\fR \fIthreads\fR +.br +\fB\-\-jobs=\fR\fIthreads\fR +.RS 4 +Number of worker threads within +pgbench\&. Using more than one thread can be helpful on multi\-CPU machines\&. Clients are distributed as evenly as possible among available threads\&. Default is 1\&. +.RE +.PP +\fB\-l\fR +.br +\fB\-\-log\fR +.RS 4 +Write information about each transaction to a log file\&. See below for details\&. +.RE +.PP +\fB\-L\fR \fIlimit\fR +.br +\fB\-\-latency\-limit=\fR\fIlimit\fR +.RS 4 +Transactions that last more than +\fIlimit\fR +milliseconds are counted and reported separately, as +late\&. +.sp +When throttling is used (\fB\-\-rate=\&.\&.\&.\fR), transactions that lag behind schedule by more than +\fIlimit\fR +ms, and thus have no hope of meeting the latency limit, are not sent to the server at all\&. They are counted and reported separately as +skipped\&. +.sp +When the +\fB\-\-max\-tries\fR +option is used, a transaction which fails due to a serialization anomaly or from a deadlock will not be retried if the total time of all its tries is greater than +\fIlimit\fR +ms\&. To limit only the time of tries and not their number, use +\-\-max\-tries=0\&. By default, the option +\fB\-\-max\-tries\fR +is set to 1 and transactions with serialization/deadlock errors are not retried\&. See +Failures and Serialization/Deadlock Retries +for more information about retrying such transactions\&. +.RE +.PP +\fB\-M\fR \fIquerymode\fR +.br +\fB\-\-protocol=\fR\fIquerymode\fR +.RS 4 +Protocol to use for submitting queries to the server: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +simple: use simple query protocol\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +extended: use extended query protocol\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +prepared: use extended query protocol with prepared statements\&. +.RE +.sp +In the +prepared +mode, +pgbench +reuses the parse analysis result starting from the second query iteration, so +pgbench +runs faster than in other modes\&. +.sp +The default is simple query protocol\&. (See +Chapter\ \&55 +for more information\&.) +.RE +.PP +\fB\-n\fR +.br +\fB\-\-no\-vacuum\fR +.RS 4 +Perform no vacuuming before running the test\&. This option is +\fInecessary\fR +if you are running a custom test scenario that does not include the standard tables +pgbench_accounts, +pgbench_branches, +pgbench_history, and +pgbench_tellers\&. +.RE +.PP +\fB\-N\fR +.br +\fB\-\-skip\-some\-updates\fR +.RS 4 +Run built\-in simple\-update script\&. Shorthand for +\fB\-b simple\-update\fR\&. +.RE +.PP +\fB\-P\fR \fIsec\fR +.br +\fB\-\-progress=\fR\fIsec\fR +.RS 4 +Show progress report every +\fIsec\fR +seconds\&. The report includes the time since the beginning of the run, the TPS since the last report, and the transaction latency average, standard deviation, and the number of failed transactions since the last report\&. Under throttling (\fB\-R\fR), the latency is computed with respect to the transaction scheduled start time, not the actual transaction beginning time, thus it also includes the average schedule lag time\&. When +\fB\-\-max\-tries\fR +is used to enable transaction retries after serialization/deadlock errors, the report includes the number of retried transactions and the sum of all retries\&. +.RE +.PP +\fB\-r\fR +.br +\fB\-\-report\-per\-command\fR +.RS 4 +Report the following statistics for each command after the benchmark finishes: the average per\-statement latency (execution time from the perspective of the client), the number of failures, and the number of retries after serialization or deadlock errors in this command\&. The report displays retry statistics only if the +\fB\-\-max\-tries\fR +option is not equal to 1\&. +.RE +.PP +\fB\-R\fR \fIrate\fR +.br +\fB\-\-rate=\fR\fIrate\fR +.RS 4 +Execute transactions targeting the specified rate instead of running as fast as possible (the default)\&. The rate is given in transactions per second\&. If the targeted rate is above the maximum possible rate, the rate limit won\*(Aqt impact the results\&. +.sp +The rate is targeted by starting transactions along a Poisson\-distributed schedule time line\&. The expected start time schedule moves forward based on when the client first started, not when the previous transaction ended\&. That approach means that when transactions go past their original scheduled end time, it is possible for later ones to catch up again\&. +.sp +When throttling is active, the transaction latency reported at the end of the run is calculated from the scheduled start times, so it includes the time each transaction had to wait for the previous transaction to finish\&. The wait time is called the schedule lag time, and its average and maximum are also reported separately\&. The transaction latency with respect to the actual transaction start time, i\&.e\&., the time spent executing the transaction in the database, can be computed by subtracting the schedule lag time from the reported latency\&. +.sp +If +\fB\-\-latency\-limit\fR +is used together with +\fB\-\-rate\fR, a transaction can lag behind so much that it is already over the latency limit when the previous transaction ends, because the latency is calculated from the scheduled start time\&. Such transactions are not sent to the server, but are skipped altogether and counted separately\&. +.sp +A high schedule lag time is an indication that the system cannot process transactions at the specified rate, with the chosen number of clients and threads\&. When the average transaction execution time is longer than the scheduled interval between each transaction, each successive transaction will fall further behind, and the schedule lag time will keep increasing the longer the test run is\&. When that happens, you will have to reduce the specified transaction rate\&. +.RE +.PP +\fB\-s\fR \fIscale_factor\fR +.br +\fB\-\-scale=\fR\fIscale_factor\fR +.RS 4 +Report the specified scale factor in +pgbench\*(Aqs output\&. With the built\-in tests, this is not necessary; the correct scale factor will be detected by counting the number of rows in the +pgbench_branches +table\&. However, when testing only custom benchmarks (\fB\-f\fR +option), the scale factor will be reported as 1 unless this option is used\&. +.RE +.PP +\fB\-S\fR +.br +\fB\-\-select\-only\fR +.RS 4 +Run built\-in select\-only script\&. Shorthand for +\fB\-b select\-only\fR\&. +.RE +.PP +\fB\-t\fR \fItransactions\fR +.br +\fB\-\-transactions=\fR\fItransactions\fR +.RS 4 +Number of transactions each client runs\&. Default is 10\&. +.RE +.PP +\fB\-T\fR \fIseconds\fR +.br +\fB\-\-time=\fR\fIseconds\fR +.RS 4 +Run the test for this many seconds, rather than a fixed number of transactions per client\&. +\fB\-t\fR +and +\fB\-T\fR +are mutually exclusive\&. +.RE +.PP +\fB\-v\fR +.br +\fB\-\-vacuum\-all\fR +.RS 4 +Vacuum all four standard tables before running the test\&. With neither +\fB\-n\fR +nor +\fB\-v\fR, +pgbench +will vacuum the +pgbench_tellers +and +pgbench_branches +tables, and will truncate +pgbench_history\&. +.RE +.PP +\fB\-\-aggregate\-interval=\fR\fB\fIseconds\fR\fR +.RS 4 +Length of aggregation interval (in seconds)\&. May be used only with +\fB\-l\fR +option\&. With this option, the log contains per\-interval summary data, as described below\&. +.RE +.PP +\fB\-\-failures\-detailed\fR +.RS 4 +Report failures in per\-transaction and aggregation logs, as well as in the main and per\-script reports, grouped by the following types: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +serialization failures; +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +deadlock failures; +.RE +.sp +See +Failures and Serialization/Deadlock Retries +for more information\&. +.RE +.PP +\fB\-\-log\-prefix=\fR\fB\fIprefix\fR\fR +.RS 4 +Set the filename prefix for the log files created by +\fB\-\-log\fR\&. The default is +pgbench_log\&. +.RE +.PP +\fB\-\-max\-tries=\fR\fB\fInumber_of_tries\fR\fR +.RS 4 +Enable retries for transactions with serialization/deadlock errors and set the maximum number of these tries\&. This option can be combined with the +\fB\-\-latency\-limit\fR +option which limits the total time of all transaction tries; moreover, you cannot use an unlimited number of tries (\-\-max\-tries=0) without +\fB\-\-latency\-limit\fR +or +\fB\-\-time\fR\&. The default value is 1 and transactions with serialization/deadlock errors are not retried\&. See +Failures and Serialization/Deadlock Retries +for more information about retrying such transactions\&. +.RE +.PP +\fB\-\-progress\-timestamp\fR +.RS 4 +When showing progress (option +\fB\-P\fR), use a timestamp (Unix epoch) instead of the number of seconds since the beginning of the run\&. The unit is in seconds, with millisecond precision after the dot\&. This helps compare logs generated by various tools\&. +.RE +.PP +\fB\-\-random\-seed=\fR\fIseed\fR +.RS 4 +Set random generator seed\&. Seeds the system random number generator, which then produces a sequence of initial generator states, one for each thread\&. Values for +\fIseed\fR +may be: +time +(the default, the seed is based on the current time), +rand +(use a strong random source, failing if none is available), or an unsigned decimal integer value\&. The random generator is invoked explicitly from a pgbench script (random\&.\&.\&. +functions) or implicitly (for instance option +\fB\-\-rate\fR +uses it to schedule transactions)\&. When explicitly set, the value used for seeding is shown on the terminal\&. Any value allowed for +\fIseed\fR +may also be provided through the environment variable +PGBENCH_RANDOM_SEED\&. To ensure that the provided seed impacts all possible uses, put this option first or use the environment variable\&. +.sp +Setting the seed explicitly allows to reproduce a +\fBpgbench\fR +run exactly, as far as random numbers are concerned\&. As the random state is managed per thread, this means the exact same +\fBpgbench\fR +run for an identical invocation if there is one client per thread and there are no external or data dependencies\&. From a statistical viewpoint reproducing runs exactly is a bad idea because it can hide the performance variability or improve performance unduly, e\&.g\&., by hitting the same pages as a previous run\&. However, it may also be of great help for debugging, for instance re\-running a tricky case which leads to an error\&. Use wisely\&. +.RE +.PP +\fB\-\-sampling\-rate=\fR\fB\fIrate\fR\fR +.RS 4 +Sampling rate, used when writing data into the log, to reduce the amount of log generated\&. If this option is given, only the specified fraction of transactions are logged\&. 1\&.0 means all transactions will be logged, 0\&.05 means only 5% of the transactions will be logged\&. +.sp +Remember to take the sampling rate into account when processing the log file\&. For example, when computing TPS values, you need to multiply the numbers accordingly (e\&.g\&., with 0\&.01 sample rate, you\*(Aqll only get 1/100 of the actual TPS)\&. +.RE +.PP +\fB\-\-show\-script=\fR\fIscriptname\fR +.RS 4 +Show the actual code of builtin script +\fIscriptname\fR +on stderr, and exit immediately\&. +.RE +.PP +\fB\-\-verbose\-errors\fR +.RS 4 +Print messages about all errors and failures (errors without retrying) including which limit for retries was exceeded and how far it was exceeded for the serialization/deadlock failures\&. (Note that in this case the output can be significantly increased\&.)\&. See +Failures and Serialization/Deadlock Retries +for more information\&. +.RE +.SS "Common Options" +.PP +pgbench +also accepts the following common command\-line arguments for connection parameters: +.PP +\fB\-h\fR \fIhostname\fR +.br +\fB\-\-host=\fR\fIhostname\fR +.RS 4 +The database server\*(Aqs host name +.RE +.PP +\fB\-p\fR \fIport\fR +.br +\fB\-\-port=\fR\fIport\fR +.RS 4 +The database server\*(Aqs port number +.RE +.PP +\fB\-U\fR \fIlogin\fR +.br +\fB\-\-username=\fR\fIlogin\fR +.RS 4 +The user name to connect as +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +pgbench +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +pgbench +command line arguments, and exit\&. +.RE +.SH "EXIT STATUS" +.PP +A successful run will exit with status 0\&. Exit status 1 indicates static problems such as invalid command\-line options or internal errors which are supposed to never occur\&. Early errors that occur when starting benchmark such as initial connection failures also exit with status 1\&. Errors during the run such as database errors or problems in the script will result in exit status 2\&. In the latter case, +pgbench +will print partial results\&. +.SH "ENVIRONMENT" +.PP +\fBPGDATABASE\fR +.br +\fBPGHOST\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.PP +The environment variable +\fBPG_COLOR\fR +specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.SH "NOTES" +.SS "What Is the \(lqTransaction\(rq Actually Performed in pgbench?" +.PP +pgbench +executes test scripts chosen randomly from a specified list\&. The scripts may include built\-in scripts specified with +\fB\-b\fR +and user\-provided scripts specified with +\fB\-f\fR\&. Each script may be given a relative weight specified after an +@ +so as to change its selection probability\&. The default weight is +1\&. Scripts with a weight of +0 +are ignored\&. +.PP +The default built\-in transaction script (also invoked with +\fB\-b tpcb\-like\fR) issues seven commands per transaction over randomly chosen +aid, +tid, +bid +and +delta\&. The scenario is inspired by the TPC\-B benchmark, but is not actually TPC\-B, hence the name\&. +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +BEGIN; +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +SELECT abalance FROM pgbench_accounts WHERE aid = :aid; +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 6." 4.2 +.\} +INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 7." 4.2 +.\} +END; +.RE +.PP +If you select the +simple\-update +built\-in (also +\fB\-N\fR), steps 4 and 5 aren\*(Aqt included in the transaction\&. This will avoid update contention on these tables, but it makes the test case even less like TPC\-B\&. +.PP +If you select the +select\-only +built\-in (also +\fB\-S\fR), only the +\fBSELECT\fR +is issued\&. +.SS "Custom Scripts" +.PP +pgbench +has support for running custom benchmark scenarios by replacing the default transaction script (described above) with a transaction script read from a file (\fB\-f\fR +option)\&. In this case a +\(lqtransaction\(rq +counts as one execution of a script file\&. +.PP +A script file contains one or more SQL commands terminated by semicolons\&. Empty lines and lines beginning with +\-\- +are ignored\&. Script files can also contain +\(lqmeta commands\(rq, which are interpreted by +pgbench +itself, as described below\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +Before +PostgreSQL +9\&.6, SQL commands in script files were terminated by newlines, and so they could not be continued across lines\&. Now a semicolon is +\fIrequired\fR +to separate consecutive SQL commands (though an SQL command does not need one if it is followed by a meta command)\&. If you need to create a script file that works with both old and new versions of +pgbench, be sure to write each SQL command on a single line ending with a semicolon\&. +.PP +It is assumed that pgbench scripts do not contain incomplete blocks of SQL transactions\&. If at runtime the client reaches the end of the script without completing the last transaction block, it will be aborted\&. +.sp .5v +.RE +.PP +There is a simple variable\-substitution facility for script files\&. Variable names must consist of letters (including non\-Latin letters), digits, and underscores, with the first character not being a digit\&. Variables can be set by the command\-line +\fB\-D\fR +option, explained above, or by the meta commands explained below\&. In addition to any variables preset by +\fB\-D\fR +command\-line options, there are a few variables that are preset automatically, listed in +Table\ \&288\&. A value specified for these variables using +\fB\-D\fR +takes precedence over the automatic presets\&. Once set, a variable\*(Aqs value can be inserted into an SQL command by writing +:\fIvariablename\fR\&. When running more than one client session, each session has its own set of variables\&. +pgbench +supports up to 255 variable uses in one statement\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&288.\ \&pgbench Automatic Variables +.TS +allbox tab(:); +lB lB. +T{ +Variable +T}:T{ +Description +T} +.T& +l l +l l +l l +l l. +T{ +client_id +T}:T{ +unique number identifying the client session (starts from zero) +T} +T{ +default_seed +T}:T{ +seed used in hash and pseudorandom permutation functions by default +T} +T{ +random_seed +T}:T{ +random generator seed (unless overwritten with \fB\-D\fR) +T} +T{ +scale +T}:T{ +current scale factor +T} +.TE +.sp 1 +.PP +Script file meta commands begin with a backslash (\e) and normally extend to the end of the line, although they can be continued to additional lines by writing backslash\-return\&. Arguments to a meta command are separated by white space\&. These meta commands are supported: +.PP +\egset [\fIprefix\fR] \easet [\fIprefix\fR] +.RS 4 +These commands may be used to end SQL queries, taking the place of the terminating semicolon (;)\&. +.sp +When the +\egset +command is used, the preceding SQL query is expected to return one row, the columns of which are stored into variables named after column names, and prefixed with +\fIprefix\fR +if provided\&. +.sp +When the +\easet +command is used, all combined SQL queries (separated by +\e;) have their columns stored into variables named after column names, and prefixed with +\fIprefix\fR +if provided\&. If a query returns no row, no assignment is made and the variable can be tested for existence to detect this\&. If a query returns more than one row, the last value is kept\&. +.sp +\egset +and +\easet +cannot be used in pipeline mode, since the query results are not yet available by the time the commands would need them\&. +.sp +The following example puts the final account balance from the first query into variable +\fIabalance\fR, and fills variables +\fIp_two\fR +and +\fIp_three\fR +with integers from the third query\&. The result of the second query is discarded\&. The result of the two last combined queries are stored in variables +\fIfour\fR +and +\fIfive\fR\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE pgbench_accounts + SET abalance = abalance + :delta + WHERE aid = :aid + RETURNING abalance \egset +\-\- compound of two queries +SELECT 1 \e; +SELECT 2 AS two, 3 AS three \egset p_ +SELECT 4 AS four \e; SELECT 5 AS five \easet +.fi +.if n \{\ +.RE +.\} +.RE +.PP +\eif \fIexpression\fR +.br +\eelif \fIexpression\fR +.br +\eelse +.br +\eendif +.RS 4 +This group of commands implements nestable conditional blocks, similarly to +psql\*(Aqs +\eif \fIexpression\fR\&. Conditional expressions are identical to those with +\eset, with non\-zero values interpreted as true\&. +.RE +.PP +\eset \fIvarname\fR \fIexpression\fR +.RS 4 +Sets variable +\fIvarname\fR +to a value calculated from +\fIexpression\fR\&. The expression may contain the +NULL +constant, Boolean constants +TRUE +and +FALSE, integer constants such as +5432, double constants such as +3\&.14159, references to variables +:\fIvariablename\fR, +operators +with their usual SQL precedence and associativity, +function calls, SQL +CASE generic conditional expressions +and parentheses\&. +.sp +Functions and most operators return +NULL +on +NULL +input\&. +.sp +For conditional purposes, non zero numerical values are +TRUE, zero numerical values and +NULL +are +FALSE\&. +.sp +Too large or small integer and double constants, as well as integer arithmetic operators (+, +\-, +* +and +/) raise errors on overflows\&. +.sp +When no final +ELSE +clause is provided to a +CASE, the default value is +NULL\&. +.sp +Examples: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\eset ntellers 10 * :scale +\eset aid (1021 * random(1, 100000 * :scale)) % \e + (100000 * :scale) + 1 +\eset divx CASE WHEN :x <> 0 THEN :y/:x ELSE NULL END +.fi +.if n \{\ +.RE +.\} +.RE +.PP +\esleep \fInumber\fR [ us | ms | s ] +.RS 4 +Causes script execution to sleep for the specified duration in microseconds (us), milliseconds (ms) or seconds (s)\&. If the unit is omitted then seconds are the default\&. +\fInumber\fR +can be either an integer constant or a +:\fIvariablename\fR +reference to a variable having an integer value\&. +.sp +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\esleep 10 ms +.fi +.if n \{\ +.RE +.\} +.RE +.PP +\esetshell \fIvarname\fR \fIcommand\fR [ \fIargument\fR \&.\&.\&. ] +.RS 4 +Sets variable +\fIvarname\fR +to the result of the shell command +\fIcommand\fR +with the given +\fIargument\fR(s)\&. The command must return an integer value through its standard output\&. +.sp +\fIcommand\fR +and each +\fIargument\fR +can be either a text constant or a +:\fIvariablename\fR +reference to a variable\&. If you want to use an +\fIargument\fR +starting with a colon, write an additional colon at the beginning of +\fIargument\fR\&. +.sp +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\esetshell variable_to_be_assigned command literal_argument :variable ::literal_starting_with_colon +.fi +.if n \{\ +.RE +.\} +.RE +.PP +\eshell \fIcommand\fR [ \fIargument\fR \&.\&.\&. ] +.RS 4 +Same as +\esetshell, but the result of the command is discarded\&. +.sp +Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\eshell command literal_argument :variable ::literal_starting_with_colon +.fi +.if n \{\ +.RE +.\} +.RE +.PP +\estartpipeline +.br +\eendpipeline +.RS 4 +These commands delimit the start and end of a pipeline of SQL statements\&. In pipeline mode, statements are sent to the server without waiting for the results of previous statements\&. See +Section\ \&34.5 +for more details\&. Pipeline mode requires the use of extended query protocol\&. +.RE +.SS "Built\-in Operators" +.PP +The arithmetic, bitwise, comparison and logical operators listed in +Table\ \&289 +are built into +pgbench +and may be used in expressions appearing in +\eset\&. The operators are listed in increasing precedence order\&. Except as noted, operators taking two numeric inputs will produce a double value if either input is double, otherwise they produce an integer result\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&289.\ \&pgbench Operators +.TS +allbox tab(:); +lB. +T{ +.PP +Operator + + .PP +Description + + .PP +Example(s) +T} +.T& +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l. +T{ +.PP +\fIboolean\fR +OR +\fIboolean\fR +→ \fIboolean\fR + + .PP +Logical OR + + .PP +5 or 0 +→ TRUE +T} +T{ +.PP +\fIboolean\fR +AND +\fIboolean\fR +→ \fIboolean\fR + + .PP +Logical AND + + .PP +3 and 0 +→ FALSE +T} +T{ +.PP +NOT +\fIboolean\fR +→ \fIboolean\fR + + .PP +Logical NOT + + .PP +not false +→ TRUE +T} +T{ +.PP +\fIboolean\fR +IS [NOT] (NULL|TRUE|FALSE) +→ \fIboolean\fR + + .PP +Boolean value tests + + .PP +1 is null +→ FALSE +T} +T{ +.PP +\fIvalue\fR +ISNULL|NOTNULL +→ \fIboolean\fR + + .PP +Nullness tests + + .PP +1 notnull +→ TRUE +T} +T{ +.PP +\fInumber\fR += +\fInumber\fR +→ \fIboolean\fR + + .PP +Equal + + .PP +5 = 4 +→ FALSE +T} +T{ +.PP +\fInumber\fR +<> +\fInumber\fR +→ \fIboolean\fR + + .PP +Not equal + + .PP +5 <> 4 +→ TRUE +T} +T{ +.PP +\fInumber\fR +!= +\fInumber\fR +→ \fIboolean\fR + + .PP +Not equal + + .PP +5 != 5 +→ FALSE +T} +T{ +.PP +\fInumber\fR +< +\fInumber\fR +→ \fIboolean\fR + + .PP +Less than + + .PP +5 < 4 +→ FALSE +T} +T{ +.PP +\fInumber\fR +<= +\fInumber\fR +→ \fIboolean\fR + + .PP +Less than or equal to + + .PP +5 <= 4 +→ FALSE +T} +T{ +.PP +\fInumber\fR +> +\fInumber\fR +→ \fIboolean\fR + + .PP +Greater than + + .PP +5 > 4 +→ TRUE +T} +T{ +.PP +\fInumber\fR +>= +\fInumber\fR +→ \fIboolean\fR + + .PP +Greater than or equal to + + .PP +5 >= 4 +→ TRUE +T} +T{ +.PP +\fIinteger\fR +| +\fIinteger\fR +→ \fIinteger\fR + + .PP +Bitwise OR + + .PP +1 | 2 +→ 3 +T} +T{ +.PP +\fIinteger\fR +# +\fIinteger\fR +→ \fIinteger\fR + + .PP +Bitwise XOR + + .PP +1 # 3 +→ 2 +T} +T{ +.PP +\fIinteger\fR +& +\fIinteger\fR +→ \fIinteger\fR + + .PP +Bitwise AND + + .PP +1 & 3 +→ 1 +T} +T{ +.PP +~ +\fIinteger\fR +→ \fIinteger\fR + + .PP +Bitwise NOT + + .PP +~ 1 +→ \-2 +T} +T{ +.PP +\fIinteger\fR +<< +\fIinteger\fR +→ \fIinteger\fR + + .PP +Bitwise shift left + + .PP +1 << 2 +→ 4 +T} +T{ +.PP +\fIinteger\fR +>> +\fIinteger\fR +→ \fIinteger\fR + + .PP +Bitwise shift right + + .PP +8 >> 2 +→ 2 +T} +T{ +.PP +\fInumber\fR ++ +\fInumber\fR +→ \fInumber\fR + + .PP +Addition + + .PP +5 + 4 +→ 9 +T} +T{ +.PP +\fInumber\fR +\- +\fInumber\fR +→ \fInumber\fR + + .PP +Subtraction + + .PP +3 \- 2\&.0 +→ 1\&.0 +T} +T{ +.PP +\fInumber\fR +* +\fInumber\fR +→ \fInumber\fR + + .PP +Multiplication + + .PP +5 * 4 +→ 20 +T} +T{ +.PP +\fInumber\fR +/ +\fInumber\fR +→ \fInumber\fR + + .PP +Division (truncates the result towards zero if both inputs are integers) + + .PP +5 / 3 +→ 1 +T} +T{ +.PP +\fIinteger\fR +% +\fIinteger\fR +→ \fIinteger\fR + + .PP +Modulo (remainder) + + .PP +3 % 2 +→ 1 +T} +T{ +.PP +\- +\fInumber\fR +→ \fInumber\fR + + .PP +Negation + + .PP +\- 2\&.0 +→ \-2\&.0 +T} +.TE +.sp 1 +.SS "Built\-In Functions" +.PP +The functions listed in +Table\ \&290 +are built into +pgbench +and may be used in expressions appearing in +\eset\&. +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&290.\ \&pgbench Functions +.TS +allbox tab(:); +lB. +T{ +.PP +Function + + .PP +Description + + .PP +Example(s) +T} +.T& +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l +l. +T{ +.PP +\fBabs\fR +( +\fInumber\fR +) +→ +same type as input + + .PP +Absolute value + + .PP +abs(\-17) +→ 17 +T} +T{ +.PP +\fBdebug\fR +( +\fInumber\fR +) +→ +same type as input + + .PP +Prints the argument to +stderr, and returns the argument\&. + + .PP +debug(5432\&.1) +→ 5432\&.1 +T} +T{ +.PP +\fBdouble\fR +( +\fInumber\fR +) +→ double + + .PP +Casts to double\&. + + .PP +double(5432) +→ 5432\&.0 +T} +T{ +.PP +\fBexp\fR +( +\fInumber\fR +) +→ double + + .PP +Exponential (e +raised to the given power) + + .PP +exp(1\&.0) +→ 2\&.718281828459045 +T} +T{ +.PP +\fBgreatest\fR +( +\fInumber\fR +[, \&.\&.\&. ] +) +→ +double +if any argument is double, else +integer + + .PP +Selects the largest value among the arguments\&. + + .PP +greatest(5, 4, 3, 2) +→ 5 +T} +T{ +.PP +\fBhash\fR +( +\fIvalue\fR +[, \fIseed\fR ] +) +→ integer + + .PP +This is an alias for +\fBhash_murmur2\fR\&. + + .PP +hash(10, 5432) +→ \-5817877081768721676 +T} +T{ +.PP +\fBhash_fnv1a\fR +( +\fIvalue\fR +[, \fIseed\fR ] +) +→ integer + + .PP +Computes +\m[blue]\fBFNV\-1a hash\fR\m[]\&. + + .PP +hash_fnv1a(10, 5432) +→ \-7793829335365542153 +T} +T{ +.PP +\fBhash_murmur2\fR +( +\fIvalue\fR +[, \fIseed\fR ] +) +→ integer + + .PP +Computes +\m[blue]\fBMurmurHash2 hash\fR\m[]\&. + + .PP +hash_murmur2(10, 5432) +→ \-5817877081768721676 +T} +T{ +.PP +\fBint\fR +( +\fInumber\fR +) +→ integer + + .PP +Casts to integer\&. + + .PP +int(5\&.4 + 3\&.8) +→ 9 +T} +T{ +.PP +\fBleast\fR +( +\fInumber\fR +[, \&.\&.\&. ] +) +→ +double +if any argument is double, else +integer + + .PP +Selects the smallest value among the arguments\&. + + .PP +least(5, 4, 3, 2\&.1) +→ 2\&.1 +T} +T{ +.PP +\fBln\fR +( +\fInumber\fR +) +→ double + + .PP +Natural logarithm + + .PP +ln(2\&.718281828459045) +→ 1\&.0 +T} +T{ +.PP +\fBmod\fR +( +\fIinteger\fR, +\fIinteger\fR +) +→ integer + + .PP +Modulo (remainder) + + .PP +mod(54, 32) +→ 22 +T} +T{ +.PP +\fBpermute\fR +( +\fIi\fR, +\fIsize\fR +[, +\fIseed\fR +] ) +→ integer + + .PP +Permuted value of +\fIi\fR, in the range +[0, size)\&. This is the new position of +\fIi\fR +(modulo +\fIsize\fR) in a pseudorandom permutation of the integers +0\&.\&.\&.size\-1, parameterized by +\fIseed\fR, see below\&. + + .PP +permute(0, 4) +→ an integer between 0 and 3 +T} +T{ +.PP +\fBpi\fR +() +→ double + + .PP +Approximate value of +π + + .PP +pi() +→ 3\&.14159265358979323846 +T} +T{ +.PP +\fBpow\fR +( +\fIx\fR, +\fIy\fR +) +→ double + + .PP +\fBpower\fR +( +\fIx\fR, +\fIy\fR +) +→ double + + .PP +\fIx\fR +raised to the power of +\fIy\fR + + .PP +pow(2\&.0, 10) +→ 1024\&.0 +T} +T{ +.PP +\fBrandom\fR +( +\fIlb\fR, +\fIub\fR +) +→ integer + + .PP +Computes a uniformly\-distributed random integer in +[lb, ub]\&. + + .PP +random(1, 10) +→ an integer between 1 and 10 +T} +T{ +.PP +\fBrandom_exponential\fR +( +\fIlb\fR, +\fIub\fR, +\fIparameter\fR +) +→ integer + + .PP +Computes an exponentially\-distributed random integer in +[lb, ub], see below\&. + + .PP +random_exponential(1, 10, 3\&.0) +→ an integer between 1 and 10 +T} +T{ +.PP +\fBrandom_gaussian\fR +( +\fIlb\fR, +\fIub\fR, +\fIparameter\fR +) +→ integer + + .PP +Computes a Gaussian\-distributed random integer in +[lb, ub], see below\&. + + .PP +random_gaussian(1, 10, 2\&.5) +→ an integer between 1 and 10 +T} +T{ +.PP +\fBrandom_zipfian\fR +( +\fIlb\fR, +\fIub\fR, +\fIparameter\fR +) +→ integer + + .PP +Computes a Zipfian\-distributed random integer in +[lb, ub], see below\&. + + .PP +random_zipfian(1, 10, 1\&.5) +→ an integer between 1 and 10 +T} +T{ +.PP +\fBsqrt\fR +( +\fInumber\fR +) +→ double + + .PP +Square root + + .PP +sqrt(2\&.0) +→ 1\&.414213562 +T} +.TE +.sp 1 +.PP +The +random +function generates values using a uniform distribution, that is all the values are drawn within the specified range with equal probability\&. The +random_exponential, +random_gaussian +and +random_zipfian +functions require an additional double parameter which determines the precise shape of the distribution\&. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +For an exponential distribution, +\fIparameter\fR +controls the distribution by truncating a quickly\-decreasing exponential distribution at +\fIparameter\fR, and then projecting onto integers between the bounds\&. To be precise, with +.sp +.if n \{\ +.RS 4 +.\} +.nf +f(x) = exp(\-parameter * (x \- min) / (max \- min + 1)) / (1 \- exp(\-parameter)) +.fi +.if n \{\ +.RE +.\} +.sp +Then value +\fIi\fR +between +\fImin\fR +and +\fImax\fR +inclusive is drawn with probability: +f(i) \- f(i + 1)\&. +.sp +Intuitively, the larger the +\fIparameter\fR, the more frequently values close to +\fImin\fR +are accessed, and the less frequently values close to +\fImax\fR +are accessed\&. The closer to 0 +\fIparameter\fR +is, the flatter (more uniform) the access distribution\&. A crude approximation of the distribution is that the most frequent 1% values in the range, close to +\fImin\fR, are drawn +\fIparameter\fR% of the time\&. The +\fIparameter\fR +value must be strictly positive\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +For a Gaussian distribution, the interval is mapped onto a standard normal distribution (the classical bell\-shaped Gaussian curve) truncated at +\-parameter +on the left and ++parameter +on the right\&. Values in the middle of the interval are more likely to be drawn\&. To be precise, if +PHI(x) +is the cumulative distribution function of the standard normal distribution, with mean +mu +defined as +(max + min) / 2\&.0, with +.sp +.if n \{\ +.RS 4 +.\} +.nf +f(x) = PHI(2\&.0 * parameter * (x \- mu) / (max \- min + 1)) / + (2\&.0 * PHI(parameter) \- 1) +.fi +.if n \{\ +.RE +.\} +.sp +then value +\fIi\fR +between +\fImin\fR +and +\fImax\fR +inclusive is drawn with probability: +f(i + 0\&.5) \- f(i \- 0\&.5)\&. Intuitively, the larger the +\fIparameter\fR, the more frequently values close to the middle of the interval are drawn, and the less frequently values close to the +\fImin\fR +and +\fImax\fR +bounds\&. About 67% of values are drawn from the middle +1\&.0 / parameter, that is a relative +0\&.5 / parameter +around the mean, and 95% in the middle +2\&.0 / parameter, that is a relative +1\&.0 / parameter +around the mean; for instance, if +\fIparameter\fR +is 4\&.0, 67% of values are drawn from the middle quarter (1\&.0 / 4\&.0) of the interval (i\&.e\&., from +3\&.0 / 8\&.0 +to +5\&.0 / 8\&.0) and 95% from the middle half (2\&.0 / 4\&.0) of the interval (second and third quartiles)\&. The minimum allowed +\fIparameter\fR +value is 2\&.0\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +random_zipfian +generates a bounded Zipfian distribution\&. +\fIparameter\fR +defines how skewed the distribution is\&. The larger the +\fIparameter\fR, the more frequently values closer to the beginning of the interval are drawn\&. The distribution is such that, assuming the range starts from 1, the ratio of the probability of drawing +\fIk\fR +versus drawing +\fIk+1\fR +is +((\fIk\fR+1)/\fIk\fR)**\fIparameter\fR\&. For example, +random_zipfian(1, \&.\&.\&., 2\&.5) +produces the value +1 +about +(2/1)**2\&.5 = 5\&.66 +times more frequently than +2, which itself is produced +(3/2)**2\&.5 = 2\&.76 +times more frequently than +3, and so on\&. +.sp +pgbench\*(Aqs implementation is based on "Non\-Uniform Random Variate Generation", Luc Devroye, p\&. 550\-551, Springer 1986\&. Due to limitations of that algorithm, the +\fIparameter\fR +value is restricted to the range [1\&.001, 1000]\&. +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +When designing a benchmark which selects rows non\-uniformly, be aware that the rows chosen may be correlated with other data such as IDs from a sequence or the physical row ordering, which may skew performance measurements\&. +.PP +To avoid this, you may wish to use the +\fBpermute\fR +function, or some other additional step with similar effect, to shuffle the selected rows and remove such correlations\&. +.sp .5v +.RE +.PP +Hash functions +hash, +hash_murmur2 +and +hash_fnv1a +accept an input value and an optional seed parameter\&. In case the seed isn\*(Aqt provided the value of +:default_seed +is used, which is initialized randomly unless set by the command\-line +\-D +option\&. +.PP +permute +accepts an input value, a size, and an optional seed parameter\&. It generates a pseudorandom permutation of integers in the range +[0, size), and returns the index of the input value in the permuted values\&. The permutation chosen is parameterized by the seed, which defaults to +:default_seed, if not specified\&. Unlike the hash functions, +permute +ensures that there are no collisions or holes in the output values\&. Input values outside the interval are interpreted modulo the size\&. The function raises an error if the size is not positive\&. +\fBpermute\fR +can be used to scatter the distribution of non\-uniform random functions such as +random_zipfian +or +random_exponential +so that values drawn more often are not trivially correlated\&. For instance, the following +pgbench +script simulates a possible real world workload typical for social media and blogging platforms where a few accounts generate excessive load: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\eset size 1000000 +\eset r random_zipfian(1, :size, 1\&.07) +\eset k 1 + permute(:r, :size) +.fi +.if n \{\ +.RE +.\} +.sp +In some cases several distinct distributions are needed which don\*(Aqt correlate with each other and this is when the optional seed parameter comes in handy: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\eset k1 1 + permute(:r, :size, :default_seed + 123) +\eset k2 1 + permute(:r, :size, :default_seed + 321) +.fi +.if n \{\ +.RE +.\} +.sp +A similar behavior can also be approximated with +\fBhash\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\eset size 1000000 +\eset r random_zipfian(1, 100 * :size, 1\&.07) +\eset k 1 + abs(hash(:r)) % :size +.fi +.if n \{\ +.RE +.\} +.sp +However, since +\fBhash\fR +generates collisions, some values will not be reachable and others will be more frequent than expected from the original distribution\&. +.PP +As an example, the full definition of the built\-in TPC\-B\-like transaction is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\eset aid random(1, 100000 * :scale) +\eset bid random(1, 1 * :scale) +\eset tid random(1, 10 * :scale) +\eset delta random(\-5000, 5000) +BEGIN; +UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; +SELECT abalance FROM pgbench_accounts WHERE aid = :aid; +UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; +UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; +INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); +END; +.fi +.if n \{\ +.RE +.\} +.sp +This script allows each iteration of the transaction to reference different, randomly\-chosen rows\&. (This example also shows why it\*(Aqs important for each client session to have its own variables \(em otherwise they\*(Aqd not be independently touching different rows\&.) +.SS "Per\-Transaction Logging" +.PP +With the +\fB\-l\fR +option (but without the +\fB\-\-aggregate\-interval\fR +option), +pgbench +writes information about each transaction to a log file\&. The log file will be named +\fIprefix\fR\&.\fInnn\fR, where +\fIprefix\fR +defaults to +pgbench_log, and +\fInnn\fR +is the PID of the +pgbench +process\&. The prefix can be changed by using the +\fB\-\-log\-prefix\fR +option\&. If the +\fB\-j\fR +option is 2 or higher, so that there are multiple worker threads, each will have its own log file\&. The first worker will use the same name for its log file as in the standard single worker case\&. The additional log files for the other workers will be named +\fIprefix\fR\&.\fInnn\fR\&.\fImmm\fR, where +\fImmm\fR +is a sequential number for each worker starting with 1\&. +.PP +Each line in a log file describes one transaction\&. It contains the following space\-separated fields: +.PP +\fIclient_id\fR +.RS 4 +identifies the client session that ran the transaction +.RE +.PP +\fItransaction_no\fR +.RS 4 +counts how many transactions have been run by that session +.RE +.PP +\fItime\fR +.RS 4 +transaction\*(Aqs elapsed time, in microseconds +.RE +.PP +\fIscript_no\fR +.RS 4 +identifies the script file that was used for the transaction (useful when multiple scripts are specified with +\fB\-f\fR +or +\fB\-b\fR) +.RE +.PP +\fItime_epoch\fR +.RS 4 +transaction\*(Aqs completion time, as a Unix\-epoch time stamp +.RE +.PP +\fItime_us\fR +.RS 4 +fractional\-second part of transaction\*(Aqs completion time, in microseconds +.RE +.PP +\fIschedule_lag\fR +.RS 4 +transaction start delay, that is the difference between the transaction\*(Aqs scheduled start time and the time it actually started, in microseconds (present only if +\fB\-\-rate\fR +is specified) +.RE +.PP +\fIretries\fR +.RS 4 +count of retries after serialization or deadlock errors during the transaction (present only if +\fB\-\-max\-tries\fR +is not equal to one) +.RE +.PP +When both +\fB\-\-rate\fR +and +\fB\-\-latency\-limit\fR +are used, the +\fItime\fR +for a skipped transaction will be reported as +skipped\&. If the transaction ends with a failure, its +\fItime\fR +will be reported as +failed\&. If you use the +\fB\-\-failures\-detailed\fR +option, the +\fItime\fR +of the failed transaction will be reported as +serialization +or +deadlock +depending on the type of failure (see +Failures and Serialization/Deadlock Retries +for more information)\&. +.PP +Here is a snippet of a log file generated in a single\-client run: +.sp +.if n \{\ +.RS 4 +.\} +.nf +0 199 2241 0 1175850568 995598 +0 200 2465 0 1175850568 998079 +0 201 2513 0 1175850569 608 +0 202 2038 0 1175850569 2663 +.fi +.if n \{\ +.RE +.\} +.sp +Another example with +\-\-rate=100 +and +\-\-latency\-limit=5 +(note the additional +\fIschedule_lag\fR +column): +.sp +.if n \{\ +.RS 4 +.\} +.nf +0 81 4621 0 1412881037 912698 3005 +0 82 6173 0 1412881037 914578 4304 +0 83 skipped 0 1412881037 914578 5217 +0 83 skipped 0 1412881037 914578 5099 +0 83 4722 0 1412881037 916203 3108 +0 84 4142 0 1412881037 918023 2333 +0 85 2465 0 1412881037 919759 740 +.fi +.if n \{\ +.RE +.\} +.sp +In this example, transaction 82 was late, because its latency (6\&.173 ms) was over the 5 ms limit\&. The next two transactions were skipped, because they were already late before they were even started\&. +.PP +The following example shows a snippet of a log file with failures and retries, with the maximum number of tries set to 10 (note the additional +\fIretries\fR +column): +.sp +.if n \{\ +.RS 4 +.\} +.nf +3 0 47423 0 1499414498 34501 3 +3 1 8333 0 1499414498 42848 0 +3 2 8358 0 1499414498 51219 0 +4 0 72345 0 1499414498 59433 6 +1 3 41718 0 1499414498 67879 4 +1 4 8416 0 1499414498 76311 0 +3 3 33235 0 1499414498 84469 3 +0 0 failed 0 1499414498 84905 9 +2 0 failed 0 1499414498 86248 9 +3 4 8307 0 1499414498 92788 0 +.fi +.if n \{\ +.RE +.\} +.PP +If the +\fB\-\-failures\-detailed\fR +option is used, the type of failure is reported in the +\fItime\fR +like this: +.sp +.if n \{\ +.RS 4 +.\} +.nf +3 0 47423 0 1499414498 34501 3 +3 1 8333 0 1499414498 42848 0 +3 2 8358 0 1499414498 51219 0 +4 0 72345 0 1499414498 59433 6 +1 3 41718 0 1499414498 67879 4 +1 4 8416 0 1499414498 76311 0 +3 3 33235 0 1499414498 84469 3 +0 0 serialization 0 1499414498 84905 9 +2 0 serialization 0 1499414498 86248 9 +3 4 8307 0 1499414498 92788 0 +.fi +.if n \{\ +.RE +.\} +.PP +When running a long test on hardware that can handle a lot of transactions, the log files can become very large\&. The +\fB\-\-sampling\-rate\fR +option can be used to log only a random sample of transactions\&. +.SS "Aggregated Logging" +.PP +With the +\fB\-\-aggregate\-interval\fR +option, a different format is used for the log files\&. Each log line describes one aggregation interval\&. It contains the following space\-separated fields: +.PP +\fIinterval_start\fR +.RS 4 +start time of the interval, as a Unix\-epoch time stamp +.RE +.PP +\fInum_transactions\fR +.RS 4 +number of transactions within the interval +.RE +.PP +\fIsum_latency\fR +.RS 4 +sum of transaction latencies +.RE +.PP +\fIsum_latency_2\fR +.RS 4 +sum of squares of transaction latencies +.RE +.PP +\fImin_latency\fR +.RS 4 +minimum transaction latency +.RE +.PP +\fImax_latency\fR +.RS 4 +maximum transaction latency +.RE +.PP +\fIsum_lag\fR +.RS 4 +sum of transaction start delays (zero unless +\fB\-\-rate\fR +is specified) +.RE +.PP +\fIsum_lag_2\fR +.RS 4 +sum of squares of transaction start delays (zero unless +\fB\-\-rate\fR +is specified) +.RE +.PP +\fImin_lag\fR +.RS 4 +minimum transaction start delay (zero unless +\fB\-\-rate\fR +is specified) +.RE +.PP +\fImax_lag\fR +.RS 4 +maximum transaction start delay (zero unless +\fB\-\-rate\fR +is specified) +.RE +.PP +\fIskipped\fR +.RS 4 +number of transactions skipped because they would have started too late (zero unless +\fB\-\-rate\fR +and +\fB\-\-latency\-limit\fR +are specified) +.RE +.PP +\fIretried\fR +.RS 4 +number of retried transactions (zero unless +\fB\-\-max\-tries\fR +is not equal to one) +.RE +.PP +\fIretries\fR +.RS 4 +number of retries after serialization or deadlock errors (zero unless +\fB\-\-max\-tries\fR +is not equal to one) +.RE +.PP +\fIserialization_failures\fR +.RS 4 +number of transactions that got a serialization error and were not retried afterwards (zero unless +\fB\-\-failures\-detailed\fR +is specified) +.RE +.PP +\fIdeadlock_failures\fR +.RS 4 +number of transactions that got a deadlock error and were not retried afterwards (zero unless +\fB\-\-failures\-detailed\fR +is specified) +.RE +.PP +Here is some example output generated with these options: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBpgbench \-\-aggregate\-interval=10 \-\-time=20 \-\-client=10 \-\-log \-\-rate=1000 \-\-latency\-limit=10 \-\-failures\-detailed \-\-max\-tries=10 test\fR + +1650260552 5178 26171317 177284491527 1136 44462 2647617 7321113867 0 9866 64 7564 28340 4148 0 +1650260562 4808 25573984 220121792172 1171 62083 3037380 9666800914 0 9998 598 7392 26621 4527 0 +.fi +.if n \{\ +.RE +.\} +.PP +Notice that while the plain (unaggregated) log format shows which script was used for each transaction, the aggregated format does not\&. Therefore if you need per\-script data, you need to aggregate the data on your own\&. +.SS "Per\-Statement Report" +.PP +With the +\fB\-r\fR +option, +pgbench +collects the following statistics for each statement: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +latency +\(em elapsed transaction time for each statement\&. +pgbench +reports an average value of all successful runs of the statement\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The number of failures in this statement\&. See +Failures and Serialization/Deadlock Retries +for more information\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The number of retries after a serialization or a deadlock error in this statement\&. See +Failures and Serialization/Deadlock Retries +for more information\&. +.RE +.PP +The report displays retry statistics only if the +\fB\-\-max\-tries\fR +option is not equal to 1\&. +.PP +All values are computed for each statement executed by every client and are reported after the benchmark has finished\&. +.PP +For the default script, the output will look similar to this: +.sp +.if n \{\ +.RS 4 +.\} +.nf +starting vacuum\&.\&.\&.end\&. +transaction type: <builtin: TPC\-B (sort of)> +scaling factor: 1 +query mode: simple +number of clients: 10 +number of threads: 1 +maximum number of tries: 1 +number of transactions per client: 1000 +number of transactions actually processed: 10000/10000 +number of failed transactions: 0 (0\&.000%) +number of transactions above the 50\&.0 ms latency limit: 1311/10000 (13\&.110 %) +latency average = 28\&.488 ms +latency stddev = 21\&.009 ms +initial connection time = 69\&.068 ms +tps = 346\&.224794 (without initial connection time) +statement latencies in milliseconds and failures: + 0\&.012 0 \eset aid random(1, 100000 * :scale) + 0\&.002 0 \eset bid random(1, 1 * :scale) + 0\&.002 0 \eset tid random(1, 10 * :scale) + 0\&.002 0 \eset delta random(\-5000, 5000) + 0\&.319 0 BEGIN; + 0\&.834 0 UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; + 0\&.641 0 SELECT abalance FROM pgbench_accounts WHERE aid = :aid; + 11\&.126 0 UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; + 12\&.961 0 UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; + 0\&.634 0 INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); + 1\&.957 0 END; +.fi +.if n \{\ +.RE +.\} +.sp +Another example of output for the default script using serializable default transaction isolation level (\fBPGOPTIONS=\*(Aq\-c default_transaction_isolation=serializable\*(Aq pgbench \&.\&.\&.\fR): +.sp +.if n \{\ +.RS 4 +.\} +.nf +starting vacuum\&.\&.\&.end\&. +transaction type: <builtin: TPC\-B (sort of)> +scaling factor: 1 +query mode: simple +number of clients: 10 +number of threads: 1 +maximum number of tries: 10 +number of transactions per client: 1000 +number of transactions actually processed: 6317/10000 +number of failed transactions: 3683 (36\&.830%) +number of transactions retried: 7667 (76\&.670%) +total number of retries: 45339 +number of transactions above the 50\&.0 ms latency limit: 106/6317 (1\&.678 %) +latency average = 17\&.016 ms +latency stddev = 13\&.283 ms +initial connection time = 45\&.017 ms +tps = 186\&.792667 (without initial connection time) +statement latencies in milliseconds, failures and retries: + 0\&.006 0 0 \eset aid random(1, 100000 * :scale) + 0\&.001 0 0 \eset bid random(1, 1 * :scale) + 0\&.001 0 0 \eset tid random(1, 10 * :scale) + 0\&.001 0 0 \eset delta random(\-5000, 5000) + 0\&.385 0 0 BEGIN; + 0\&.773 0 1 UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; + 0\&.624 0 0 SELECT abalance FROM pgbench_accounts WHERE aid = :aid; + 1\&.098 320 3762 UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; + 0\&.582 3363 41576 UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; + 0\&.465 0 0 INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); + 1\&.933 0 0 END; +.fi +.if n \{\ +.RE +.\} +.PP +If multiple script files are specified, all statistics are reported separately for each script file\&. +.PP +Note that collecting the additional timing information needed for per\-statement latency computation adds some overhead\&. This will slow average execution speed and lower the computed TPS\&. The amount of slowdown varies significantly depending on platform and hardware\&. Comparing average TPS values with and without latency reporting enabled is a good way to measure if the timing overhead is significant\&. +.SS "Failures and Serialization/Deadlock Retries" +.PP +When executing +pgbench, there are three main types of errors: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Errors of the main program\&. They are the most serious and always result in an immediate exit from +pgbench +with the corresponding error message\&. They include: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +errors at the beginning of +pgbench +(e\&.g\&. an invalid option value); +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +errors in the initialization mode (e\&.g\&. the query to create tables for built\-in scripts fails); +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +errors before starting threads (e\&.g\&. could not connect to the database server, syntax error in the meta command, thread creation failure); +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +internal +pgbench +errors (which are supposed to never occur\&.\&.\&.)\&. +.RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Errors when the thread manages its clients (e\&.g\&. the client could not start a connection to the database server / the socket for connecting the client to the database server has become invalid)\&. In such cases all clients of this thread stop while other threads continue to work\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Direct client errors\&. They lead to immediate exit from +pgbench +with the corresponding error message only in the case of an internal +pgbench +error (which are supposed to never occur\&.\&.\&.)\&. Otherwise in the worst case they only lead to the abortion of the failed client while other clients continue their run (but some client errors are handled without an abortion of the client and reported separately, see below)\&. Later in this section it is assumed that the discussed errors are only the direct client errors and they are not internal +pgbench +errors\&. +.RE +.PP +A client\*(Aqs run is aborted in case of a serious error; for example, the connection with the database server was lost or the end of script was reached without completing the last transaction\&. In addition, if execution of an SQL or meta command fails for reasons other than serialization or deadlock errors, the client is aborted\&. Otherwise, if an SQL command fails with serialization or deadlock errors, the client is not aborted\&. In such cases, the current transaction is rolled back, which also includes setting the client variables as they were before the run of this transaction (it is assumed that one transaction script contains only one transaction; see +What Is the "Transaction" Actually Performed in pgbench? +for more information)\&. Transactions with serialization or deadlock errors are repeated after rollbacks until they complete successfully or reach the maximum number of tries (specified by the +\fB\-\-max\-tries\fR +option) / the maximum time of retries (specified by the +\fB\-\-latency\-limit\fR +option) / the end of benchmark (specified by the +\fB\-\-time\fR +option)\&. If the last trial run fails, this transaction will be reported as failed but the client is not aborted and continues to work\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +Without specifying the +\fB\-\-max\-tries\fR +option, a transaction will never be retried after a serialization or deadlock error because its default value is 1\&. Use an unlimited number of tries (\-\-max\-tries=0) and the +\fB\-\-latency\-limit\fR +option to limit only the maximum time of tries\&. You can also use the +\fB\-\-time\fR +option to limit the benchmark duration under an unlimited number of tries\&. +.PP +Be careful when repeating scripts that contain multiple transactions: the script is always retried completely, so successful transactions can be performed several times\&. +.PP +Be careful when repeating transactions with shell commands\&. Unlike the results of SQL commands, the results of shell commands are not rolled back, except for the variable value of the +\fB\esetshell\fR +command\&. +.sp .5v +.RE +.PP +The latency of a successful transaction includes the entire time of transaction execution with rollbacks and retries\&. The latency is measured only for successful transactions and commands but not for failed transactions or commands\&. +.PP +The main report contains the number of failed transactions\&. If the +\fB\-\-max\-tries\fR +option is not equal to 1, the main report also contains statistics related to retries: the total number of retried transactions and total number of retries\&. The per\-script report inherits all these fields from the main report\&. The per\-statement report displays retry statistics only if the +\fB\-\-max\-tries\fR +option is not equal to 1\&. +.PP +If you want to group failures by basic types in per\-transaction and aggregation logs, as well as in the main and per\-script reports, use the +\fB\-\-failures\-detailed\fR +option\&. If you also want to distinguish all errors and failures (errors without retrying) by type including which limit for retries was exceeded and how much it was exceeded by for the serialization/deadlock failures, use the +\fB\-\-verbose\-errors\fR +option\&. +.SS "Good Practices" +.PP +It is very easy to use +pgbench +to produce completely meaningless numbers\&. Here are some guidelines to help you get useful results\&. +.PP +In the first place, +\fInever\fR +believe any test that runs for only a few seconds\&. Use the +\fB\-t\fR +or +\fB\-T\fR +option to make the run last at least a few minutes, so as to average out noise\&. In some cases you could need hours to get numbers that are reproducible\&. It\*(Aqs a good idea to try the test run a few times, to find out if your numbers are reproducible or not\&. +.PP +For the default TPC\-B\-like test scenario, the initialization scale factor (\fB\-s\fR) should be at least as large as the largest number of clients you intend to test (\fB\-c\fR); else you\*(Aqll mostly be measuring update contention\&. There are only +\fB\-s\fR +rows in the +pgbench_branches +table, and every transaction wants to update one of them, so +\fB\-c\fR +values in excess of +\fB\-s\fR +will undoubtedly result in lots of transactions blocked waiting for other transactions\&. +.PP +The default test scenario is also quite sensitive to how long it\*(Aqs been since the tables were initialized: accumulation of dead rows and dead space in the tables changes the results\&. To understand the results you must keep track of the total number of updates and when vacuuming happens\&. If autovacuum is enabled it can result in unpredictable changes in measured performance\&. +.PP +A limitation of +pgbench +is that it can itself become the bottleneck when trying to test a large number of client sessions\&. This can be alleviated by running +pgbench +on a different machine from the database server, although low network latency will be essential\&. It might even be useful to run several +pgbench +instances concurrently, on several client machines, against the same database server\&. +.SS "Security" +.PP +If untrusted users have access to a database that has not adopted a +secure schema usage pattern, do not run +pgbench +in that database\&. +pgbench +uses unqualified names and does not manipulate the search path\&. diff --git a/doc/src/sgml/man1/postgres.1 b/doc/src/sgml/man1/postgres.1 new file mode 100644 index 0000000..b4e783a --- /dev/null +++ b/doc/src/sgml/man1/postgres.1 @@ -0,0 +1,631 @@ +'\" t +.\" Title: postgres +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "POSTGRES" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +postgres \- PostgreSQL database server +.SH "SYNOPSIS" +.HP \w'\fBpostgres\fR\ 'u +\fBpostgres\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +\fBpostgres\fR +is the +PostgreSQL +database server\&. In order for a client application to access a database it connects (over a network or locally) to a running +\fBpostgres\fR +instance\&. The +\fBpostgres\fR +instance then starts a separate server process to handle the connection\&. +.PP +One +\fBpostgres\fR +instance always manages the data of exactly one database cluster\&. A database cluster is a collection of databases that is stored at a common file system location (the +\(lqdata area\(rq)\&. More than one +\fBpostgres\fR +instance can run on a system at one time, so long as they use different data areas and different communication ports (see below)\&. When +\fBpostgres\fR +starts it needs to know the location of the data area\&. The location must be specified by the +\fB\-D\fR +option or the +\fBPGDATA\fR +environment variable; there is no default\&. Typically, +\fB\-D\fR +or +\fBPGDATA\fR +points directly to the data area directory created by +\fBinitdb\fR(1)\&. Other possible file layouts are discussed in +Section\ \&20.2\&. +.PP +By default +\fBpostgres\fR +starts in the foreground and prints log messages to the standard error stream\&. In practical applications +\fBpostgres\fR +should be started as a background process, perhaps at boot time\&. +.PP +The +\fBpostgres\fR +command can also be called in single\-user mode\&. The primary use for this mode is during bootstrapping by +\fBinitdb\fR(1)\&. Sometimes it is used for debugging or disaster recovery; note that running a single\-user server is not truly suitable for debugging the server, since no realistic interprocess communication and locking will happen\&. When invoked in single\-user mode from the shell, the user can enter queries and the results will be printed to the screen, but in a form that is more useful for developers than end users\&. In the single\-user mode, the session user will be set to the user with ID 1, and implicit superuser powers are granted to this user\&. This user does not actually have to exist, so the single\-user mode can be used to manually recover from certain kinds of accidental damage to the system catalogs\&. +.SH "OPTIONS" +.PP +\fBpostgres\fR +accepts the following command\-line arguments\&. For a detailed discussion of the options consult +Chapter\ \&20\&. You can save typing most of these options by setting up a configuration file\&. Some (safe) options can also be set from the connecting client in an application\-dependent way to apply only for that session\&. For example, if the environment variable +\fBPGOPTIONS\fR +is set, then +libpq\-based clients will pass that string to the server, which will interpret it as +\fBpostgres\fR +command\-line options\&. +.SS "General Purpose" +.PP +\fB\-B \fR\fB\fInbuffers\fR\fR +.RS 4 +Sets the number of shared buffers for use by the server processes\&. The default value of this parameter is chosen automatically by +initdb\&. Specifying this option is equivalent to setting the +shared_buffers +configuration parameter\&. +.RE +.PP +\fB\-c \fR\fB\fIname\fR\fR\fB=\fR\fB\fIvalue\fR\fR +.RS 4 +Sets a named run\-time parameter\&. The configuration parameters supported by +PostgreSQL +are described in +Chapter\ \&20\&. Most of the other command line options are in fact short forms of such a parameter assignment\&. +\fB\-c\fR +can appear multiple times to set multiple parameters\&. +.RE +.PP +\fB\-C \fR\fB\fIname\fR\fR +.RS 4 +Prints the value of the named run\-time parameter, and exits\&. (See the +\fB\-c\fR +option above for details\&.) This returns values from +postgresql\&.conf, modified by any parameters supplied in this invocation\&. It does not reflect parameters supplied when the cluster was started\&. +.sp +This can be used on a running server for most parameters\&. However, the server must be shut down for some runtime\-computed parameters (e\&.g\&., +shared_memory_size, +shared_memory_size_in_huge_pages, and +wal_segment_size)\&. +.sp +This option is meant for other programs that interact with a server instance, such as +\fBpg_ctl\fR(1), to query configuration parameter values\&. User\-facing applications should instead use +\fBSHOW\fR +or the +pg_settings +view\&. +.RE +.PP +\fB\-d \fR\fB\fIdebug\-level\fR\fR +.RS 4 +Sets the debug level\&. The higher this value is set, the more debugging output is written to the server log\&. Values are from 1 to 5\&. It is also possible to pass +\-d 0 +for a specific session, which will prevent the server log level of the parent +\fBpostgres\fR +process from being propagated to this session\&. +.RE +.PP +\fB\-D \fR\fB\fIdatadir\fR\fR +.RS 4 +Specifies the file system location of the database configuration files\&. See +Section\ \&20.2 +for details\&. +.RE +.PP +\fB\-e\fR +.RS 4 +Sets the default date style to +\(lqEuropean\(rq, that is +DMY +ordering of input date fields\&. This also causes the day to be printed before the month in certain date output formats\&. See +Section\ \&8.5 +for more information\&. +.RE +.PP +\fB\-F\fR +.RS 4 +Disables +\fBfsync\fR +calls for improved performance, at the risk of data corruption in the event of a system crash\&. Specifying this option is equivalent to disabling the +fsync +configuration parameter\&. Read the detailed documentation before using this! +.RE +.PP +\fB\-h \fR\fB\fIhostname\fR\fR +.RS 4 +Specifies the IP host name or address on which +\fBpostgres\fR +is to listen for TCP/IP connections from client applications\&. The value can also be a comma\-separated list of addresses, or +* +to specify listening on all available interfaces\&. An empty value specifies not listening on any IP addresses, in which case only Unix\-domain sockets can be used to connect to the server\&. Defaults to listening only on +localhost\&. Specifying this option is equivalent to setting the +listen_addresses +configuration parameter\&. +.RE +.PP +\fB\-i\fR +.RS 4 +Allows remote clients to connect via TCP/IP (Internet domain) connections\&. Without this option, only local connections are accepted\&. This option is equivalent to setting +\fIlisten_addresses\fR +to +* +in +postgresql\&.conf +or via +\fB\-h\fR\&. +.sp +This option is deprecated since it does not allow access to the full functionality of +listen_addresses\&. It\*(Aqs usually better to set +\fIlisten_addresses\fR +directly\&. +.RE +.PP +\fB\-k \fR\fB\fIdirectory\fR\fR +.RS 4 +Specifies the directory of the Unix\-domain socket on which +\fBpostgres\fR +is to listen for connections from client applications\&. The value can also be a comma\-separated list of directories\&. An empty value specifies not listening on any Unix\-domain sockets, in which case only TCP/IP sockets can be used to connect to the server\&. The default value is normally +/tmp, but that can be changed at build time\&. Specifying this option is equivalent to setting the +unix_socket_directories +configuration parameter\&. +.RE +.PP +\fB\-l\fR +.RS 4 +Enables secure connections using +SSL\&. +PostgreSQL +must have been compiled with support for +SSL +for this option to be available\&. For more information on using +SSL, refer to +Section\ \&19.9\&. +.RE +.PP +\fB\-N \fR\fB\fImax\-connections\fR\fR +.RS 4 +Sets the maximum number of client connections that this server will accept\&. The default value of this parameter is chosen automatically by +initdb\&. Specifying this option is equivalent to setting the +max_connections +configuration parameter\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP/IP port or local Unix domain socket file extension on which +\fBpostgres\fR +is to listen for connections from client applications\&. Defaults to the value of the +\fBPGPORT\fR +environment variable, or if +\fBPGPORT\fR +is not set, then defaults to the value established during compilation (normally 5432)\&. If you specify a port other than the default port, then all client applications must specify the same port using either command\-line options or +\fBPGPORT\fR\&. +.RE +.PP +\fB\-s\fR +.RS 4 +Print time information and other statistics at the end of each command\&. This is useful for benchmarking or for use in tuning the number of buffers\&. +.RE +.PP +\fB\-S\fR \fIwork\-mem\fR +.RS 4 +Specifies the base amount of memory to be used by sorts and hash tables before resorting to temporary disk files\&. See the description of the +\fIwork_mem\fR +configuration parameter in +Section\ \&20.4.1\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +postgres +version and exit\&. +.RE +.PP +\fB\-\-\fR\fB\fIname\fR\fR\fB=\fR\fB\fIvalue\fR\fR +.RS 4 +Sets a named run\-time parameter; a shorter form of +\fB\-c\fR\&. +.RE +.PP +\fB\-\-describe\-config\fR +.RS 4 +This option dumps out the server\*(Aqs internal configuration variables, descriptions, and defaults in tab\-delimited +\fBCOPY\fR +format\&. It is designed primarily for use by administration tools\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +postgres +command line arguments, and exit\&. +.RE +.SS "Semi\-Internal Options" +.PP +The options described here are used mainly for debugging purposes, and in some cases to assist with recovery of severely damaged databases\&. There should be no reason to use them in a production database setup\&. They are listed here only for use by +PostgreSQL +system developers\&. Furthermore, these options might change or be removed in a future release without notice\&. +.PP +\fB\-f\fR { s | i | o | b | t | n | m | h } +.RS 4 +Forbids the use of particular scan and join methods: +s +and +i +disable sequential and index scans respectively, +o, +b +and +t +disable index\-only scans, bitmap index scans, and TID scans respectively, while +n, +m, and +h +disable nested\-loop, merge and hash joins respectively\&. +.sp +Neither sequential scans nor nested\-loop joins can be disabled completely; the +\-fs +and +\-fn +options simply discourage the optimizer from using those plan types if it has any other alternative\&. +.RE +.PP +\fB\-n\fR +.RS 4 +This option is for debugging problems that cause a server process to die abnormally\&. The ordinary strategy in this situation is to notify all other server processes that they must terminate and then reinitialize the shared memory and semaphores\&. This is because an errant server process could have corrupted some shared state before terminating\&. This option specifies that +\fBpostgres\fR +will not reinitialize shared data structures\&. A knowledgeable system programmer can then use a debugger to examine shared memory and semaphore state\&. +.RE +.PP +\fB\-O\fR +.RS 4 +Allows the structure of system tables to be modified\&. This is used by +\fBinitdb\fR\&. +.RE +.PP +\fB\-P\fR +.RS 4 +Ignore system indexes when reading system tables, but still update the indexes when modifying the tables\&. This is useful when recovering from damaged system indexes\&. +.RE +.PP +\fB\-t\fR pa[rser] | pl[anner] | e[xecutor] +.RS 4 +Print timing statistics for each query relating to each of the major system modules\&. This option cannot be used together with the +\fB\-s\fR +option\&. +.RE +.PP +\fB\-T\fR +.RS 4 +This option is for debugging problems that cause a server process to die abnormally\&. The ordinary strategy in this situation is to notify all other server processes that they must terminate and then reinitialize the shared memory and semaphores\&. This is because an errant server process could have corrupted some shared state before terminating\&. This option specifies that +\fBpostgres\fR +will stop all other server processes by sending the signal +SIGSTOP, but will not cause them to terminate\&. This permits system programmers to collect core dumps from all server processes by hand\&. +.RE +.PP +\fB\-v\fR \fIprotocol\fR +.RS 4 +Specifies the version number of the frontend/backend protocol to be used for a particular session\&. This option is for internal use only\&. +.RE +.PP +\fB\-W\fR \fIseconds\fR +.RS 4 +A delay of this many seconds occurs when a new server process is started, after it conducts the authentication procedure\&. This is intended to give an opportunity to attach to the server process with a debugger\&. +.RE +.SS "Options for Single\-User Mode" +.PP +The following options only apply to the single\-user mode (see +Single-User Mode +below)\&. +.PP +\fB\-\-single\fR +.RS 4 +Selects the single\-user mode\&. This must be the first argument on the command line\&. +.RE +.PP +\fIdatabase\fR +.RS 4 +Specifies the name of the database to be accessed\&. This must be the last argument on the command line\&. If it is omitted it defaults to the user name\&. +.RE +.PP +\fB\-E\fR +.RS 4 +Echo all commands to standard output before executing them\&. +.RE +.PP +\fB\-j\fR +.RS 4 +Use semicolon followed by two newlines, rather than just newline, as the command entry terminator\&. +.RE +.PP +\fB\-r\fR \fIfilename\fR +.RS 4 +Send all server log output to +\fIfilename\fR\&. This option is only honored when supplied as a command\-line option\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGCLIENTENCODING\fR +.RS 4 +Default character encoding used by clients\&. (The clients can override this individually\&.) This value can also be set in the configuration file\&. +.RE +.PP +\fBPGDATA\fR +.RS 4 +Default data directory location +.RE +.PP +\fBPGDATESTYLE\fR +.RS 4 +Default value of the +DateStyle +run\-time parameter\&. (The use of this environment variable is deprecated\&.) +.RE +.PP +\fBPGPORT\fR +.RS 4 +Default port number (preferably set in the configuration file) +.RE +.SH "DIAGNOSTICS" +.PP +A failure message mentioning +semget +or +shmget +probably indicates you need to configure your kernel to provide adequate shared memory and semaphores\&. For more discussion see +Section\ \&19.4\&. You might be able to postpone reconfiguring your kernel by decreasing +shared_buffers +to reduce the shared memory consumption of +PostgreSQL, and/or by reducing +max_connections +to reduce the semaphore consumption\&. +.PP +A failure message suggesting that another server is already running should be checked carefully, for example by using the command +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBps ax | grep postgres\fR +.fi +.if n \{\ +.RE +.\} +.sp +or +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBps \-ef | grep postgres\fR +.fi +.if n \{\ +.RE +.\} +.sp +depending on your system\&. If you are certain that no conflicting server is running, you can remove the lock file mentioned in the message and try again\&. +.PP +A failure message indicating inability to bind to a port might indicate that that port is already in use by some non\-PostgreSQL +process\&. You might also get this error if you terminate +\fBpostgres\fR +and immediately restart it using the same port; in this case, you must simply wait a few seconds until the operating system closes the port before trying again\&. Finally, you might get this error if you specify a port number that your operating system considers to be reserved\&. For example, many versions of Unix consider port numbers under 1024 to be +\(lqtrusted\(rq +and only permit the Unix superuser to access them\&. +.SH "NOTES" +.PP +The utility command +\fBpg_ctl\fR(1) +can be used to start and shut down the +\fBpostgres\fR +server safely and comfortably\&. +.PP +If at all possible, +\fIdo not\fR +use +SIGKILL +to kill the main +\fBpostgres\fR +server\&. Doing so will prevent +\fBpostgres\fR +from freeing the system resources (e\&.g\&., shared memory and semaphores) that it holds before terminating\&. This might cause problems for starting a fresh +\fBpostgres\fR +run\&. +.PP +To terminate the +\fBpostgres\fR +server normally, the signals +SIGTERM, +SIGINT, or +SIGQUIT +can be used\&. The first will wait for all clients to terminate before quitting, the second will forcefully disconnect all clients, and the third will quit immediately without proper shutdown, resulting in a recovery run during restart\&. +.PP +The +SIGHUP +signal will reload the server configuration files\&. It is also possible to send +SIGHUP +to an individual server process, but that is usually not sensible\&. +.PP +To cancel a running query, send the +SIGINT +signal to the process running that command\&. To terminate a backend process cleanly, send +SIGTERM +to that process\&. See also +\fBpg_cancel_backend\fR +and +\fBpg_terminate_backend\fR +in +Section\ \&9.27.2 +for the SQL\-callable equivalents of these two actions\&. +.PP +The +\fBpostgres\fR +server uses +SIGQUIT +to tell subordinate server processes to terminate without normal cleanup\&. This signal +\fIshould not\fR +be used by users\&. It is also unwise to send +SIGKILL +to a server process \(em the main +\fBpostgres\fR +process will interpret this as a crash and will force all the sibling processes to quit as part of its standard crash\-recovery procedure\&. +.SH "BUGS" +.PP +The +\fB\-\-\fR +options will not work on +FreeBSD +or +OpenBSD\&. Use +\fB\-c\fR +instead\&. This is a bug in the affected operating systems; a future release of +PostgreSQL +will provide a workaround if this is not fixed\&. +.SH "SINGLE\-USER MODE" +.PP +To start a single\-user mode server, use a command like +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fBpostgres \-\-single \-D /usr/local/pgsql/data \fR\fB\fIother\-options\fR\fR\fB my_database\fR +.fi +.if n \{\ +.RE +.\} +.sp +Provide the correct path to the database directory with +\fB\-D\fR, or make sure that the environment variable +\fBPGDATA\fR +is set\&. Also specify the name of the particular database you want to work in\&. +.PP +Normally, the single\-user mode server treats newline as the command entry terminator; there is no intelligence about semicolons, as there is in +psql\&. To continue a command across multiple lines, you must type backslash just before each newline except the last one\&. The backslash and adjacent newline are both dropped from the input command\&. Note that this will happen even when within a string literal or comment\&. +.PP +But if you use the +\fB\-j\fR +command line switch, a single newline does not terminate command entry; instead, the sequence semicolon\-newline\-newline does\&. That is, type a semicolon immediately followed by a completely empty line\&. Backslash\-newline is not treated specially in this mode\&. Again, there is no intelligence about such a sequence appearing within a string literal or comment\&. +.PP +In either input mode, if you type a semicolon that is not just before or part of a command entry terminator, it is considered a command separator\&. When you do type a command entry terminator, the multiple statements you\*(Aqve entered will be executed as a single transaction\&. +.PP +To quit the session, type +EOF +(Control+D, usually)\&. If you\*(Aqve entered any text since the last command entry terminator, then +EOF +will be taken as a command entry terminator, and another +EOF +will be needed to exit\&. +.PP +Note that the single\-user mode server does not provide sophisticated line\-editing features (no command history, for example)\&. Single\-user mode also does not do any background processing, such as automatic checkpoints or replication\&. +.SH "EXAMPLES" +.PP +To start +\fBpostgres\fR +in the background using default values, type: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBnohup postgres >logfile 2>&1 </dev/null &\fR +.fi +.if n \{\ +.RE +.\} +.PP +To start +\fBpostgres\fR +with a specific port, e\&.g\&., 1234: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpostgres \-p 1234\fR +.fi +.if n \{\ +.RE +.\} +.sp +To connect to this server using +psql, specify this port with the \-p option: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpsql \-p 1234\fR +.fi +.if n \{\ +.RE +.\} +.sp +or set the environment variable +\fBPGPORT\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBexport PGPORT=1234\fR +$ \fBpsql\fR +.fi +.if n \{\ +.RE +.\} +.PP +Named run\-time parameters can be set in either of these styles: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpostgres \-c work_mem=1234\fR +$ \fBpostgres \-\-work\-mem=1234\fR +.fi +.if n \{\ +.RE +.\} +.sp +Either form overrides whatever setting might exist for +\fIwork_mem\fR +in +postgresql\&.conf\&. Notice that underscores in parameter names can be written as either underscore or dash on the command line\&. Except for short\-term experiments, it\*(Aqs probably better practice to edit the setting in +postgresql\&.conf +than to rely on a command\-line switch to set a parameter\&. +.SH "SEE ALSO" +.PP +\fBinitdb\fR(1), +\fBpg_ctl\fR(1) diff --git a/doc/src/sgml/man1/postmaster.1 b/doc/src/sgml/man1/postmaster.1 new file mode 100644 index 0000000..1d8ad0d --- /dev/null +++ b/doc/src/sgml/man1/postmaster.1 @@ -0,0 +1,42 @@ +'\" t +.\" Title: postmaster +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "POSTMASTER" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +postmaster \- PostgreSQL database server +.SH "SYNOPSIS" +.HP \w'\fBpostmaster\fR\ 'u +\fBpostmaster\fR [\fIoption\fR...] +.SH "DESCRIPTION" +.PP +\fBpostmaster\fR +is a deprecated alias of +\fBpostgres\fR\&. +.SH "SEE ALSO" +.PP +\fBpostgres\fR(1) diff --git a/doc/src/sgml/man1/psql.1 b/doc/src/sgml/man1/psql.1 new file mode 100644 index 0000000..2b9c0ce --- /dev/null +++ b/doc/src/sgml/man1/psql.1 @@ -0,0 +1,4515 @@ +'\" t +.\" Title: psql +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "PSQL" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +psql \- PostgreSQL interactive terminal +.SH "SYNOPSIS" +.HP \w'\fBpsql\fR\ 'u +\fBpsql\fR [\fIoption\fR...] [\fIdbname\fR\ [\fIusername\fR]] +.SH "DESCRIPTION" +.PP +psql +is a terminal\-based front\-end to +PostgreSQL\&. It enables you to type in queries interactively, issue them to +PostgreSQL, and see the query results\&. Alternatively, input can be from a file or from command line arguments\&. In addition, +psql +provides a number of meta\-commands and various shell\-like features to facilitate writing scripts and automating a wide variety of tasks\&. +.SH "OPTIONS" +.PP +\fB\-a\fR +.br +\fB\-\-echo\-all\fR +.RS 4 +Print all nonempty input lines to standard output as they are read\&. (This does not apply to lines read interactively\&.) This is equivalent to setting the variable +\fIECHO\fR +to +all\&. +.RE +.PP +\fB\-A\fR +.br +\fB\-\-no\-align\fR +.RS 4 +Switches to unaligned output mode\&. (The default output mode is +aligned\&.) This is equivalent to +\fB\epset format unaligned\fR\&. +.RE +.PP +\fB\-b\fR +.br +\fB\-\-echo\-errors\fR +.RS 4 +Print failed SQL commands to standard error output\&. This is equivalent to setting the variable +\fIECHO\fR +to +errors\&. +.RE +.PP +\fB\-c \fR\fB\fIcommand\fR\fR +.br +\fB\-\-command=\fR\fB\fIcommand\fR\fR +.RS 4 +Specifies that +psql +is to execute the given command string, +\fIcommand\fR\&. This option can be repeated and combined in any order with the +\fB\-f\fR +option\&. When either +\fB\-c\fR +or +\fB\-f\fR +is specified, +psql +does not read commands from standard input; instead it terminates after processing all the +\fB\-c\fR +and +\fB\-f\fR +options in sequence\&. +.sp +\fIcommand\fR +must be either a command string that is completely parsable by the server (i\&.e\&., it contains no +psql\-specific features), or a single backslash command\&. Thus you cannot mix +SQL +and +psql +meta\-commands within a +\fB\-c\fR +option\&. To achieve that, you could use repeated +\fB\-c\fR +options or pipe the string into +psql, for example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +psql \-c \*(Aq\ex\*(Aq \-c \*(AqSELECT * FROM foo;\*(Aq +.fi +.if n \{\ +.RE +.\} +.sp +or +.sp +.if n \{\ +.RS 4 +.\} +.nf +echo \*(Aq\ex \e\e SELECT * FROM foo;\*(Aq | psql +.fi +.if n \{\ +.RE +.\} +.sp +(\e\e +is the separator meta\-command\&.) +.sp +Each +SQL +command string passed to +\fB\-c\fR +is sent to the server as a single request\&. Because of this, the server executes it as a single transaction even if the string contains multiple +SQL +commands, unless there are explicit +\fBBEGIN\fR/\fBCOMMIT\fR +commands included in the string to divide it into multiple transactions\&. (See +Section\ \&55.2.2.1 +for more details about how the server handles multi\-query strings\&.) +.sp +If having several commands executed in one transaction is not desired, use repeated +\fB\-c\fR +commands or feed multiple commands to +psql\*(Aqs standard input, either using +echo +as illustrated above, or via a shell here\-document, for example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +psql <<EOF +\ex +SELECT * FROM foo; +EOF +.fi +.if n \{\ +.RE +.\} +.RE +.PP +\fB\-\-csv\fR +.RS 4 +Switches to +CSV +(Comma\-Separated Values) output mode\&. This is equivalent to +\fB\epset format csv\fR\&. +.RE +.PP +\fB\-d \fR\fB\fIdbname\fR\fR +.br +\fB\-\-dbname=\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to connect to\&. This is equivalent to specifying +\fIdbname\fR +as the first non\-option argument on the command line\&. The +\fIdbname\fR +can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. +.RE +.PP +\fB\-e\fR +.br +\fB\-\-echo\-queries\fR +.RS 4 +Copy all SQL commands sent to the server to standard output as well\&. This is equivalent to setting the variable +\fIECHO\fR +to +queries\&. +.RE +.PP +\fB\-E\fR +.br +\fB\-\-echo\-hidden\fR +.RS 4 +Echo the actual queries generated by +\fB\ed\fR +and other backslash commands\&. You can use this to study +psql\*(Aqs internal operations\&. This is equivalent to setting the variable +\fIECHO_HIDDEN\fR +to +on\&. +.RE +.PP +\fB\-f \fR\fB\fIfilename\fR\fR +.br +\fB\-\-file=\fR\fB\fIfilename\fR\fR +.RS 4 +Read commands from the file +\fIfilename\fR, rather than standard input\&. This option can be repeated and combined in any order with the +\fB\-c\fR +option\&. When either +\fB\-c\fR +or +\fB\-f\fR +is specified, +psql +does not read commands from standard input; instead it terminates after processing all the +\fB\-c\fR +and +\fB\-f\fR +options in sequence\&. Except for that, this option is largely equivalent to the meta\-command +\fB\ei\fR\&. +.sp +If +\fIfilename\fR +is +\- +(hyphen), then standard input is read until an EOF indication or +\fB\eq\fR +meta\-command\&. This can be used to intersperse interactive input with input from files\&. Note however that Readline is not used in this case (much as if +\fB\-n\fR +had been specified)\&. +.sp +Using this option is subtly different from writing +psql < \fIfilename\fR\&. In general, both will do what you expect, but using +\-f +enables some nice features such as error messages with line numbers\&. There is also a slight chance that using this option will reduce the start\-up overhead\&. On the other hand, the variant using the shell\*(Aqs input redirection is (in theory) guaranteed to yield exactly the same output you would have received had you entered everything by hand\&. +.RE +.PP +\fB\-F \fR\fB\fIseparator\fR\fR +.br +\fB\-\-field\-separator=\fR\fB\fIseparator\fR\fR +.RS 4 +Use +\fIseparator\fR +as the field separator for unaligned output\&. This is equivalent to +\fB\epset fieldsep\fR +or +\fB\ef\fR\&. +.RE +.PP +\fB\-h \fR\fB\fIhostname\fR\fR +.br +\fB\-\-host=\fR\fB\fIhostname\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix\-domain socket\&. +.RE +.PP +\fB\-H\fR +.br +\fB\-\-html\fR +.RS 4 +Switches to +HTML +output mode\&. This is equivalent to +\fB\epset format html\fR +or the +\fB\eH\fR +command\&. +.RE +.PP +\fB\-l\fR +.br +\fB\-\-list\fR +.RS 4 +List all available databases, then exit\&. Other non\-connection options are ignored\&. This is similar to the meta\-command +\fB\elist\fR\&. +.sp +When this option is used, +psql +will connect to the database +postgres, unless a different database is named on the command line (option +\fB\-d\fR +or non\-option argument, possibly via a service entry, but not via an environment variable)\&. +.RE +.PP +\fB\-L \fR\fB\fIfilename\fR\fR +.br +\fB\-\-log\-file=\fR\fB\fIfilename\fR\fR +.RS 4 +Write all query output into file +\fIfilename\fR, in addition to the normal output destination\&. +.RE +.PP +\fB\-n\fR +.br +\fB\-\-no\-readline\fR +.RS 4 +Do not use +Readline +for line editing and do not use the command history (see +the section called \(lqCommand\-Line Editing\(rq +below)\&. +.RE +.PP +\fB\-o \fR\fB\fIfilename\fR\fR +.br +\fB\-\-output=\fR\fB\fIfilename\fR\fR +.RS 4 +Put all query output into file +\fIfilename\fR\&. This is equivalent to the command +\fB\eo\fR\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or the local Unix\-domain socket file extension on which the server is listening for connections\&. Defaults to the value of the +\fBPGPORT\fR +environment variable or, if not set, to the port specified at compile time, usually 5432\&. +.RE +.PP +\fB\-P \fR\fB\fIassignment\fR\fR +.br +\fB\-\-pset=\fR\fB\fIassignment\fR\fR +.RS 4 +Specifies printing options, in the style of +\fB\epset\fR\&. Note that here you have to separate name and value with an equal sign instead of a space\&. For example, to set the output format to +LaTeX, you could write +\-P format=latex\&. +.RE +.PP +\fB\-q\fR +.br +\fB\-\-quiet\fR +.RS 4 +Specifies that +psql +should do its work quietly\&. By default, it prints welcome messages and various informational output\&. If this option is used, none of this happens\&. This is useful with the +\fB\-c\fR +option\&. This is equivalent to setting the variable +\fIQUIET\fR +to +on\&. +.RE +.PP +\fB\-R \fR\fB\fIseparator\fR\fR +.br +\fB\-\-record\-separator=\fR\fB\fIseparator\fR\fR +.RS 4 +Use +\fIseparator\fR +as the record separator for unaligned output\&. This is equivalent to +\fB\epset recordsep\fR\&. +.RE +.PP +\fB\-s\fR +.br +\fB\-\-single\-step\fR +.RS 4 +Run in single\-step mode\&. That means the user is prompted before each command is sent to the server, with the option to cancel execution as well\&. Use this to debug scripts\&. +.RE +.PP +\fB\-S\fR +.br +\fB\-\-single\-line\fR +.RS 4 +Runs in single\-line mode where a newline terminates an SQL command, as a semicolon does\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This mode is provided for those who insist on it, but you are not necessarily encouraged to use it\&. In particular, if you mix +SQL +and meta\-commands on a line the order of execution might not always be clear to the inexperienced user\&. +.sp .5v +.RE +.RE +.PP +\fB\-t\fR +.br +\fB\-\-tuples\-only\fR +.RS 4 +Turn off printing of column names and result row count footers, etc\&. This is equivalent to +\fB\et\fR +or +\fB\epset tuples_only\fR\&. +.RE +.PP +\fB\-T \fR\fB\fItable_options\fR\fR +.br +\fB\-\-table\-attr=\fR\fB\fItable_options\fR\fR +.RS 4 +Specifies options to be placed within the +HTML +table +tag\&. See +\fB\epset tableattr\fR +for details\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +Connect to the database as the user +\fIusername\fR +instead of the default\&. (You must have permission to do so, of course\&.) +.RE +.PP +\fB\-v \fR\fB\fIassignment\fR\fR +.br +\fB\-\-set=\fR\fB\fIassignment\fR\fR +.br +\fB\-\-variable=\fR\fB\fIassignment\fR\fR +.RS 4 +Perform a variable assignment, like the +\fB\eset\fR +meta\-command\&. Note that you must separate name and value, if any, by an equal sign on the command line\&. To unset a variable, leave off the equal sign\&. To set a variable with an empty value, use the equal sign but leave off the value\&. These assignments are done during command line processing, so variables that reflect connection state will get overwritten later\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +psql +version and exit\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available from other sources such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.sp +Note that this option will remain set for the entire session, and so it affects uses of the meta\-command +\fB\econnect\fR +as well as the initial connection attempt\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +psql +to prompt for a password before connecting to a database, even if the password will not be used\&. +.sp +If the server requires password authentication and a password is not available from other sources such as a +\&.pgpass +file, +psql +will prompt for a password in any case\&. However, +psql +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.sp +Note that this option will remain set for the entire session, and so it affects uses of the meta\-command +\fB\econnect\fR +as well as the initial connection attempt\&. +.RE +.PP +\fB\-x\fR +.br +\fB\-\-expanded\fR +.RS 4 +Turn on the expanded table formatting mode\&. This is equivalent to +\fB\ex\fR +or +\fB\epset expanded\fR\&. +.RE +.PP +\fB\-X,\fR +.br +\fB\-\-no\-psqlrc\fR +.RS 4 +Do not read the start\-up file (neither the system\-wide +psqlrc +file nor the user\*(Aqs +~/\&.psqlrc +file)\&. +.RE +.PP +\fB\-z\fR +.br +\fB\-\-field\-separator\-zero\fR +.RS 4 +Set the field separator for unaligned output to a zero byte\&. This is equivalent to +\fB\epset fieldsep_zero\fR\&. +.RE +.PP +\fB\-0\fR +.br +\fB\-\-record\-separator\-zero\fR +.RS 4 +Set the record separator for unaligned output to a zero byte\&. This is useful for interfacing, for example, with +xargs \-0\&. This is equivalent to +\fB\epset recordsep_zero\fR\&. +.RE +.PP +\fB\-1\fR +.br +\fB\-\-single\-transaction\fR +.RS 4 +This option can only be used in combination with one or more +\fB\-c\fR +and/or +\fB\-f\fR +options\&. It causes +psql +to issue a +\fBBEGIN\fR +command before the first such option and a +\fBCOMMIT\fR +command after the last one, thereby wrapping all the commands into a single transaction\&. If any of the commands fails and the variable +\fION_ERROR_STOP\fR +was set, a +\fBROLLBACK\fR +command is sent instead\&. This ensures that either all the commands complete successfully, or no changes are applied\&. +.sp +If the commands themselves contain +\fBBEGIN\fR, +\fBCOMMIT\fR, or +\fBROLLBACK\fR, this option will not have the desired effects\&. Also, if an individual command cannot be executed inside a transaction block, specifying this option will cause the whole transaction to fail\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help[=\fR\fB\fItopic\fR\fR\fB]\fR +.RS 4 +Show help about +psql +and exit\&. The optional +\fItopic\fR +parameter (defaulting to +options) selects which part of +psql +is explained: +commands +describes +psql\*(Aqs backslash commands; +options +describes the command\-line options that can be passed to +psql; and +variables +shows help about +psql +configuration variables\&. +.RE +.SH "EXIT STATUS" +.PP +psql +returns 0 to the shell if it finished normally, 1 if a fatal error of its own occurs (e\&.g\&., out of memory, file not found), 2 if the connection to the server went bad and the session was not interactive, and 3 if an error occurred in a script and the variable +\fION_ERROR_STOP\fR +was set\&. +.SH "USAGE" +.SS "Connecting to a Database" +.PP +psql +is a regular +PostgreSQL +client application\&. In order to connect to a database you need to know the name of your target database, the host name and port number of the server, and what user name you want to connect as\&. +psql +can be told about those parameters via command line options, namely +\fB\-d\fR, +\fB\-h\fR, +\fB\-p\fR, and +\fB\-U\fR +respectively\&. If an argument is found that does not belong to any option it will be interpreted as the database name (or the user name, if the database name is already given)\&. Not all of these options are required; there are useful defaults\&. If you omit the host name, +psql +will connect via a Unix\-domain socket to a server on the local host, or via TCP/IP to +localhost +on machines that don\*(Aqt have Unix\-domain sockets\&. The default port number is determined at compile time\&. Since the database server uses the same default, you will not have to specify the port in most cases\&. The default user name is your operating\-system user name, as is the default database name\&. Note that you cannot just connect to any database under any user name\&. Your database administrator should have informed you about your access rights\&. +.PP +When the defaults aren\*(Aqt quite right, you can save yourself some typing by setting the environment variables +\fBPGDATABASE\fR, +\fBPGHOST\fR, +\fBPGPORT\fR +and/or +\fBPGUSER\fR +to appropriate values\&. (For additional environment variables, see +Section\ \&34.15\&.) It is also convenient to have a +~/\&.pgpass +file to avoid regularly having to type in passwords\&. See +Section\ \&34.16 +for more information\&. +.PP +An alternative way to specify connection parameters is in a +\fIconninfo\fR +string or a +URI, which is used instead of a database name\&. This mechanism give you very wide control over the connection\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpsql "service=myservice sslmode=require"\fR +$ \fBpsql postgresql://dbmaster:5433/mydb?sslmode=require\fR +.fi +.if n \{\ +.RE +.\} +.sp +This way you can also use +LDAP +for connection parameter lookup as described in +Section\ \&34.18\&. See +Section\ \&34.1.2 +for more information on all the available connection options\&. +.PP +If the connection could not be made for any reason (e\&.g\&., insufficient privileges, server is not running on the targeted host, etc\&.), +psql +will return an error and terminate\&. +.PP +If both standard input and standard output are a terminal, then +psql +sets the client encoding to +\(lqauto\(rq, which will detect the appropriate client encoding from the locale settings (\fBLC_CTYPE\fR +environment variable on Unix systems)\&. If this doesn\*(Aqt work out as expected, the client encoding can be overridden using the environment variable +\fBPGCLIENTENCODING\fR\&. +.SS "Entering SQL Commands" +.PP +In normal operation, +psql +provides a prompt with the name of the database to which +psql +is currently connected, followed by the string +=>\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBpsql testdb\fR +psql (15\&.4) +Type "help" for help\&. + +testdb=> +.fi +.if n \{\ +.RE +.\} +.PP +At the prompt, the user can type in +SQL +commands\&. Ordinarily, input lines are sent to the server when a command\-terminating semicolon is reached\&. An end of line does not terminate a command\&. Thus commands can be spread over several lines for clarity\&. If the command was sent and executed without error, the results of the command are displayed on the screen\&. +.PP +If untrusted users have access to a database that has not adopted a +secure schema usage pattern, begin your session by removing publicly\-writable schemas from +\fIsearch_path\fR\&. One can add +options=\-csearch_path= +to the connection string or issue +SELECT pg_catalog\&.set_config(\*(Aqsearch_path\*(Aq, \*(Aq\*(Aq, false) +before other SQL commands\&. This consideration is not specific to +psql; it applies to every interface for executing arbitrary SQL commands\&. +.PP +Whenever a command is executed, +psql +also polls for asynchronous notification events generated by +\fBLISTEN\fR +and +\fBNOTIFY\fR\&. +.PP +While C\-style block comments are passed to the server for processing and removal, SQL\-standard comments are removed by +psql\&. +.SS "Meta\-Commands" +.PP +Anything you enter in +psql +that begins with an unquoted backslash is a +psql +meta\-command that is processed by +psql +itself\&. These commands make +psql +more useful for administration or scripting\&. Meta\-commands are often called slash or backslash commands\&. +.PP +The format of a +psql +command is the backslash, followed immediately by a command verb, then any arguments\&. The arguments are separated from the command verb and each other by any number of whitespace characters\&. +.PP +To include whitespace in an argument you can quote it with single quotes\&. To include a single quote in an argument, write two single quotes within single\-quoted text\&. Anything contained in single quotes is furthermore subject to C\-like substitutions for +\en +(new line), +\et +(tab), +\eb +(backspace), +\er +(carriage return), +\ef +(form feed), +\e\fIdigits\fR +(octal), and +\ex\fIdigits\fR +(hexadecimal)\&. A backslash preceding any other character within single\-quoted text quotes that single character, whatever it is\&. +.PP +If an unquoted colon (:) followed by a +psql +variable name appears within an argument, it is replaced by the variable\*(Aqs value, as described in +SQL Interpolation +below\&. The forms +:\*(Aq\fIvariable_name\fR\*(Aq +and +:"\fIvariable_name\fR" +described there work as well\&. The +:{?\fIvariable_name\fR} +syntax allows testing whether a variable is defined\&. It is substituted by TRUE or FALSE\&. Escaping the colon with a backslash protects it from substitution\&. +.PP +Within an argument, text that is enclosed in backquotes (`) is taken as a command line that is passed to the shell\&. The output of the command (with any trailing newline removed) replaces the backquoted text\&. Within the text enclosed in backquotes, no special quoting or other processing occurs, except that appearances of +:\fIvariable_name\fR +where +\fIvariable_name\fR +is a +psql +variable name are replaced by the variable\*(Aqs value\&. Also, appearances of +:\*(Aq\fIvariable_name\fR\*(Aq +are replaced by the variable\*(Aqs value suitably quoted to become a single shell command argument\&. (The latter form is almost always preferable, unless you are very sure of what is in the variable\&.) Because carriage return and line feed characters cannot be safely quoted on all platforms, the +:\*(Aq\fIvariable_name\fR\*(Aq +form prints an error message and does not substitute the variable value when such characters appear in the value\&. +.PP +Some commands take an +SQL +identifier (such as a table name) as argument\&. These arguments follow the syntax rules of +SQL: Unquoted letters are forced to lowercase, while double quotes (") protect letters from case conversion and allow incorporation of whitespace into the identifier\&. Within double quotes, paired double quotes reduce to a single double quote in the resulting name\&. For example, +FOO"BAR"BAZ +is interpreted as +fooBARbaz, and +"A weird"" name" +becomes +A weird" name\&. +.PP +Parsing for arguments stops at the end of the line, or when another unquoted backslash is found\&. An unquoted backslash is taken as the beginning of a new meta\-command\&. The special sequence +\e\e +(two backslashes) marks the end of arguments and continues parsing +SQL +commands, if any\&. That way +SQL +and +psql +commands can be freely mixed on a line\&. But in any case, the arguments of a meta\-command cannot continue beyond the end of the line\&. +.PP +Many of the meta\-commands act on the +current query buffer\&. This is simply a buffer holding whatever SQL command text has been typed but not yet sent to the server for execution\&. This will include previous input lines as well as any text appearing before the meta\-command on the same line\&. +.PP +The following meta\-commands are defined: +.PP +\ea +.RS 4 +If the current table output format is unaligned, it is switched to aligned\&. If it is not unaligned, it is set to unaligned\&. This command is kept for backwards compatibility\&. See +\fB\epset\fR +for a more general solution\&. +.RE +.PP +\ec or \econnect [ \-reuse\-previous=\fIon|off\fR ] [ \fIdbname\fR [ \fIusername\fR ] [ \fIhost\fR ] [ \fIport\fR ] | \fIconninfo\fR ] +.RS 4 +Establishes a new connection to a +PostgreSQL +server\&. The connection parameters to use can be specified either using a positional syntax (one or more of database name, user, host, and port), or using a +\fIconninfo\fR +connection string as detailed in +Section\ \&34.1.1\&. If no arguments are given, a new connection is made using the same parameters as before\&. +.sp +Specifying any of +\fIdbname\fR, +\fIusername\fR, +\fIhost\fR +or +\fIport\fR +as +\- +is equivalent to omitting that parameter\&. +.sp +The new connection can re\-use connection parameters from the previous connection; not only database name, user, host, and port, but other settings such as +\fIsslmode\fR\&. By default, parameters are re\-used in the positional syntax, but not when a +\fIconninfo\fR +string is given\&. Passing a first argument of +\-reuse\-previous=on +or +\-reuse\-previous=off +overrides that default\&. If parameters are re\-used, then any parameter not explicitly specified as a positional parameter or in the +\fIconninfo\fR +string is taken from the existing connection\*(Aqs parameters\&. An exception is that if the +\fIhost\fR +setting is changed from its previous value using the positional syntax, any +\fIhostaddr\fR +setting present in the existing connection\*(Aqs parameters is dropped\&. Also, any password used for the existing connection will be re\-used only if the user, host, and port settings are not changed\&. When the command neither specifies nor reuses a particular parameter, the +libpq +default is used\&. +.sp +If the new connection is successfully made, the previous connection is closed\&. If the connection attempt fails (wrong user name, access denied, etc\&.), the previous connection will be kept if +psql +is in interactive mode\&. But when executing a non\-interactive script, the old connection is closed and an error is reported\&. That may or may not terminate the script; if it does not, all database\-accessing commands will fail until another +\econnect +command is successfully executed\&. This distinction was chosen as a user convenience against typos on the one hand, and a safety mechanism that scripts are not accidentally acting on the wrong database on the other hand\&. Note that whenever a +\econnect +command attempts to re\-use parameters, the values re\-used are those of the last successful connection, not of any failed attempts made subsequently\&. However, in the case of a non\-interactive +\econnect +failure, no parameters are allowed to be re\-used later, since the script would likely be expecting the values from the failed +\econnect +to be re\-used\&. +.sp +Examples: +.sp +.if n \{\ +.RS 4 +.\} +.nf +=> \ec mydb myuser host\&.dom 6432 +=> \ec service=foo +=> \ec "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" +=> \ec \-reuse\-previous=on sslmode=require \-\- changes only sslmode +=> \ec postgresql://tom@localhost/mydb?application_name=myapp +.fi +.if n \{\ +.RE +.\} +.RE +.PP +\eC [ \fItitle\fR ] +.RS 4 +Sets the title of any tables being printed as the result of a query or unset any such title\&. This command is equivalent to +\epset title \fItitle\fR\&. (The name of this command derives from +\(lqcaption\(rq, as it was previously only used to set the caption in an +HTML +table\&.) +.RE +.PP +\ecd [ \fIdirectory\fR ] +.RS 4 +Changes the current working directory to +\fIdirectory\fR\&. Without argument, changes to the current user\*(Aqs home directory\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +To print your current working directory, use +\e! pwd\&. +.sp .5v +.RE +.RE +.PP +\econninfo +.RS 4 +Outputs information about the current database connection\&. +.RE +.PP +\ecopy { \fItable\fR [ ( \fIcolumn_list\fR ) ] } from { \fI\*(Aqfilename\*(Aq\fR | program \fI\*(Aqcommand\*(Aq\fR | stdin | pstdin } [ [ with ] ( \fIoption\fR [, \&.\&.\&.] ) ] [ where \fIcondition\fR ] +.br +\ecopy { \fItable\fR [ ( \fIcolumn_list\fR ) ] | ( \fIquery\fR ) } to { \fI\*(Aqfilename\*(Aq\fR | program \fI\*(Aqcommand\*(Aq\fR | stdout | pstdout } [ [ with ] ( \fIoption\fR [, \&.\&.\&.] ) ] +.RS 4 +Performs a frontend (client) copy\&. This is an operation that runs an +SQL +\fBCOPY\fR +command, but instead of the server reading or writing the specified file, +psql +reads or writes the file and routes the data between the server and the local file system\&. This means that file accessibility and privileges are those of the local user, not the server, and no SQL superuser privileges are required\&. +.sp +When +program +is specified, +\fIcommand\fR +is executed by +psql +and the data passed from or to +\fIcommand\fR +is routed between the server and the client\&. Again, the execution privileges are those of the local user, not the server, and no SQL superuser privileges are required\&. +.sp +For +\ecopy \&.\&.\&. from stdin, data rows are read from the same source that issued the command, continuing until +\e\&. +is read or the stream reaches +EOF\&. This option is useful for populating tables in\-line within an SQL script file\&. For +\ecopy \&.\&.\&. to stdout, output is sent to the same place as +psql +command output, and the +COPY \fIcount\fR +command status is not printed (since it might be confused with a data row)\&. To read/write +psql\*(Aqs standard input or output regardless of the current command source or +\eo +option, write +from pstdin +or +to pstdout\&. +.sp +The syntax of this command is similar to that of the +SQL +\fBCOPY\fR +command\&. All options other than the data source/destination are as specified for +\fBCOPY\fR\&. Because of this, special parsing rules apply to the +\fB\ecopy\fR +meta\-command\&. Unlike most other meta\-commands, the entire remainder of the line is always taken to be the arguments of +\fB\ecopy\fR, and neither variable interpolation nor backquote expansion are performed in the arguments\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +Another way to obtain the same result as +\ecopy \&.\&.\&. to +is to use the +SQL +COPY \&.\&.\&. TO STDOUT +command and terminate it with +\eg \fIfilename\fR +or +\eg |\fIprogram\fR\&. Unlike +\ecopy, this method allows the command to span multiple lines; also, variable interpolation and backquote expansion can be used\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +These operations are not as efficient as the +SQL +\fBCOPY\fR +command with a file or program data source or destination, because all data must pass through the client/server connection\&. For large amounts of data the +SQL +command might be preferable\&. +.sp .5v +.RE +.RE +.PP +\ecopyright +.RS 4 +Shows the copyright and distribution terms of +PostgreSQL\&. +.RE +.PP +\ecrosstabview [ \fIcolV\fR [ \fIcolH\fR [ \fIcolD\fR [ \fIsortcolH\fR ] ] ] ] +.RS 4 +Executes the current query buffer (like +\eg) and shows the results in a crosstab grid\&. The query must return at least three columns\&. The output column identified by +\fIcolV\fR +becomes a vertical header and the output column identified by +\fIcolH\fR +becomes a horizontal header\&. +\fIcolD\fR +identifies the output column to display within the grid\&. +\fIsortcolH\fR +identifies an optional sort column for the horizontal header\&. +.sp +Each column specification can be a column number (starting at 1) or a column name\&. The usual SQL case folding and quoting rules apply to column names\&. If omitted, +\fIcolV\fR +is taken as column 1 and +\fIcolH\fR +as column 2\&. +\fIcolH\fR +must differ from +\fIcolV\fR\&. If +\fIcolD\fR +is not specified, then there must be exactly three columns in the query result, and the column that is neither +\fIcolV\fR +nor +\fIcolH\fR +is taken to be +\fIcolD\fR\&. +.sp +The vertical header, displayed as the leftmost column, contains the values found in column +\fIcolV\fR, in the same order as in the query results, but with duplicates removed\&. +.sp +The horizontal header, displayed as the first row, contains the values found in column +\fIcolH\fR, with duplicates removed\&. By default, these appear in the same order as in the query results\&. But if the optional +\fIsortcolH\fR +argument is given, it identifies a column whose values must be integer numbers, and the values from +\fIcolH\fR +will appear in the horizontal header sorted according to the corresponding +\fIsortcolH\fR +values\&. +.sp +Inside the crosstab grid, for each distinct value +x +of +\fIcolH\fR +and each distinct value +y +of +\fIcolV\fR, the cell located at the intersection +(x,y) +contains the value of the +colD +column in the query result row for which the value of +\fIcolH\fR +is +x +and the value of +\fIcolV\fR +is +y\&. If there is no such row, the cell is empty\&. If there are multiple such rows, an error is reported\&. +.RE +.PP +\ed[S+] [ \fIpattern\fR ] +.RS 4 +For each relation (table, view, materialized view, index, sequence, or foreign table) or composite type matching the +\fIpattern\fR, show all columns, their types, the tablespace (if not the default) and any special attributes such as +NOT NULL +or defaults\&. Associated indexes, constraints, rules, and triggers are also shown\&. For foreign tables, the associated foreign server is shown as well\&. (\(lqMatching the pattern\(rq +is defined in +Patterns +below\&.) +.sp +For some types of relation, +\ed +shows additional information for each column: column values for sequences, indexed expressions for indexes, and foreign data wrapper options for foreign tables\&. +.sp +The command form +\ed+ +is identical, except that more information is displayed: any comments associated with the columns of the table are shown, as is the presence of OIDs in the table, the view definition if the relation is a view, a non\-default +replica identity +setting and the +access method +name if the relation has an access method\&. +.sp +By default, only user\-created objects are shown; supply a pattern or the +S +modifier to include system objects\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +If +\fB\ed\fR +is used without a +\fIpattern\fR +argument, it is equivalent to +\fB\edtvmsE\fR +which will show a list of all visible tables, views, materialized views, sequences and foreign tables\&. This is purely a convenience measure\&. +.sp .5v +.RE +.RE +.PP +\eda[S] [ \fIpattern\fR ] +.RS 4 +Lists aggregate functions, together with their return type and the data types they operate on\&. If +\fIpattern\fR +is specified, only aggregates whose names match the pattern are shown\&. By default, only user\-created objects are shown; supply a pattern or the +S +modifier to include system objects\&. +.RE +.PP +\edA[+] [ \fIpattern\fR ] +.RS 4 +Lists access methods\&. If +\fIpattern\fR +is specified, only access methods whose names match the pattern are shown\&. If ++ +is appended to the command name, each access method is listed with its associated handler function and description\&. +.RE +.PP +\edAc[+] [\fIaccess\-method\-pattern\fR [\fIinput\-type\-pattern\fR]] +.RS 4 +Lists operator classes (see +Section\ \&38.16.1)\&. If +\fIaccess\-method\-pattern\fR +is specified, only operator classes associated with access methods whose names match that pattern are listed\&. If +\fIinput\-type\-pattern\fR +is specified, only operator classes associated with input types whose names match that pattern are listed\&. If ++ +is appended to the command name, each operator class is listed with its associated operator family and owner\&. +.RE +.PP +\edAf[+] [\fIaccess\-method\-pattern\fR [\fIinput\-type\-pattern\fR]] +.RS 4 +Lists operator families (see +Section\ \&38.16.5)\&. If +\fIaccess\-method\-pattern\fR +is specified, only operator families associated with access methods whose names match that pattern are listed\&. If +\fIinput\-type\-pattern\fR +is specified, only operator families associated with input types whose names match that pattern are listed\&. If ++ +is appended to the command name, each operator family is listed with its owner\&. +.RE +.PP +\edAo[+] [\fIaccess\-method\-pattern\fR [\fIoperator\-family\-pattern\fR]] +.RS 4 +Lists operators associated with operator families (see +Section\ \&38.16.2)\&. If +\fIaccess\-method\-pattern\fR +is specified, only members of operator families associated with access methods whose names match that pattern are listed\&. If +\fIoperator\-family\-pattern\fR +is specified, only members of operator families whose names match that pattern are listed\&. If ++ +is appended to the command name, each operator is listed with its sort operator family (if it is an ordering operator)\&. +.RE +.PP +\edAp[+] [\fIaccess\-method\-pattern\fR [\fIoperator\-family\-pattern\fR]] +.RS 4 +Lists support functions associated with operator families (see +Section\ \&38.16.3)\&. If +\fIaccess\-method\-pattern\fR +is specified, only functions of operator families associated with access methods whose names match that pattern are listed\&. If +\fIoperator\-family\-pattern\fR +is specified, only functions of operator families whose names match that pattern are listed\&. If ++ +is appended to the command name, functions are displayed verbosely, with their actual parameter lists\&. +.RE +.PP +\edb[+] [ \fIpattern\fR ] +.RS 4 +Lists tablespaces\&. If +\fIpattern\fR +is specified, only tablespaces whose names match the pattern are shown\&. If ++ +is appended to the command name, each tablespace is listed with its associated options, on\-disk size, permissions and description\&. +.RE +.PP +\edc[S+] [ \fIpattern\fR ] +.RS 4 +Lists conversions between character\-set encodings\&. If +\fIpattern\fR +is specified, only conversions whose names match the pattern are listed\&. By default, only user\-created objects are shown; supply a pattern or the +S +modifier to include system objects\&. If ++ +is appended to the command name, each object is listed with its associated description\&. +.RE +.PP +\edconfig[+] [ \fIpattern\fR ] +.RS 4 +Lists server configuration parameters and their values\&. If +\fIpattern\fR +is specified, only parameters whose names match the pattern are listed\&. Without a +\fIpattern\fR, only parameters that are set to non\-default values are listed\&. (Use +\edconfig * +to see all parameters\&.) If ++ +is appended to the command name, each parameter is listed with its data type, context in which the parameter can be set, and access privileges (if non\-default access privileges have been granted)\&. +.RE +.PP +\edC[+] [ \fIpattern\fR ] +.RS 4 +Lists type casts\&. If +\fIpattern\fR +is specified, only casts whose source or target types match the pattern are listed\&. If ++ +is appended to the command name, each object is listed with its associated description\&. +.RE +.PP +\edd[S] [ \fIpattern\fR ] +.RS 4 +Shows the descriptions of objects of type +constraint, +operator class, +operator family, +rule, and +trigger\&. All other comments may be viewed by the respective backslash commands for those object types\&. +.sp +\edd +displays descriptions for objects matching the +\fIpattern\fR, or of visible objects of the appropriate type if no argument is given\&. But in either case, only objects that have a description are listed\&. By default, only user\-created objects are shown; supply a pattern or the +S +modifier to include system objects\&. +.sp +Descriptions for objects can be created with the +\fBCOMMENT\fR +SQL +command\&. +.RE +.PP +\edD[S+] [ \fIpattern\fR ] +.RS 4 +Lists domains\&. If +\fIpattern\fR +is specified, only domains whose names match the pattern are shown\&. By default, only user\-created objects are shown; supply a pattern or the +S +modifier to include system objects\&. If ++ +is appended to the command name, each object is listed with its associated permissions and description\&. +.RE +.PP +\eddp [ \fIpattern\fR ] +.RS 4 +Lists default access privilege settings\&. An entry is shown for each role (and schema, if applicable) for which the default privilege settings have been changed from the built\-in defaults\&. If +\fIpattern\fR +is specified, only entries whose role name or schema name matches the pattern are listed\&. +.sp +The +\fBALTER DEFAULT PRIVILEGES\fR +command is used to set default access privileges\&. The meaning of the privilege display is explained in +Section\ \&5.7\&. +.RE +.PP +\edE[S+] [ \fIpattern\fR ] +.br +\edi[S+] [ \fIpattern\fR ] +.br +\edm[S+] [ \fIpattern\fR ] +.br +\eds[S+] [ \fIpattern\fR ] +.br +\edt[S+] [ \fIpattern\fR ] +.br +\edv[S+] [ \fIpattern\fR ] +.RS 4 +In this group of commands, the letters +E, +i, +m, +s, +t, and +v +stand for foreign table, index, materialized view, sequence, table, and view, respectively\&. You can specify any or all of these letters, in any order, to obtain a listing of objects of these types\&. For example, +\edti +lists tables and indexes\&. If ++ +is appended to the command name, each object is listed with its persistence status (permanent, temporary, or unlogged), physical size on disk, and associated description if any\&. If +\fIpattern\fR +is specified, only objects whose names match the pattern are listed\&. By default, only user\-created objects are shown; supply a pattern or the +S +modifier to include system objects\&. +.RE +.PP +\edes[+] [ \fIpattern\fR ] +.RS 4 +Lists foreign servers (mnemonic: +\(lqexternal servers\(rq)\&. If +\fIpattern\fR +is specified, only those servers whose name matches the pattern are listed\&. If the form +\edes+ +is used, a full description of each server is shown, including the server\*(Aqs access privileges, type, version, options, and description\&. +.RE +.PP +\edet[+] [ \fIpattern\fR ] +.RS 4 +Lists foreign tables (mnemonic: +\(lqexternal tables\(rq)\&. If +\fIpattern\fR +is specified, only entries whose table name or schema name matches the pattern are listed\&. If the form +\edet+ +is used, generic options and the foreign table description are also displayed\&. +.RE +.PP +\edeu[+] [ \fIpattern\fR ] +.RS 4 +Lists user mappings (mnemonic: +\(lqexternal users\(rq)\&. If +\fIpattern\fR +is specified, only those mappings whose user names match the pattern are listed\&. If the form +\edeu+ +is used, additional information about each mapping is shown\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +\edeu+ +might also display the user name and password of the remote user, so care should be taken not to disclose them\&. +.sp .5v +.RE +.RE +.PP +\edew[+] [ \fIpattern\fR ] +.RS 4 +Lists foreign\-data wrappers (mnemonic: +\(lqexternal wrappers\(rq)\&. If +\fIpattern\fR +is specified, only those foreign\-data wrappers whose name matches the pattern are listed\&. If the form +\edew+ +is used, the access privileges, options, and description of the foreign\-data wrapper are also shown\&. +.RE +.PP +\edf[anptwS+] [ \fIpattern\fR [ \fIarg_pattern\fR \&.\&.\&. ] ] +.RS 4 +Lists functions, together with their result data types, argument data types, and function types, which are classified as +\(lqagg\(rq +(aggregate), +\(lqnormal\(rq, +\(lqprocedure\(rq, +\(lqtrigger\(rq, or +\(lqwindow\(rq\&. To display only functions of specific type(s), add the corresponding letters +a, +n, +p, +t, or +w +to the command\&. If +\fIpattern\fR +is specified, only functions whose names match the pattern are shown\&. Any additional arguments are type\-name patterns, which are matched to the type names of the first, second, and so on arguments of the function\&. (Matching functions can have more arguments than what you specify\&. To prevent that, write a dash +\- +as the last +\fIarg_pattern\fR\&.) By default, only user\-created objects are shown; supply a pattern or the +S +modifier to include system objects\&. If the form +\edf+ +is used, additional information about each function is shown, including volatility, parallel safety, owner, security classification, access privileges, language, source code and description\&. +.RE +.PP +\edF[+] [ \fIpattern\fR ] +.RS 4 +Lists text search configurations\&. If +\fIpattern\fR +is specified, only configurations whose names match the pattern are shown\&. If the form +\edF+ +is used, a full description of each configuration is shown, including the underlying text search parser and the dictionary list for each parser token type\&. +.RE +.PP +\edFd[+] [ \fIpattern\fR ] +.RS 4 +Lists text search dictionaries\&. If +\fIpattern\fR +is specified, only dictionaries whose names match the pattern are shown\&. If the form +\edFd+ +is used, additional information is shown about each selected dictionary, including the underlying text search template and the option values\&. +.RE +.PP +\edFp[+] [ \fIpattern\fR ] +.RS 4 +Lists text search parsers\&. If +\fIpattern\fR +is specified, only parsers whose names match the pattern are shown\&. If the form +\edFp+ +is used, a full description of each parser is shown, including the underlying functions and the list of recognized token types\&. +.RE +.PP +\edFt[+] [ \fIpattern\fR ] +.RS 4 +Lists text search templates\&. If +\fIpattern\fR +is specified, only templates whose names match the pattern are shown\&. If the form +\edFt+ +is used, additional information is shown about each template, including the underlying function names\&. +.RE +.PP +\edg[S+] [ \fIpattern\fR ] +.RS 4 +Lists database roles\&. (Since the concepts of +\(lqusers\(rq +and +\(lqgroups\(rq +have been unified into +\(lqroles\(rq, this command is now equivalent to +\edu\&.) By default, only user\-created roles are shown; supply the +S +modifier to include system roles\&. If +\fIpattern\fR +is specified, only those roles whose names match the pattern are listed\&. If the form +\edg+ +is used, additional information is shown about each role; currently this adds the comment for each role\&. +.RE +.PP +\edl[+] +.RS 4 +This is an alias for +\fB\elo_list\fR, which shows a list of large objects\&. If ++ +is appended to the command name, each large object is listed with its associated permissions, if any\&. +.RE +.PP +\edL[S+] [ \fIpattern\fR ] +.RS 4 +Lists procedural languages\&. If +\fIpattern\fR +is specified, only languages whose names match the pattern are listed\&. By default, only user\-created languages are shown; supply the +S +modifier to include system objects\&. If ++ +is appended to the command name, each language is listed with its call handler, validator, access privileges, and whether it is a system object\&. +.RE +.PP +\edn[S+] [ \fIpattern\fR ] +.RS 4 +Lists schemas (namespaces)\&. If +\fIpattern\fR +is specified, only schemas whose names match the pattern are listed\&. By default, only user\-created objects are shown; supply a pattern or the +S +modifier to include system objects\&. If ++ +is appended to the command name, each object is listed with its associated permissions and description, if any\&. +.RE +.PP +\edo[S+] [ \fIpattern\fR [ \fIarg_pattern\fR [ \fIarg_pattern\fR ] ] ] +.RS 4 +Lists operators with their operand and result types\&. If +\fIpattern\fR +is specified, only operators whose names match the pattern are listed\&. If one +\fIarg_pattern\fR +is specified, only prefix operators whose right argument\*(Aqs type name matches that pattern are listed\&. If two +\fIarg_pattern\fRs are specified, only binary operators whose argument type names match those patterns are listed\&. (Alternatively, write +\- +for the unused argument of a unary operator\&.) By default, only user\-created objects are shown; supply a pattern or the +S +modifier to include system objects\&. If ++ +is appended to the command name, additional information about each operator is shown, currently just the name of the underlying function\&. +.RE +.PP +\edO[S+] [ \fIpattern\fR ] +.RS 4 +Lists collations\&. If +\fIpattern\fR +is specified, only collations whose names match the pattern are listed\&. By default, only user\-created objects are shown; supply a pattern or the +S +modifier to include system objects\&. If ++ +is appended to the command name, each collation is listed with its associated description, if any\&. Note that only collations usable with the current database\*(Aqs encoding are shown, so the results may vary in different databases of the same installation\&. +.RE +.PP +\edp [ \fIpattern\fR ] +.RS 4 +Lists tables, views and sequences with their associated access privileges\&. If +\fIpattern\fR +is specified, only tables, views and sequences whose names match the pattern are listed\&. +.sp +The +\fBGRANT\fR +and +\fBREVOKE\fR +commands are used to set access privileges\&. The meaning of the privilege display is explained in +Section\ \&5.7\&. +.RE +.PP +\edP[itn+] [ \fIpattern\fR ] +.RS 4 +Lists partitioned relations\&. If +\fIpattern\fR +is specified, only entries whose name matches the pattern are listed\&. The modifiers +t +(tables) and +i +(indexes) can be appended to the command, filtering the kind of relations to list\&. By default, partitioned tables and indexes are listed\&. +.sp +If the modifier +n +(\(lqnested\(rq) is used, or a pattern is specified, then non\-root partitioned relations are included, and a column is shown displaying the parent of each partitioned relation\&. +.sp +If ++ +is appended to the command name, the sum of the sizes of each relation\*(Aqs partitions is also displayed, along with the relation\*(Aqs description\&. If +n +is combined with ++, two sizes are shown: one including the total size of directly\-attached leaf partitions, and another showing the total size of all partitions, including indirectly attached sub\-partitions\&. +.RE +.PP +\edrds [ \fIrole\-pattern\fR [ \fIdatabase\-pattern\fR ] ] +.RS 4 +Lists defined configuration settings\&. These settings can be role\-specific, database\-specific, or both\&. +\fIrole\-pattern\fR +and +\fIdatabase\-pattern\fR +are used to select specific roles and databases to list, respectively\&. If omitted, or if +* +is specified, all settings are listed, including those not role\-specific or database\-specific, respectively\&. +.sp +The +\fBALTER ROLE\fR +and +\fBALTER DATABASE\fR +commands are used to define per\-role and per\-database configuration settings\&. +.RE +.PP +\edRp[+] [ \fIpattern\fR ] +.RS 4 +Lists replication publications\&. If +\fIpattern\fR +is specified, only those publications whose names match the pattern are listed\&. If ++ +is appended to the command name, the tables and schemas associated with each publication are shown as well\&. +.RE +.PP +\edRs[+] [ \fIpattern\fR ] +.RS 4 +Lists replication subscriptions\&. If +\fIpattern\fR +is specified, only those subscriptions whose names match the pattern are listed\&. If ++ +is appended to the command name, additional properties of the subscriptions are shown\&. +.RE +.PP +\edT[S+] [ \fIpattern\fR ] +.RS 4 +Lists data types\&. If +\fIpattern\fR +is specified, only types whose names match the pattern are listed\&. If ++ +is appended to the command name, each type is listed with its internal name and size, its allowed values if it is an +enum +type, and its associated permissions\&. By default, only user\-created objects are shown; supply a pattern or the +S +modifier to include system objects\&. +.RE +.PP +\edu[S+] [ \fIpattern\fR ] +.RS 4 +Lists database roles\&. (Since the concepts of +\(lqusers\(rq +and +\(lqgroups\(rq +have been unified into +\(lqroles\(rq, this command is now equivalent to +\edg\&.) By default, only user\-created roles are shown; supply the +S +modifier to include system roles\&. If +\fIpattern\fR +is specified, only those roles whose names match the pattern are listed\&. If the form +\edu+ +is used, additional information is shown about each role; currently this adds the comment for each role\&. +.RE +.PP +\edx[+] [ \fIpattern\fR ] +.RS 4 +Lists installed extensions\&. If +\fIpattern\fR +is specified, only those extensions whose names match the pattern are listed\&. If the form +\edx+ +is used, all the objects belonging to each matching extension are listed\&. +.RE +.PP +\edX [ \fIpattern\fR ] +.RS 4 +Lists extended statistics\&. If +\fIpattern\fR +is specified, only those extended statistics whose names match the pattern are listed\&. +.sp +The status of each kind of extended statistics is shown in a column named after its statistic kind (e\&.g\&. Ndistinct)\&. +defined +means that it was requested when creating the statistics, and NULL means it wasn\*(Aqt requested\&. You can use +pg_stats_ext +if you\*(Aqd like to know whether +\fBANALYZE\fR +was run and statistics are available to the planner\&. +.RE +.PP +\edy[+] [ \fIpattern\fR ] +.RS 4 +Lists event triggers\&. If +\fIpattern\fR +is specified, only those event triggers whose names match the pattern are listed\&. If ++ +is appended to the command name, each object is listed with its associated description\&. +.RE +.PP +\ee or \eedit [ \fIfilename\fR ] [ \fIline_number\fR ] +.RS 4 +If +\fIfilename\fR +is specified, the file is edited; after the editor exits, the file\*(Aqs content is copied into the current query buffer\&. If no +\fIfilename\fR +is given, the current query buffer is copied to a temporary file which is then edited in the same fashion\&. Or, if the current query buffer is empty, the most recently executed query is copied to a temporary file and edited in the same fashion\&. +.sp +If you edit a file or the previous query, and you quit the editor without modifying the file, the query buffer is cleared\&. Otherwise, the new contents of the query buffer are re\-parsed according to the normal rules of +psql, treating the whole buffer as a single line\&. Any complete queries are immediately executed; that is, if the query buffer contains or ends with a semicolon, everything up to that point is executed and removed from the query buffer\&. Whatever remains in the query buffer is redisplayed\&. Type semicolon or +\eg +to send it, or +\er +to cancel it by clearing the query buffer\&. +.sp +Treating the buffer as a single line primarily affects meta\-commands: whatever is in the buffer after a meta\-command will be taken as argument(s) to the meta\-command, even if it spans multiple lines\&. (Thus you cannot make meta\-command\-using scripts this way\&. Use +\fB\ei\fR +for that\&.) +.sp +If a line number is specified, +psql +will position the cursor on the specified line of the file or query buffer\&. Note that if a single all\-digits argument is given, +psql +assumes it is a line number, not a file name\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +See +Environment, below, for how to configure and customize your editor\&. +.sp .5v +.RE +.RE +.PP +\eecho \fItext\fR [ \&.\&.\&. ] +.RS 4 +Prints the evaluated arguments to standard output, separated by spaces and followed by a newline\&. This can be useful to intersperse information in the output of scripts\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +=> \fB\eecho `date`\fR +Tue Oct 26 21:40:57 CEST 1999 +.fi +.if n \{\ +.RE +.\} +.sp +If the first argument is an unquoted +\-n +the trailing newline is not written (nor is the first argument)\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +If you use the +\fB\eo\fR +command to redirect your query output you might wish to use +\fB\eqecho\fR +instead of this command\&. See also +\fB\ewarn\fR\&. +.sp .5v +.RE +.RE +.PP +\eef [ \fIfunction_description\fR [ \fIline_number\fR ] ] +.RS 4 +This command fetches and edits the definition of the named function or procedure, in the form of a +\fBCREATE OR REPLACE FUNCTION\fR +or +\fBCREATE OR REPLACE PROCEDURE\fR +command\&. Editing is done in the same way as for +\eedit\&. If you quit the editor without saving, the statement is discarded\&. If you save and exit the editor, the updated command is executed immediately if you added a semicolon to it\&. Otherwise it is redisplayed; type semicolon or +\eg +to send it, or +\er +to cancel\&. +.sp +The target function can be specified by name alone, or by name and arguments, for example +foo(integer, text)\&. The argument types must be given if there is more than one function of the same name\&. +.sp +If no function is specified, a blank +\fBCREATE FUNCTION\fR +template is presented for editing\&. +.sp +If a line number is specified, +psql +will position the cursor on the specified line of the function body\&. (Note that the function body typically does not begin on the first line of the file\&.) +.sp +Unlike most other meta\-commands, the entire remainder of the line is always taken to be the argument(s) of +\fB\eef\fR, and neither variable interpolation nor backquote expansion are performed in the arguments\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +See +Environment, below, for how to configure and customize your editor\&. +.sp .5v +.RE +.RE +.PP +\eencoding [ \fIencoding\fR ] +.RS 4 +Sets the client character set encoding\&. Without an argument, this command shows the current encoding\&. +.RE +.PP +\eerrverbose +.RS 4 +Repeats the most recent server error message at maximum verbosity, as though +\fIVERBOSITY\fR +were set to +verbose +and +\fISHOW_CONTEXT\fR +were set to +always\&. +.RE +.PP +\eev [ \fIview_name\fR [ \fIline_number\fR ] ] +.RS 4 +This command fetches and edits the definition of the named view, in the form of a +\fBCREATE OR REPLACE VIEW\fR +command\&. Editing is done in the same way as for +\eedit\&. If you quit the editor without saving, the statement is discarded\&. If you save and exit the editor, the updated command is executed immediately if you added a semicolon to it\&. Otherwise it is redisplayed; type semicolon or +\eg +to send it, or +\er +to cancel\&. +.sp +If no view is specified, a blank +\fBCREATE VIEW\fR +template is presented for editing\&. +.sp +If a line number is specified, +psql +will position the cursor on the specified line of the view definition\&. +.sp +Unlike most other meta\-commands, the entire remainder of the line is always taken to be the argument(s) of +\fB\eev\fR, and neither variable interpolation nor backquote expansion are performed in the arguments\&. +.RE +.PP +\ef [ \fIstring\fR ] +.RS 4 +Sets the field separator for unaligned query output\&. The default is the vertical bar (|)\&. It is equivalent to +\fB\epset fieldsep\fR\&. +.RE +.PP +\eg [ (\fIoption\fR=\fIvalue\fR [\&.\&.\&.]) ] [ \fIfilename\fR ] +.br +\eg [ (\fIoption\fR=\fIvalue\fR [\&.\&.\&.]) ] [ |\fIcommand\fR ] +.RS 4 +Sends the current query buffer to the server for execution\&. +.sp +If parentheses appear after +\eg, they surround a space\-separated list of +\fIoption\fR=\fIvalue\fR +formatting\-option clauses, which are interpreted in the same way as +\epset +\fIoption\fR +\fIvalue\fR +commands, but take effect only for the duration of this query\&. In this list, spaces are not allowed around += +signs, but are required between option clauses\&. If +=\fIvalue\fR +is omitted, the named +\fIoption\fR +is changed in the same way as for +\epset +\fIoption\fR +with no explicit +\fIvalue\fR\&. +.sp +If a +\fIfilename\fR +or +|\fIcommand\fR +argument is given, the query\*(Aqs output is written to the named file or piped to the given shell command, instead of displaying it as usual\&. The file or command is written to only if the query successfully returns zero or more tuples, not if the query fails or is a non\-data\-returning SQL command\&. +.sp +If the current query buffer is empty, the most recently sent query is re\-executed instead\&. Except for that behavior, +\eg +without any arguments is essentially equivalent to a semicolon\&. With arguments, +\eg +provides a +\(lqone\-shot\(rq +alternative to the +\fB\eo\fR +command, and additionally allows one\-shot adjustments of the output formatting options normally set by +\epset\&. +.sp +When the last argument begins with +|, the entire remainder of the line is taken to be the +\fIcommand\fR +to execute, and neither variable interpolation nor backquote expansion are performed in it\&. The rest of the line is simply passed literally to the shell\&. +.RE +.PP +\egdesc +.RS 4 +Shows the description (that is, the column names and data types) of the result of the current query buffer\&. The query is not actually executed; however, if it contains some type of syntax error, that error will be reported in the normal way\&. +.sp +If the current query buffer is empty, the most recently sent query is described instead\&. +.RE +.PP +\egetenv \fIpsql_var\fR \fIenv_var\fR +.RS 4 +Gets the value of the environment variable +\fIenv_var\fR +and assigns it to the +psql +variable +\fIpsql_var\fR\&. If +\fIenv_var\fR +is not defined in the +psql +process\*(Aqs environment, +\fIpsql_var\fR +is not changed\&. Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +=> \fB\egetenv home HOME\fR +=> \fB\eecho :home\fR +/home/postgres +.fi +.if n \{\ +.RE +.\} +.RE +.PP +\egexec +.RS 4 +Sends the current query buffer to the server, then treats each column of each row of the query\*(Aqs output (if any) as an SQL statement to be executed\&. For example, to create an index on each column of +my_table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +=> \fBSELECT format(\*(Aqcreate index on my_table(%I)\*(Aq, attname)\fR +\-> \fBFROM pg_attribute\fR +\-> \fBWHERE attrelid = \*(Aqmy_table\*(Aq::regclass AND attnum > 0\fR +\-> \fBORDER BY attnum\fR +\-> \fB\egexec\fR +CREATE INDEX +CREATE INDEX +CREATE INDEX +CREATE INDEX +.fi +.if n \{\ +.RE +.\} +.sp +The generated queries are executed in the order in which the rows are returned, and left\-to\-right within each row if there is more than one column\&. NULL fields are ignored\&. The generated queries are sent literally to the server for processing, so they cannot be +psql +meta\-commands nor contain +psql +variable references\&. If any individual query fails, execution of the remaining queries continues unless +\fION_ERROR_STOP\fR +is set\&. Execution of each query is subject to +\fIECHO\fR +processing\&. (Setting +\fIECHO\fR +to +all +or +queries +is often advisable when using +\fB\egexec\fR\&.) Query logging, single\-step mode, timing, and other query execution features apply to each generated query as well\&. +.sp +If the current query buffer is empty, the most recently sent query is re\-executed instead\&. +.RE +.PP +\egset [ \fIprefix\fR ] +.RS 4 +Sends the current query buffer to the server and stores the query\*(Aqs output into +psql +variables (see +Variables +below)\&. The query to be executed must return exactly one row\&. Each column of the row is stored into a separate variable, named the same as the column\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +=> \fBSELECT \*(Aqhello\*(Aq AS var1, 10 AS var2\fR +\-> \fB\egset\fR +=> \fB\eecho :var1 :var2\fR +hello 10 +.fi +.if n \{\ +.RE +.\} +.sp +If you specify a +\fIprefix\fR, that string is prepended to the query\*(Aqs column names to create the variable names to use: +.sp +.if n \{\ +.RS 4 +.\} +.nf +=> \fBSELECT \*(Aqhello\*(Aq AS var1, 10 AS var2\fR +\-> \fB\egset result_\fR +=> \fB\eecho :result_var1 :result_var2\fR +hello 10 +.fi +.if n \{\ +.RE +.\} +.sp +If a column result is NULL, the corresponding variable is unset rather than being set\&. +.sp +If the query fails or does not return one row, no variables are changed\&. +.sp +If the current query buffer is empty, the most recently sent query is re\-executed instead\&. +.RE +.PP +\egx [ (\fIoption\fR=\fIvalue\fR [\&.\&.\&.]) ] [ \fIfilename\fR ] +.br +\egx [ (\fIoption\fR=\fIvalue\fR [\&.\&.\&.]) ] [ |\fIcommand\fR ] +.RS 4 +\egx +is equivalent to +\eg, except that it forces expanded output mode for this query, as if +expanded=on +were included in the list of +\epset +options\&. See also +\ex\&. +.RE +.PP +\eh or \ehelp [ \fIcommand\fR ] +.RS 4 +Gives syntax help on the specified +SQL +command\&. If +\fIcommand\fR +is not specified, then +psql +will list all the commands for which syntax help is available\&. If +\fIcommand\fR +is an asterisk (*), then syntax help on all +SQL +commands is shown\&. +.sp +Unlike most other meta\-commands, the entire remainder of the line is always taken to be the argument(s) of +\fB\ehelp\fR, and neither variable interpolation nor backquote expansion are performed in the arguments\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +To simplify typing, commands that consists of several words do not have to be quoted\&. Thus it is fine to type +\fB\ehelp alter table\fR\&. +.sp .5v +.RE +.RE +.PP +\eH or \ehtml +.RS 4 +Turns on +HTML +query output format\&. If the +HTML +format is already on, it is switched back to the default aligned text format\&. This command is for compatibility and convenience, but see +\fB\epset\fR +about setting other output options\&. +.RE +.PP +\ei or \einclude \fIfilename\fR +.RS 4 +Reads input from the file +\fIfilename\fR +and executes it as though it had been typed on the keyboard\&. +.sp +If +\fIfilename\fR +is +\- +(hyphen), then standard input is read until an EOF indication or +\fB\eq\fR +meta\-command\&. This can be used to intersperse interactive input with input from files\&. Note that Readline behavior will be used only if it is active at the outermost level\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +If you want to see the lines on the screen as they are read you must set the variable +\fIECHO\fR +to +all\&. +.sp .5v +.RE +.RE +.PP +\eif \fIexpression\fR +.br +\eelif \fIexpression\fR +.br +\eelse +.br +\eendif +.RS 4 +This group of commands implements nestable conditional blocks\&. A conditional block must begin with an +\fB\eif\fR +and end with an +\fB\eendif\fR\&. In between there may be any number of +\fB\eelif\fR +clauses, which may optionally be followed by a single +\fB\eelse\fR +clause\&. Ordinary queries and other types of backslash commands may (and usually do) appear between the commands forming a conditional block\&. +.sp +The +\fB\eif\fR +and +\fB\eelif\fR +commands read their argument(s) and evaluate them as a Boolean expression\&. If the expression yields +true +then processing continues normally; otherwise, lines are skipped until a matching +\fB\eelif\fR, +\fB\eelse\fR, or +\fB\eendif\fR +is reached\&. Once an +\fB\eif\fR +or +\fB\eelif\fR +test has succeeded, the arguments of later +\fB\eelif\fR +commands in the same block are not evaluated but are treated as false\&. Lines following an +\fB\eelse\fR +are processed only if no earlier matching +\fB\eif\fR +or +\fB\eelif\fR +succeeded\&. +.sp +The +\fIexpression\fR +argument of an +\fB\eif\fR +or +\fB\eelif\fR +command is subject to variable interpolation and backquote expansion, just like any other backslash command argument\&. After that it is evaluated like the value of an on/off option variable\&. So a valid value is any unambiguous case\-insensitive match for one of: +true, +false, +1, +0, +on, +off, +yes, +no\&. For example, +t, +T, and +tR +will all be considered to be +true\&. +.sp +Expressions that do not properly evaluate to true or false will generate a warning and be treated as false\&. +.sp +Lines being skipped are parsed normally to identify queries and backslash commands, but queries are not sent to the server, and backslash commands other than conditionals (\fB\eif\fR, +\fB\eelif\fR, +\fB\eelse\fR, +\fB\eendif\fR) are ignored\&. Conditional commands are checked only for valid nesting\&. Variable references in skipped lines are not expanded, and backquote expansion is not performed either\&. +.sp +All the backslash commands of a given conditional block must appear in the same source file\&. If EOF is reached on the main input file or an +\fB\einclude\fR\-ed file before all local +\fB\eif\fR\-blocks have been closed, then +psql +will raise an error\&. +.sp +Here is an example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\-\- check for the existence of two separate records in the database and store +\-\- the results in separate psql variables +SELECT + EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer, + EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee +\egset +\eif :is_customer + SELECT * FROM customer WHERE customer_id = 123; +\eelif :is_employee + \eecho \*(Aqis not a customer but is an employee\*(Aq + SELECT * FROM employee WHERE employee_id = 456; +\eelse + \eif yes + \eecho \*(Aqnot a customer or employee\*(Aq + \eelse + \eecho \*(Aqthis will never print\*(Aq + \eendif +\eendif +.fi +.if n \{\ +.RE +.\} +.RE +.PP +\eir or \einclude_relative \fIfilename\fR +.RS 4 +The +\eir +command is similar to +\ei, but resolves relative file names differently\&. When executing in interactive mode, the two commands behave identically\&. However, when invoked from a script, +\eir +interprets file names relative to the directory in which the script is located, rather than the current working directory\&. +.RE +.PP +\el[+] or \elist[+] [ \fIpattern\fR ] +.RS 4 +List the databases in the server and show their names, owners, character set encodings, and access privileges\&. If +\fIpattern\fR +is specified, only databases whose names match the pattern are listed\&. If ++ +is appended to the command name, database sizes, default tablespaces, and descriptions are also displayed\&. (Size information is only available for databases that the current user can connect to\&.) +.RE +.PP +\elo_export \fIloid\fR \fIfilename\fR +.RS 4 +Reads the large object with +OID +\fIloid\fR +from the database and writes it to +\fIfilename\fR\&. Note that this is subtly different from the server function +\fBlo_export\fR, which acts with the permissions of the user that the database server runs as and on the server\*(Aqs file system\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +Use +\fB\elo_list\fR +to find out the large object\*(Aqs +OID\&. +.sp .5v +.RE +.RE +.PP +\elo_import \fIfilename\fR [ \fIcomment\fR ] +.RS 4 +Stores the file into a +PostgreSQL +large object\&. Optionally, it associates the given comment with the object\&. Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +foo=> \fB\elo_import \*(Aq/home/peter/pictures/photo\&.xcf\*(Aq \*(Aqa picture of me\*(Aq\fR +lo_import 152801 +.fi +.if n \{\ +.RE +.\} +.sp +The response indicates that the large object received object ID 152801, which can be used to access the newly\-created large object in the future\&. For the sake of readability, it is recommended to always associate a human\-readable comment with every object\&. Both OIDs and comments can be viewed with the +\fB\elo_list\fR +command\&. +.sp +Note that this command is subtly different from the server\-side +\fBlo_import\fR +because it acts as the local user on the local file system, rather than the server\*(Aqs user and file system\&. +.RE +.PP +\elo_list[+] +.RS 4 +Shows a list of all +PostgreSQL +large objects currently stored in the database, along with any comments provided for them\&. If ++ +is appended to the command name, each large object is listed with its associated permissions, if any\&. +.RE +.PP +\elo_unlink \fIloid\fR +.RS 4 +Deletes the large object with +OID +\fIloid\fR +from the database\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +Use +\fB\elo_list\fR +to find out the large object\*(Aqs +OID\&. +.sp .5v +.RE +.RE +.PP +\eo or \eout [ \fIfilename\fR ] +.br +\eo or \eout [ |\fIcommand\fR ] +.RS 4 +Arranges to save future query results to the file +\fIfilename\fR +or pipe future results to the shell command +\fIcommand\fR\&. If no argument is specified, the query output is reset to the standard output\&. +.sp +If the argument begins with +|, then the entire remainder of the line is taken to be the +\fIcommand\fR +to execute, and neither variable interpolation nor backquote expansion are performed in it\&. The rest of the line is simply passed literally to the shell\&. +.sp +\(lqQuery results\(rq +includes all tables, command responses, and notices obtained from the database server, as well as output of various backslash commands that query the database (such as +\fB\ed\fR); but not error messages\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +To intersperse text output in between query results, use +\fB\eqecho\fR\&. +.sp .5v +.RE +.RE +.PP +\ep or \eprint +.RS 4 +Print the current query buffer to the standard output\&. If the current query buffer is empty, the most recently executed query is printed instead\&. +.RE +.PP +\epassword [ \fIusername\fR ] +.RS 4 +Changes the password of the specified user (by default, the current user)\&. This command prompts for the new password, encrypts it, and sends it to the server as an +\fBALTER ROLE\fR +command\&. This makes sure that the new password does not appear in cleartext in the command history, the server log, or elsewhere\&. +.RE +.PP +\eprompt [ \fItext\fR ] \fIname\fR +.RS 4 +Prompts the user to supply text, which is assigned to the variable +\fIname\fR\&. An optional prompt string, +\fItext\fR, can be specified\&. (For multiword prompts, surround the text with single quotes\&.) +.sp +By default, +\eprompt +uses the terminal for input and output\&. However, if the +\fB\-f\fR +command line switch was used, +\eprompt +uses standard input and standard output\&. +.RE +.PP +\epset [ \fIoption\fR [ \fIvalue\fR ] ] +.RS 4 +This command sets options affecting the output of query result tables\&. +\fIoption\fR +indicates which option is to be set\&. The semantics of +\fIvalue\fR +vary depending on the selected option\&. For some options, omitting +\fIvalue\fR +causes the option to be toggled or unset, as described under the particular option\&. If no such behavior is mentioned, then omitting +\fIvalue\fR +just results in the current setting being displayed\&. +.sp +\fB\epset\fR +without any arguments displays the current status of all printing options\&. +.sp +Adjustable printing options are: +.PP +border +.RS 4 +The +\fIvalue\fR +must be a number\&. In general, the higher the number the more borders and lines the tables will have, but details depend on the particular format\&. In +HTML +format, this will translate directly into the +border=\&.\&.\&. +attribute\&. In most other formats only values 0 (no border), 1 (internal dividing lines), and 2 (table frame) make sense, and values above 2 will be treated the same as +border = 2\&. The +latex +and +latex\-longtable +formats additionally allow a value of 3 to add dividing lines between data rows\&. +.RE +.PP +columns +.RS 4 +Sets the target width for the +wrapped +format, and also the width limit for determining whether output is wide enough to require the pager or switch to the vertical display in expanded auto mode\&. Zero (the default) causes the target width to be controlled by the environment variable +\fBCOLUMNS\fR, or the detected screen width if +\fBCOLUMNS\fR +is not set\&. In addition, if +columns +is zero then the +wrapped +format only affects screen output\&. If +columns +is nonzero then file and pipe output is wrapped to that width as well\&. +.RE +.PP +csv_fieldsep +.RS 4 +Specifies the field separator to be used in +CSV +output format\&. If the separator character appears in a field\*(Aqs value, that field is output within double quotes, following standard +CSV +rules\&. The default is a comma\&. +.RE +.PP +expanded (or x) +.RS 4 +If +\fIvalue\fR +is specified it must be either +on +or +off, which will enable or disable expanded mode, or +auto\&. If +\fIvalue\fR +is omitted the command toggles between the on and off settings\&. When expanded mode is enabled, query results are displayed in two columns, with the column name on the left and the data on the right\&. This mode is useful if the data wouldn\*(Aqt fit on the screen in the normal +\(lqhorizontal\(rq +mode\&. In the auto setting, the expanded mode is used whenever the query output has more than one column and is wider than the screen; otherwise, the regular mode is used\&. The auto setting is only effective in the aligned and wrapped formats\&. In other formats, it always behaves as if the expanded mode is off\&. +.RE +.PP +fieldsep +.RS 4 +Specifies the field separator to be used in unaligned output format\&. That way one can create, for example, tab\-separated output, which other programs might prefer\&. To set a tab as field separator, type +\epset fieldsep \*(Aq\et\*(Aq\&. The default field separator is +\*(Aq|\*(Aq +(a vertical bar)\&. +.RE +.PP +fieldsep_zero +.RS 4 +Sets the field separator to use in unaligned output format to a zero byte\&. +.RE +.PP +footer +.RS 4 +If +\fIvalue\fR +is specified it must be either +on +or +off +which will enable or disable display of the table footer (the +(\fIn\fR rows) +count)\&. If +\fIvalue\fR +is omitted the command toggles footer display on or off\&. +.RE +.PP +format +.RS 4 +Sets the output format to one of +aligned, +asciidoc, +csv, +html, +latex, +latex\-longtable, +troff\-ms, +unaligned, or +wrapped\&. Unique abbreviations are allowed\&. +.sp +aligned +format is the standard, human\-readable, nicely formatted text output; this is the default\&. +.sp +unaligned +format writes all columns of a row on one line, separated by the currently active field separator\&. This is useful for creating output that might be intended to be read in by other programs, for example, tab\-separated or comma\-separated format\&. However, the field separator character is not treated specially if it appears in a column\*(Aqs value; so +CSV +format may be better suited for such purposes\&. +.sp +csv +format + +writes column values separated by commas, applying the quoting rules described in +\m[blue]\fBRFC 4180\fR\m[]\&. This output is compatible with the CSV format of the server\*(Aqs +\fBCOPY\fR +command\&. A header line with column names is generated unless the +tuples_only +parameter is +on\&. Titles and footers are not printed\&. Each row is terminated by the system\-dependent end\-of\-line character, which is typically a single newline (\en) for Unix\-like systems or a carriage return and newline sequence (\er\en) for Microsoft Windows\&. Field separator characters other than comma can be selected with +\fB\epset csv_fieldsep\fR\&. +.sp +wrapped +format is like +aligned +but wraps wide data values across lines to make the output fit in the target column width\&. The target width is determined as described under the +columns +option\&. Note that +psql +will not attempt to wrap column header titles; therefore, +wrapped +format behaves the same as +aligned +if the total width needed for column headers exceeds the target\&. +.sp +The +asciidoc, +html, +latex, +latex\-longtable, and +troff\-ms +formats put out tables that are intended to be included in documents using the respective mark\-up language\&. They are not complete documents! This might not be necessary in +HTML, but in +LaTeX +you must have a complete document wrapper\&. The +latex +format uses +LaTeX\*(Aqs +tabular +environment\&. The +latex\-longtable +format requires the +LaTeX +longtable +and +booktabs +packages\&. +.RE +.PP +linestyle +.RS 4 +Sets the border line drawing style to one of +ascii, +old\-ascii, or +unicode\&. Unique abbreviations are allowed\&. (That would mean one letter is enough\&.) The default setting is +ascii\&. This option only affects the +aligned +and +wrapped +output formats\&. +.sp +ascii +style uses plain +ASCII +characters\&. Newlines in data are shown using a ++ +symbol in the right\-hand margin\&. When the +wrapped +format wraps data from one line to the next without a newline character, a dot (\&.) is shown in the right\-hand margin of the first line, and again in the left\-hand margin of the following line\&. +.sp +old\-ascii +style uses plain +ASCII +characters, using the formatting style used in +PostgreSQL +8\&.4 and earlier\&. Newlines in data are shown using a +: +symbol in place of the left\-hand column separator\&. When the data is wrapped from one line to the next without a newline character, a +; +symbol is used in place of the left\-hand column separator\&. +.sp +unicode +style uses Unicode box\-drawing characters\&. Newlines in data are shown using a carriage return symbol in the right\-hand margin\&. When the data is wrapped from one line to the next without a newline character, an ellipsis symbol is shown in the right\-hand margin of the first line, and again in the left\-hand margin of the following line\&. +.sp +When the +border +setting is greater than zero, the +linestyle +option also determines the characters with which the border lines are drawn\&. Plain +ASCII +characters work everywhere, but Unicode characters look nicer on displays that recognize them\&. +.RE +.PP +null +.RS 4 +Sets the string to be printed in place of a null value\&. The default is to print nothing, which can easily be mistaken for an empty string\&. For example, one might prefer +\epset null \*(Aq(null)\*(Aq\&. +.RE +.PP +numericlocale +.RS 4 +If +\fIvalue\fR +is specified it must be either +on +or +off +which will enable or disable display of a locale\-specific character to separate groups of digits to the left of the decimal marker\&. If +\fIvalue\fR +is omitted the command toggles between regular and locale\-specific numeric output\&. +.RE +.PP +pager +.RS 4 +Controls use of a pager program for query and +psql +help output\&. When the +pager +option is +off, the pager program is not used\&. When the +pager +option is +on, the pager is used when appropriate, i\&.e\&., when the output is to a terminal and will not fit on the screen\&. The +pager +option can also be set to +always, which causes the pager to be used for all terminal output regardless of whether it fits on the screen\&. +\epset pager +without a +\fIvalue\fR +toggles pager use on and off\&. +.sp +If the environment variable +\fBPSQL_PAGER\fR +or +\fBPAGER\fR +is set, output to be paged is piped to the specified program\&. Otherwise a platform\-dependent default program (such as +more) is used\&. +.sp +When using the +\ewatch +command to execute a query repeatedly, the environment variable +\fBPSQL_WATCH_PAGER\fR +is used to find the pager program instead, on Unix systems\&. This is configured separately because it may confuse traditional pagers, but can be used to send output to tools that understand +psql\*(Aqs output format (such as +pspg \-\-stream)\&. +.RE +.PP +pager_min_lines +.RS 4 +If +pager_min_lines +is set to a number greater than the page height, the pager program will not be called unless there are at least this many lines of output to show\&. The default setting is 0\&. +.RE +.PP +recordsep +.RS 4 +Specifies the record (line) separator to use in unaligned output format\&. The default is a newline character\&. +.RE +.PP +recordsep_zero +.RS 4 +Sets the record separator to use in unaligned output format to a zero byte\&. +.RE +.PP +tableattr (or T) +.RS 4 +In +HTML +format, this specifies attributes to be placed inside the +table +tag\&. This could for example be +cellpadding +or +bgcolor\&. Note that you probably don\*(Aqt want to specify +border +here, as that is already taken care of by +\epset border\&. If no +\fIvalue\fR +is given, the table attributes are unset\&. +.sp +In +latex\-longtable +format, this controls the proportional width of each column containing a left\-aligned data type\&. It is specified as a whitespace\-separated list of values, e\&.g\&., +\*(Aq0\&.2 0\&.2 0\&.6\*(Aq\&. Unspecified output columns use the last specified value\&. +.RE +.PP +title (or C) +.RS 4 +Sets the table title for any subsequently printed tables\&. This can be used to give your output descriptive tags\&. If no +\fIvalue\fR +is given, the title is unset\&. +.RE +.PP +tuples_only (or t) +.RS 4 +If +\fIvalue\fR +is specified it must be either +on +or +off +which will enable or disable tuples\-only mode\&. If +\fIvalue\fR +is omitted the command toggles between regular and tuples\-only output\&. Regular output includes extra information such as column headers, titles, and various footers\&. In tuples\-only mode, only actual table data is shown\&. +.RE +.PP +unicode_border_linestyle +.RS 4 +Sets the border drawing style for the +unicode +line style to one of +single +or +double\&. +.RE +.PP +unicode_column_linestyle +.RS 4 +Sets the column drawing style for the +unicode +line style to one of +single +or +double\&. +.RE +.PP +unicode_header_linestyle +.RS 4 +Sets the header drawing style for the +unicode +line style to one of +single +or +double\&. +.RE +.sp +Illustrations of how these different formats look can be seen in +Examples, below\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +There are various shortcut commands for +\fB\epset\fR\&. See +\fB\ea\fR, +\fB\eC\fR, +\fB\ef\fR, +\fB\eH\fR, +\fB\et\fR, +\fB\eT\fR, and +\fB\ex\fR\&. +.sp .5v +.RE +.RE +.PP +\eq or \equit +.RS 4 +Quits the +psql +program\&. In a script file, only execution of that script is terminated\&. +.RE +.PP +\eqecho \fItext\fR [ \&.\&.\&. ] +.RS 4 +This command is identical to +\fB\eecho\fR +except that the output will be written to the query output channel, as set by +\fB\eo\fR\&. +.RE +.PP +\er or \ereset +.RS 4 +Resets (clears) the query buffer\&. +.RE +.PP +\es [ \fIfilename\fR ] +.RS 4 +Print +psql\*(Aqs command line history to +\fIfilename\fR\&. If +\fIfilename\fR +is omitted, the history is written to the standard output (using the pager if appropriate)\&. This command is not available if +psql +was built without +Readline +support\&. +.RE +.PP +\eset [ \fIname\fR [ \fIvalue\fR [ \&.\&.\&. ] ] ] +.RS 4 +Sets the +psql +variable +\fIname\fR +to +\fIvalue\fR, or if more than one value is given, to the concatenation of all of them\&. If only one argument is given, the variable is set to an empty\-string value\&. To unset a variable, use the +\fB\eunset\fR +command\&. +.sp +\fB\eset\fR +without any arguments displays the names and values of all currently\-set +psql +variables\&. +.sp +Valid variable names can contain letters, digits, and underscores\&. See +Variables +below for details\&. Variable names are case\-sensitive\&. +.sp +Certain variables are special, in that they control +psql\*(Aqs behavior or are automatically set to reflect connection state\&. These variables are documented in +Variables, below\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This command is unrelated to the +SQL +command +\fBSET\fR\&. +.sp .5v +.RE +.RE +.PP +\esetenv \fIname\fR [ \fIvalue\fR ] +.RS 4 +Sets the environment variable +\fIname\fR +to +\fIvalue\fR, or if the +\fIvalue\fR +is not supplied, unsets the environment variable\&. Example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fB\esetenv PAGER less\fR +testdb=> \fB\esetenv LESS \-imx4F\fR +.fi +.if n \{\ +.RE +.\} +.RE +.PP +\esf[+] \fIfunction_description\fR +.RS 4 +This command fetches and shows the definition of the named function or procedure, in the form of a +\fBCREATE OR REPLACE FUNCTION\fR +or +\fBCREATE OR REPLACE PROCEDURE\fR +command\&. The definition is printed to the current query output channel, as set by +\fB\eo\fR\&. +.sp +The target function can be specified by name alone, or by name and arguments, for example +foo(integer, text)\&. The argument types must be given if there is more than one function of the same name\&. +.sp +If ++ +is appended to the command name, then the output lines are numbered, with the first line of the function body being line 1\&. +.sp +Unlike most other meta\-commands, the entire remainder of the line is always taken to be the argument(s) of +\fB\esf\fR, and neither variable interpolation nor backquote expansion are performed in the arguments\&. +.RE +.PP +\esv[+] \fIview_name\fR +.RS 4 +This command fetches and shows the definition of the named view, in the form of a +\fBCREATE OR REPLACE VIEW\fR +command\&. The definition is printed to the current query output channel, as set by +\fB\eo\fR\&. +.sp +If ++ +is appended to the command name, then the output lines are numbered from 1\&. +.sp +Unlike most other meta\-commands, the entire remainder of the line is always taken to be the argument(s) of +\fB\esv\fR, and neither variable interpolation nor backquote expansion are performed in the arguments\&. +.RE +.PP +\et +.RS 4 +Toggles the display of output column name headings and row count footer\&. This command is equivalent to +\epset tuples_only +and is provided for convenience\&. +.RE +.PP +\eT \fItable_options\fR +.RS 4 +Specifies attributes to be placed within the +table +tag in +HTML +output format\&. This command is equivalent to +\epset tableattr \fItable_options\fR\&. +.RE +.PP +\etiming [ \fIon\fR | \fIoff\fR ] +.RS 4 +With a parameter, turns displaying of how long each SQL statement takes on or off\&. Without a parameter, toggles the display between on and off\&. The display is in milliseconds; intervals longer than 1 second are also shown in minutes:seconds format, with hours and days fields added if needed\&. +.RE +.PP +\eunset \fIname\fR +.RS 4 +Unsets (deletes) the +psql +variable +\fIname\fR\&. +.sp +Most variables that control +psql\*(Aqs behavior cannot be unset; instead, an +\eunset +command is interpreted as setting them to their default values\&. See +Variables +below\&. +.RE +.PP +\ew or \ewrite \fIfilename\fR +.br +\ew or \ewrite |\fIcommand\fR +.RS 4 +Writes the current query buffer to the file +\fIfilename\fR +or pipes it to the shell command +\fIcommand\fR\&. If the current query buffer is empty, the most recently executed query is written instead\&. +.sp +If the argument begins with +|, then the entire remainder of the line is taken to be the +\fIcommand\fR +to execute, and neither variable interpolation nor backquote expansion are performed in it\&. The rest of the line is simply passed literally to the shell\&. +.RE +.PP +\ewarn \fItext\fR [ \&.\&.\&. ] +.RS 4 +This command is identical to +\fB\eecho\fR +except that the output will be written to +psql\*(Aqs standard error channel, rather than standard output\&. +.RE +.PP +\ewatch [ \fIseconds\fR ] +.RS 4 +Repeatedly execute the current query buffer (as +\eg +does) until interrupted or the query fails\&. Wait the specified number of seconds (default 2) between executions\&. Each query result is displayed with a header that includes the +\epset title +string (if any), the time as of query start, and the delay interval\&. +.sp +If the current query buffer is empty, the most recently sent query is re\-executed instead\&. +.RE +.PP +\ex [ \fIon\fR | \fIoff\fR | \fIauto\fR ] +.RS 4 +Sets or toggles expanded table formatting mode\&. As such it is equivalent to +\epset expanded\&. +.RE +.PP +\ez [ \fIpattern\fR ] +.RS 4 +Lists tables, views and sequences with their associated access privileges\&. If a +\fIpattern\fR +is specified, only tables, views and sequences whose names match the pattern are listed\&. +.sp +This is an alias for +\fB\edp\fR +(\(lqdisplay privileges\(rq)\&. +.RE +.PP +\e! [ \fIcommand\fR ] +.RS 4 +With no argument, escapes to a sub\-shell; +psql +resumes when the sub\-shell exits\&. With an argument, executes the shell command +\fIcommand\fR\&. +.sp +Unlike most other meta\-commands, the entire remainder of the line is always taken to be the argument(s) of +\fB\e!\fR, and neither variable interpolation nor backquote expansion are performed in the arguments\&. The rest of the line is simply passed literally to the shell\&. +.RE +.PP +\e? [ \fItopic\fR ] +.RS 4 +Shows help information\&. The optional +\fItopic\fR +parameter (defaulting to +commands) selects which part of +psql +is explained: +commands +describes +psql\*(Aqs backslash commands; +options +describes the command\-line options that can be passed to +psql; and +variables +shows help about +psql +configuration variables\&. +.RE +.PP +\e; +.RS 4 +Backslash\-semicolon is not a meta\-command in the same way as the preceding commands; rather, it simply causes a semicolon to be added to the query buffer without any further processing\&. +.sp +Normally, +psql +will dispatch an SQL command to the server as soon as it reaches the command\-ending semicolon, even if more input remains on the current line\&. Thus for example entering +.sp +.if n \{\ +.RS 4 +.\} +.nf +select 1; select 2; select 3; +.fi +.if n \{\ +.RE +.\} +.sp +will result in the three SQL commands being individually sent to the server, with each one\*(Aqs results being displayed before continuing to the next command\&. However, a semicolon entered as +\e; +will not trigger command processing, so that the command before it and the one after are effectively combined and sent to the server in one request\&. So for example +.sp +.if n \{\ +.RS 4 +.\} +.nf +select 1\e; select 2\e; select 3; +.fi +.if n \{\ +.RE +.\} +.sp +results in sending the three SQL commands to the server in a single request, when the non\-backslashed semicolon is reached\&. The server executes such a request as a single transaction, unless there are explicit +\fBBEGIN\fR/\fBCOMMIT\fR +commands included in the string to divide it into multiple transactions\&. (See +Section\ \&55.2.2.1 +for more details about how the server handles multi\-query strings\&.) +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBPatterns\fR +.RS 4 +.PP +The various +\ed +commands accept a +\fIpattern\fR +parameter to specify the object name(s) to be displayed\&. In the simplest case, a pattern is just the exact name of the object\&. The characters within a pattern are normally folded to lower case, just as in SQL names; for example, +\edt FOO +will display the table named +foo\&. As in SQL names, placing double quotes around a pattern stops folding to lower case\&. Should you need to include an actual double quote character in a pattern, write it as a pair of double quotes within a double\-quote sequence; again this is in accord with the rules for SQL quoted identifiers\&. For example, +\edt "FOO""BAR" +will display the table named +FOO"BAR +(not +foo"bar)\&. Unlike the normal rules for SQL names, you can put double quotes around just part of a pattern, for instance +\edt FOO"FOO"BAR +will display the table named +fooFOObar\&. +.PP +Whenever the +\fIpattern\fR +parameter is omitted completely, the +\ed +commands display all objects that are visible in the current schema search path \(em this is equivalent to using +* +as the pattern\&. (An object is said to be +visible +if its containing schema is in the search path and no object of the same kind and name appears earlier in the search path\&. This is equivalent to the statement that the object can be referenced by name without explicit schema qualification\&.) To see all objects in the database regardless of visibility, use +*\&.* +as the pattern\&. +.PP +Within a pattern, +* +matches any sequence of characters (including no characters) and +? +matches any single character\&. (This notation is comparable to Unix shell file name patterns\&.) For example, +\edt int* +displays tables whose names begin with +int\&. But within double quotes, +* +and +? +lose these special meanings and are just matched literally\&. +.PP +A relation pattern that contains a dot (\&.) is interpreted as a schema name pattern followed by an object name pattern\&. For example, +\edt foo*\&.*bar* +displays all tables whose table name includes +bar +that are in schemas whose schema name starts with +foo\&. When no dot appears, then the pattern matches only objects that are visible in the current schema search path\&. Again, a dot within double quotes loses its special meaning and is matched literally\&. A relation pattern that contains two dots (\&.) is interpreted as a database name followed by a schema name pattern followed by an object name pattern\&. The database name portion will not be treated as a pattern and must match the name of the currently connected database, else an error will be raised\&. +.PP +A schema pattern that contains a dot (\&.) is interpreted as a database name followed by a schema name pattern\&. For example, +\edn mydb\&.*foo* +displays all schemas whose schema name includes +foo\&. The database name portion will not be treated as a pattern and must match the name of the currently connected database, else an error will be raised\&. +.PP +Advanced users can use regular\-expression notations such as character classes, for example +[0\-9] +to match any digit\&. All regular expression special characters work as specified in +Section\ \&9.7.3, except for +\&. +which is taken as a separator as mentioned above, +* +which is translated to the regular\-expression notation +\&.*, +? +which is translated to +\&., and +$ +which is matched literally\&. You can emulate these pattern characters at need by writing +? +for +\&., +(\fIR\fR+|) +for +\fIR\fR*, or +(\fIR\fR|) +for +\fIR\fR?\&. +$ +is not needed as a regular\-expression character since the pattern must match the whole name, unlike the usual interpretation of regular expressions (in other words, +$ +is automatically appended to your pattern)\&. Write +* +at the beginning and/or end if you don\*(Aqt wish the pattern to be anchored\&. Note that within double quotes, all regular expression special characters lose their special meanings and are matched literally\&. Also, the regular expression special characters are matched literally in operator name patterns (i\&.e\&., the argument of +\edo)\&. +.RE +.SS "Advanced Features" +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBVariables\fR +.RS 4 +.PP +psql +provides variable substitution features similar to common Unix command shells\&. Variables are simply name/value pairs, where the value can be any string of any length\&. The name must consist of letters (including non\-Latin letters), digits, and underscores\&. +.PP +To set a variable, use the +psql +meta\-command +\fB\eset\fR\&. For example, +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fB\eset foo bar\fR +.fi +.if n \{\ +.RE +.\} +.sp +sets the variable +foo +to the value +bar\&. To retrieve the content of the variable, precede the name with a colon, for example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fB\eecho :foo\fR +bar +.fi +.if n \{\ +.RE +.\} +.sp +This works in both regular SQL commands and meta\-commands; there is more detail in +SQL Interpolation, below\&. +.PP +If you call +\fB\eset\fR +without a second argument, the variable is set to an empty\-string value\&. To unset (i\&.e\&., delete) a variable, use the command +\fB\eunset\fR\&. To show the values of all variables, call +\fB\eset\fR +without any argument\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +The arguments of +\fB\eset\fR +are subject to the same substitution rules as with other commands\&. Thus you can construct interesting references such as +\eset :foo \*(Aqsomething\*(Aq +and get +\(lqsoft links\(rq +or +\(lqvariable variables\(rq +of +Perl +or +PHP +fame, respectively\&. Unfortunately (or fortunately?), there is no way to do anything useful with these constructs\&. On the other hand, +\eset bar :foo +is a perfectly valid way to copy a variable\&. +.sp .5v +.RE +.PP +A number of these variables are treated specially by +psql\&. They represent certain option settings that can be changed at run time by altering the value of the variable, or in some cases represent changeable state of +psql\&. By convention, all specially treated variables\*(Aq names consist of all upper\-case ASCII letters (and possibly digits and underscores)\&. To ensure maximum compatibility in the future, avoid using such variable names for your own purposes\&. +.PP +Variables that control +psql\*(Aqs behavior generally cannot be unset or set to invalid values\&. An +\eunset +command is allowed but is interpreted as setting the variable to its default value\&. A +\eset +command without a second argument is interpreted as setting the variable to +on, for control variables that accept that value, and is rejected for others\&. Also, control variables that accept the values +on +and +off +will also accept other common spellings of Boolean values, such as +true +and +false\&. +.PP +The specially treated variables are: +.PP +\fIAUTOCOMMIT\fR +.RS 4 +When +on +(the default), each SQL command is automatically committed upon successful completion\&. To postpone commit in this mode, you must enter a +\fBBEGIN\fR +or +\fBSTART TRANSACTION\fR +SQL command\&. When +off +or unset, SQL commands are not committed until you explicitly issue +\fBCOMMIT\fR +or +\fBEND\fR\&. The autocommit\-off mode works by issuing an implicit +\fBBEGIN\fR +for you, just before any command that is not already in a transaction block and is not itself a +\fBBEGIN\fR +or other transaction\-control command, nor a command that cannot be executed inside a transaction block (such as +\fBVACUUM\fR)\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +In autocommit\-off mode, you must explicitly abandon any failed transaction by entering +\fBABORT\fR +or +\fBROLLBACK\fR\&. Also keep in mind that if you exit the session without committing, your work will be lost\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +The autocommit\-on mode is +PostgreSQL\*(Aqs traditional behavior, but autocommit\-off is closer to the SQL spec\&. If you prefer autocommit\-off, you might wish to set it in the system\-wide +psqlrc +file or your +~/\&.psqlrc +file\&. +.sp .5v +.RE +.RE +.PP +\fICOMP_KEYWORD_CASE\fR +.RS 4 +Determines which letter case to use when completing an SQL key word\&. If set to +lower +or +upper, the completed word will be in lower or upper case, respectively\&. If set to +preserve\-lower +or +preserve\-upper +(the default), the completed word will be in the case of the word already entered, but words being completed without anything entered will be in lower or upper case, respectively\&. +.RE +.PP +\fIDBNAME\fR +.RS 4 +The name of the database you are currently connected to\&. This is set every time you connect to a database (including program start\-up), but can be changed or unset\&. +.RE +.PP +\fIECHO\fR +.RS 4 +If set to +all, all nonempty input lines are printed to standard output as they are read\&. (This does not apply to lines read interactively\&.) To select this behavior on program start\-up, use the switch +\fB\-a\fR\&. If set to +queries, +psql +prints each query to standard output as it is sent to the server\&. The switch to select this behavior is +\fB\-e\fR\&. If set to +errors, then only failed queries are displayed on standard error output\&. The switch for this behavior is +\fB\-b\fR\&. If set to +none +(the default), then no queries are displayed\&. +.RE +.PP +\fIECHO_HIDDEN\fR +.RS 4 +When this variable is set to +on +and a backslash command queries the database, the query is first shown\&. This feature helps you to study +PostgreSQL +internals and provide similar functionality in your own programs\&. (To select this behavior on program start\-up, use the switch +\fB\-E\fR\&.) If you set this variable to the value +noexec, the queries are just shown but are not actually sent to the server and executed\&. The default value is +off\&. +.RE +.PP +\fIENCODING\fR +.RS 4 +The current client character set encoding\&. This is set every time you connect to a database (including program start\-up), and when you change the encoding with +\eencoding, but it can be changed or unset\&. +.RE +.PP +\fIERROR\fR +.RS 4 +true +if the last SQL query failed, +false +if it succeeded\&. See also +\fISQLSTATE\fR\&. +.RE +.PP +\fIFETCH_COUNT\fR +.RS 4 +If this variable is set to an integer value greater than zero, the results of +\fBSELECT\fR +queries are fetched and displayed in groups of that many rows, rather than the default behavior of collecting the entire result set before display\&. Therefore only a limited amount of memory is used, regardless of the size of the result set\&. Settings of 100 to 1000 are commonly used when enabling this feature\&. Keep in mind that when using this feature, a query might fail after having already displayed some rows\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +Although you can use any output format with this feature, the default +aligned +format tends to look bad because each group of +\fIFETCH_COUNT\fR +rows will be formatted separately, leading to varying column widths across the row groups\&. The other output formats work better\&. +.sp .5v +.RE +.RE +.PP +\fIHIDE_TABLEAM\fR +.RS 4 +If this variable is set to +true, a table\*(Aqs access method details are not displayed\&. This is mainly useful for regression tests\&. +.RE +.PP +\fIHIDE_TOAST_COMPRESSION\fR +.RS 4 +If this variable is set to +true, column compression method details are not displayed\&. This is mainly useful for regression tests\&. +.RE +.PP +\fIHISTCONTROL\fR +.RS 4 +If this variable is set to +ignorespace, lines which begin with a space are not entered into the history list\&. If set to a value of +ignoredups, lines matching the previous history line are not entered\&. A value of +ignoreboth +combines the two options\&. If set to +none +(the default), all lines read in interactive mode are saved on the history list\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This feature was shamelessly plagiarized from +Bash\&. +.sp .5v +.RE +.RE +.PP +\fIHISTFILE\fR +.RS 4 +The file name that will be used to store the history list\&. If unset, the file name is taken from the +\fBPSQL_HISTORY\fR +environment variable\&. If that is not set either, the default is +~/\&.psql_history, or +%APPDATA%\epostgresql\epsql_history +on Windows\&. For example, putting: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\eset HISTFILE ~/\&.psql_history\-:DBNAME +.fi +.if n \{\ +.RE +.\} +.sp +in +~/\&.psqlrc +will cause +psql +to maintain a separate history for each database\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This feature was shamelessly plagiarized from +Bash\&. +.sp .5v +.RE +.RE +.PP +\fIHISTSIZE\fR +.RS 4 +The maximum number of commands to store in the command history (default 500)\&. If set to a negative value, no limit is applied\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This feature was shamelessly plagiarized from +Bash\&. +.sp .5v +.RE +.RE +.PP +\fIHOST\fR +.RS 4 +The database server host you are currently connected to\&. This is set every time you connect to a database (including program start\-up), but can be changed or unset\&. +.RE +.PP +\fIIGNOREEOF\fR +.RS 4 +If set to 1 or less, sending an +EOF +character (usually +Control+D) to an interactive session of +psql +will terminate the application\&. If set to a larger numeric value, that many consecutive +EOF +characters must be typed to make an interactive session terminate\&. If the variable is set to a non\-numeric value, it is interpreted as 10\&. The default is 0\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This feature was shamelessly plagiarized from +Bash\&. +.sp .5v +.RE +.RE +.PP +\fILASTOID\fR +.RS 4 +The value of the last affected OID, as returned from an +\fBINSERT\fR +or +\fB\elo_import\fR +command\&. This variable is only guaranteed to be valid until after the result of the next +SQL +command has been displayed\&. +PostgreSQL +servers since version 12 do not support OID system columns anymore, thus LASTOID will always be 0 following +\fBINSERT\fR +when targeting such servers\&. +.RE +.PP +\fILAST_ERROR_MESSAGE\fR +.br +\fILAST_ERROR_SQLSTATE\fR +.RS 4 +The primary error message and associated SQLSTATE code for the most recent failed query in the current +psql +session, or an empty string and +00000 +if no error has occurred in the current session\&. +.RE +.PP +\fION_ERROR_ROLLBACK\fR +.RS 4 +When set to +on, if a statement in a transaction block generates an error, the error is ignored and the transaction continues\&. When set to +interactive, such errors are only ignored in interactive sessions, and not when reading script files\&. When set to +off +(the default), a statement in a transaction block that generates an error aborts the entire transaction\&. The error rollback mode works by issuing an implicit +\fBSAVEPOINT\fR +for you, just before each command that is in a transaction block, and then rolling back to the savepoint if the command fails\&. +.RE +.PP +\fION_ERROR_STOP\fR +.RS 4 +By default, command processing continues after an error\&. When this variable is set to +on, processing will instead stop immediately\&. In interactive mode, +psql +will return to the command prompt; otherwise, +psql +will exit, returning error code 3 to distinguish this case from fatal error conditions, which are reported using error code 1\&. In either case, any currently running scripts (the top\-level script, if any, and any other scripts which it may have in invoked) will be terminated immediately\&. If the top\-level command string contained multiple SQL commands, processing will stop with the current command\&. +.RE +.PP +\fIPORT\fR +.RS 4 +The database server port to which you are currently connected\&. This is set every time you connect to a database (including program start\-up), but can be changed or unset\&. +.RE +.PP +\fIPROMPT1\fR +.br +\fIPROMPT2\fR +.br +\fIPROMPT3\fR +.RS 4 +These specify what the prompts +psql +issues should look like\&. See +Prompting +below\&. +.RE +.PP +\fIQUIET\fR +.RS 4 +Setting this variable to +on +is equivalent to the command line option +\fB\-q\fR\&. It is probably not too useful in interactive mode\&. +.RE +.PP +\fIROW_COUNT\fR +.RS 4 +The number of rows returned or affected by the last SQL query, or 0 if the query failed or did not report a row count\&. +.RE +.PP +\fISERVER_VERSION_NAME\fR +.br +\fISERVER_VERSION_NUM\fR +.RS 4 +The server\*(Aqs version number as a string, for example +9\&.6\&.2, +10\&.1 +or +11beta1, and in numeric form, for example +90602 +or +100001\&. These are set every time you connect to a database (including program start\-up), but can be changed or unset\&. +.RE +.PP +\fISHOW_ALL_RESULTS\fR +.RS 4 +When this variable is set to +off, only the last result of a combined query (\e;) is shown instead of all of them\&. The default is +on\&. The off behavior is for compatibility with older versions of psql\&. +.RE +.PP +\fISHOW_CONTEXT\fR +.RS 4 +This variable can be set to the values +never, +errors, or +always +to control whether +CONTEXT +fields are displayed in messages from the server\&. The default is +errors +(meaning that context will be shown in error messages, but not in notice or warning messages)\&. This setting has no effect when +\fIVERBOSITY\fR +is set to +terse +or +sqlstate\&. (See also +\fB\eerrverbose\fR, for use when you want a verbose version of the error you just got\&.) +.RE +.PP +\fISINGLELINE\fR +.RS 4 +Setting this variable to +on +is equivalent to the command line option +\fB\-S\fR\&. +.RE +.PP +\fISINGLESTEP\fR +.RS 4 +Setting this variable to +on +is equivalent to the command line option +\fB\-s\fR\&. +.RE +.PP +\fISQLSTATE\fR +.RS 4 +The error code (see +Appendix\ \&A) associated with the last SQL query\*(Aqs failure, or +00000 +if it succeeded\&. +.RE +.PP +\fIUSER\fR +.RS 4 +The database user you are currently connected as\&. This is set every time you connect to a database (including program start\-up), but can be changed or unset\&. +.RE +.PP +\fIVERBOSITY\fR +.RS 4 +This variable can be set to the values +default, +verbose, +terse, or +sqlstate +to control the verbosity of error reports\&. (See also +\fB\eerrverbose\fR, for use when you want a verbose version of the error you just got\&.) +.RE +.PP +\fIVERSION\fR +.br +\fIVERSION_NAME\fR +.br +\fIVERSION_NUM\fR +.RS 4 +These variables are set at program start\-up to reflect +psql\*(Aqs version, respectively as a verbose string, a short string (e\&.g\&., +9\&.6\&.2, +10\&.1, or +11beta1), and a number (e\&.g\&., +90602 +or +100001)\&. They can be changed or unset\&. +.RE +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBSQL Interpolation\fR +.RS 4 +.PP +A key feature of +psql +variables is that you can substitute (\(lqinterpolate\(rq) them into regular +SQL +statements, as well as the arguments of meta\-commands\&. Furthermore, +psql +provides facilities for ensuring that variable values used as SQL literals and identifiers are properly quoted\&. The syntax for interpolating a value without any quoting is to prepend the variable name with a colon (:)\&. For example, +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fB\eset foo \*(Aqmy_table\*(Aq\fR +testdb=> \fBSELECT * FROM :foo;\fR +.fi +.if n \{\ +.RE +.\} +.sp +would query the table +my_table\&. Note that this may be unsafe: the value of the variable is copied literally, so it can contain unbalanced quotes, or even backslash commands\&. You must make sure that it makes sense where you put it\&. +.PP +When a value is to be used as an SQL literal or identifier, it is safest to arrange for it to be quoted\&. To quote the value of a variable as an SQL literal, write a colon followed by the variable name in single quotes\&. To quote the value as an SQL identifier, write a colon followed by the variable name in double quotes\&. These constructs deal correctly with quotes and other special characters embedded within the variable value\&. The previous example would be more safely written this way: +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fB\eset foo \*(Aqmy_table\*(Aq\fR +testdb=> \fBSELECT * FROM :"foo";\fR +.fi +.if n \{\ +.RE +.\} +.PP +Variable interpolation will not be performed within quoted +SQL +literals and identifiers\&. Therefore, a construction such as +\*(Aq:foo\*(Aq +doesn\*(Aqt work to produce a quoted literal from a variable\*(Aqs value (and it would be unsafe if it did work, since it wouldn\*(Aqt correctly handle quotes embedded in the value)\&. +.PP +One example use of this mechanism is to copy the contents of a file into a table column\&. First load the file into a variable and then interpolate the variable\*(Aqs value as a quoted string: +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fB\eset content `cat my_file\&.txt`\fR +testdb=> \fBINSERT INTO my_table VALUES (:\*(Aqcontent\*(Aq);\fR +.fi +.if n \{\ +.RE +.\} +.sp +(Note that this still won\*(Aqt work if +my_file\&.txt +contains NUL bytes\&. +psql +does not support embedded NUL bytes in variable values\&.) +.PP +Since colons can legally appear in SQL commands, an apparent attempt at interpolation (that is, +:name, +:\*(Aqname\*(Aq, or +:"name") is not replaced unless the named variable is currently set\&. In any case, you can escape a colon with a backslash to protect it from substitution\&. +.PP +The +:{?\fIname\fR} +special syntax returns TRUE or FALSE depending on whether the variable exists or not, and is thus always substituted, unless the colon is backslash\-escaped\&. +.PP +The colon syntax for variables is standard +SQL +for embedded query languages, such as +ECPG\&. The colon syntaxes for array slices and type casts are +PostgreSQL +extensions, which can sometimes conflict with the standard usage\&. The colon\-quote syntax for escaping a variable\*(Aqs value as an SQL literal or identifier is a +psql +extension\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBPrompting\fR +.RS 4 +.PP +The prompts +psql +issues can be customized to your preference\&. The three variables +\fIPROMPT1\fR, +\fIPROMPT2\fR, and +\fIPROMPT3\fR +contain strings and special escape sequences that describe the appearance of the prompt\&. Prompt 1 is the normal prompt that is issued when +psql +requests a new command\&. Prompt 2 is issued when more input is expected during command entry, for example because the command was not terminated with a semicolon or a quote was not closed\&. Prompt 3 is issued when you are running an +SQL +\fBCOPY FROM STDIN\fR +command and you need to type in a row value on the terminal\&. +.PP +The value of the selected prompt variable is printed literally, except where a percent sign (%) is encountered\&. Depending on the next character, certain other text is substituted instead\&. Defined substitutions are: +.PP +%M +.RS 4 +The full host name (with domain name) of the database server, or +[local] +if the connection is over a Unix domain socket, or +[local:\fI/dir/name\fR], if the Unix domain socket is not at the compiled in default location\&. +.RE +.PP +%m +.RS 4 +The host name of the database server, truncated at the first dot, or +[local] +if the connection is over a Unix domain socket\&. +.RE +.PP +%> +.RS 4 +The port number at which the database server is listening\&. +.RE +.PP +%n +.RS 4 +The database session user name\&. (The expansion of this value might change during a database session as the result of the command +\fBSET SESSION AUTHORIZATION\fR\&.) +.RE +.PP +%/ +.RS 4 +The name of the current database\&. +.RE +.PP +%~ +.RS 4 +Like +%/, but the output is +~ +(tilde) if the database is your default database\&. +.RE +.PP +%# +.RS 4 +If the session user is a database superuser, then a +#, otherwise a +>\&. (The expansion of this value might change during a database session as the result of the command +\fBSET SESSION AUTHORIZATION\fR\&.) +.RE +.PP +%p +.RS 4 +The process ID of the backend currently connected to\&. +.RE +.PP +%R +.RS 4 +In prompt 1 normally +=, but +@ +if the session is in an inactive branch of a conditional block, or +^ +if in single\-line mode, or +! +if the session is disconnected from the database (which can happen if +\fB\econnect\fR +fails)\&. In prompt 2 +%R +is replaced by a character that depends on why +psql +expects more input: +\- +if the command simply wasn\*(Aqt terminated yet, but +* +if there is an unfinished +/* \&.\&.\&. */ +comment, a single quote if there is an unfinished quoted string, a double quote if there is an unfinished quoted identifier, a dollar sign if there is an unfinished dollar\-quoted string, or +( +if there is an unmatched left parenthesis\&. In prompt 3 +%R +doesn\*(Aqt produce anything\&. +.RE +.PP +%x +.RS 4 +Transaction status: an empty string when not in a transaction block, or +* +when in a transaction block, or +! +when in a failed transaction block, or +? +when the transaction state is indeterminate (for example, because there is no connection)\&. +.RE +.PP +%l +.RS 4 +The line number inside the current statement, starting from +1\&. +.RE +.PP +%\fIdigits\fR +.RS 4 +The character with the indicated octal code is substituted\&. +.RE +.PP +%:\fIname\fR: +.RS 4 +The value of the +psql +variable +\fIname\fR\&. See +Variables, above, for details\&. +.RE +.PP +%`\fIcommand\fR` +.RS 4 +The output of +\fIcommand\fR, similar to ordinary +\(lqback\-tick\(rq +substitution\&. +.RE +.PP +%[ \&.\&.\&. %] +.RS 4 +Prompts can contain terminal control characters which, for example, change the color, background, or style of the prompt text, or change the title of the terminal window\&. In order for the line editing features of +Readline +to work properly, these non\-printing control characters must be designated as invisible by surrounding them with +%[ +and +%]\&. Multiple pairs of these can occur within the prompt\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \eset PROMPT1 \*(Aq%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# \*(Aq +.fi +.if n \{\ +.RE +.\} +.sp +results in a boldfaced (1;) yellow\-on\-black (33;40) prompt on VT100\-compatible, color\-capable terminals\&. +.RE +.PP +%w +.RS 4 +Whitespace of the same width as the most recent output of +\fIPROMPT1\fR\&. This can be used as a +\fIPROMPT2\fR +setting, so that multi\-line statements are aligned with the first line, but there is no visible secondary prompt\&. +.RE +To insert a percent sign into your prompt, write +%%\&. The default prompts are +\*(Aq%/%R%x%# \*(Aq +for prompts 1 and 2, and +\*(Aq>> \*(Aq +for prompt 3\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +This feature was shamelessly plagiarized from +tcsh\&. +.sp .5v +.RE +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCommand-Line Editing\fR +.RS 4 +.PP +psql +uses the +Readline +or +libedit +library, if available, for convenient line editing and retrieval\&. The command history is automatically saved when +psql +exits and is reloaded when +psql +starts up\&. Type up\-arrow or control\-P to retrieve previous lines\&. +.PP +You can also use tab completion to fill in partially\-typed keywords and SQL object names in many (by no means all) contexts\&. For example, at the start of a command, typing +ins +and pressing TAB will fill in +insert into\&. Then, typing a few characters of a table or schema name and pressing +TAB +will fill in the unfinished name, or offer a menu of possible completions when there\*(Aqs more than one\&. (Depending on the library in use, you may need to press +TAB +more than once to get a menu\&.) +.PP +Tab completion for SQL object names requires sending queries to the server to find possible matches\&. In some contexts this can interfere with other operations\&. For example, after +\fBBEGIN\fR +it will be too late to issue +\fBSET TRANSACTION ISOLATION LEVEL\fR +if a tab\-completion query is issued in between\&. If you do not want tab completion at all, you can turn it off permanently by putting this in a file named +\&.inputrc +in your home directory: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$if psql +set disable\-completion on +$endif +.fi +.if n \{\ +.RE +.\} +.sp +(This is not a +psql +but a +Readline +feature\&. Read its documentation for further details\&.) +.PP +The +\fB\-n\fR +(\fB\-\-no\-readline\fR) command line option can also be useful to disable use of +Readline +for a single run of +psql\&. This prevents tab completion, use or recording of command line history, and editing of multi\-line commands\&. It is particularly useful when you need to copy\-and\-paste text that contains +TAB +characters\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBCOLUMNS\fR +.RS 4 +If +\epset columns +is zero, controls the width for the +wrapped +format and width for determining if wide output requires the pager or should be switched to the vertical format in expanded auto mode\&. +.RE +.PP +\fBPGDATABASE\fR +.br +\fBPGHOST\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters (see +Section\ \&34.15)\&. +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +\fBPSQL_EDITOR\fR +.br +\fBEDITOR\fR +.br +\fBVISUAL\fR +.RS 4 +Editor used by the +\fB\ee\fR, +\fB\eef\fR, and +\fB\eev\fR +commands\&. These variables are examined in the order listed; the first that is set is used\&. If none of them is set, the default is to use +vi +on Unix systems or +notepad\&.exe +on Windows systems\&. +.RE +.PP +\fBPSQL_EDITOR_LINENUMBER_ARG\fR +.RS 4 +When +\fB\ee\fR, +\fB\eef\fR, or +\fB\eev\fR +is used with a line number argument, this variable specifies the command\-line argument used to pass the starting line number to the user\*(Aqs editor\&. For editors such as +Emacs +or +vi, this is a plus sign\&. Include a trailing space in the value of the variable if there needs to be space between the option name and the line number\&. Examples: +.sp +.if n \{\ +.RS 4 +.\} +.nf +PSQL_EDITOR_LINENUMBER_ARG=\*(Aq+\*(Aq +PSQL_EDITOR_LINENUMBER_ARG=\*(Aq\-\-line \*(Aq +.fi +.if n \{\ +.RE +.\} +.sp +The default is ++ +on Unix systems (corresponding to the default editor +vi, and useful for many other common editors); but there is no default on Windows systems\&. +.RE +.PP +\fBPSQL_HISTORY\fR +.RS 4 +Alternative location for the command history file\&. Tilde (~) expansion is performed\&. +.RE +.PP +\fBPSQL_PAGER\fR +.br +\fBPAGER\fR +.RS 4 +If a query\*(Aqs results do not fit on the screen, they are piped through this command\&. Typical values are +more +or +less\&. Use of the pager can be disabled by setting +\fBPSQL_PAGER\fR +or +\fBPAGER\fR +to an empty string, or by adjusting the pager\-related options of the +\fB\epset\fR +command\&. These variables are examined in the order listed; the first that is set is used\&. If neither of them is set, the default is to use +more +on most platforms, but +less +on Cygwin\&. +.RE +.PP +\fBPSQL_WATCH_PAGER\fR +.RS 4 +When a query is executed repeatedly with the +\fB\ewatch\fR +command, a pager is not used by default\&. This behavior can be changed by setting +\fBPSQL_WATCH_PAGER\fR +to a pager command, on Unix systems\&. The +pspg +pager (not part of +PostgreSQL +but available in many open source software distributions) can display the output of +\fB\ewatch\fR +if started with the option +\-\-stream\&. +.RE +.PP +\fBPSQLRC\fR +.RS 4 +Alternative location of the user\*(Aqs +\&.psqlrc +file\&. Tilde (~) expansion is performed\&. +.RE +.PP +\fBSHELL\fR +.RS 4 +Command executed by the +\fB\e!\fR +command\&. +.RE +.PP +\fBTMPDIR\fR +.RS 4 +Directory for storing temporary files\&. The default is +/tmp\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "FILES" +.PP +psqlrc and ~/\&.psqlrc +.RS 4 +Unless it is passed an +\fB\-X\fR +option, +psql +attempts to read and execute commands from the system\-wide startup file (psqlrc) and then the user\*(Aqs personal startup file (~/\&.psqlrc), after connecting to the database but before accepting normal commands\&. These files can be used to set up the client and/or the server to taste, typically with +\fB\eset\fR +and +\fBSET\fR +commands\&. +.sp +The system\-wide startup file is named +psqlrc\&. By default it is sought in the installation\*(Aqs +\(lqsystem configuration\(rq +directory, which is most reliably identified by running +pg_config \-\-sysconfdir\&. Typically this directory will be +\&.\&./etc/ +relative to the directory containing the +PostgreSQL +executables\&. The directory to look in can be set explicitly via the +\fBPGSYSCONFDIR\fR +environment variable\&. +.sp +The user\*(Aqs personal startup file is named +\&.psqlrc +and is sought in the invoking user\*(Aqs home directory\&. On Windows the personal startup file is instead named +%APPDATA%\epostgresql\epsqlrc\&.conf\&. In either case, this default file path can be overridden by setting the +\fBPSQLRC\fR +environment variable\&. +.sp +Both the system\-wide startup file and the user\*(Aqs personal startup file can be made +psql\-version\-specific by appending a dash and the +PostgreSQL +major or minor release identifier to the file name, for example +~/\&.psqlrc\-15 +or +~/\&.psqlrc\-15\&.4\&. The most specific version\-matching file will be read in preference to a non\-version\-specific file\&. These version suffixes are added after determining the file path as explained above\&. +.RE +.PP +\&.psql_history +.RS 4 +The command\-line history is stored in the file +~/\&.psql_history, or +%APPDATA%\epostgresql\epsql_history +on Windows\&. +.sp +The location of the history file can be set explicitly via the +\fIHISTFILE\fR +psql +variable or the +\fBPSQL_HISTORY\fR +environment variable\&. +.RE +.SH "NOTES" +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +psql +works best with servers of the same or an older major version\&. Backslash commands are particularly likely to fail if the server is of a newer version than +psql +itself\&. However, backslash commands of the +\ed +family should work with servers of versions back to 9\&.2, though not necessarily with servers newer than +psql +itself\&. The general functionality of running SQL commands and displaying query results should also work with servers of a newer major version, but this cannot be guaranteed in all cases\&. +.sp +If you want to use +psql +to connect to several servers of different major versions, it is recommended that you use the newest version of +psql\&. Alternatively, you can keep around a copy of +psql +from each major version and be sure to use the version that matches the respective server\&. But in practice, this additional complication should not be necessary\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Before +PostgreSQL +9\&.6, the +\fB\-c\fR +option implied +\fB\-X\fR +(\fB\-\-no\-psqlrc\fR); this is no longer the case\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Before +PostgreSQL +8\&.4, +psql +allowed the first argument of a single\-letter backslash command to start directly after the command, without intervening whitespace\&. Now, some whitespace is required\&. +.RE +.SH "NOTES FOR WINDOWS USERS" +.PP +psql +is built as a +\(lqconsole application\(rq\&. Since the Windows console windows use a different encoding than the rest of the system, you must take special care when using 8\-bit characters within +psql\&. If +psql +detects a problematic console code page, it will warn you at startup\&. To change the console code page, two things are necessary: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Set the code page by entering +\fBcmd\&.exe /c chcp 1252\fR\&. (1252 is a code page that is appropriate for German; replace it with your value\&.) If you are using Cygwin, you can put this command in +/etc/profile\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Set the console font to +Lucida Console, because the raster font does not work with the ANSI code page\&. +.RE +.SH "EXAMPLES" +.PP +The first example shows how to spread a command over several lines of input\&. Notice the changing prompt: +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fBCREATE TABLE my_table (\fR +testdb(> \fB first integer not null default 0,\fR +testdb(> \fB second text)\fR +testdb\-> \fB;\fR +CREATE TABLE +.fi +.if n \{\ +.RE +.\} +.sp +Now look at the table definition again: +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fB\ed my_table\fR + Table "public\&.my_table" + Column | Type | Collation | Nullable | Default +\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\- + first | integer | | not null | 0 + second | text | | | +.fi +.if n \{\ +.RE +.\} +.sp +Now we change the prompt to something more interesting: +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fB\eset PROMPT1 \*(Aq%n@%m %~%R%# \*(Aq\fR +peter@localhost testdb=> +.fi +.if n \{\ +.RE +.\} +.sp +Let\*(Aqs assume you have filled the table with data and want to take a look at it: +.sp +.if n \{\ +.RS 4 +.\} +.nf +peter@localhost testdb=> SELECT * FROM my_table; + first | second +\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\- + 1 | one + 2 | two + 3 | three + 4 | four +(4 rows) +.fi +.if n \{\ +.RE +.\} +.sp +You can display tables in different ways by using the +\fB\epset\fR +command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +peter@localhost testdb=> \fB\epset border 2\fR +Border style is 2\&. +peter@localhost testdb=> \fBSELECT * FROM my_table;\fR ++\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+ +| first | second | ++\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+ +| 1 | one | +| 2 | two | +| 3 | three | +| 4 | four | ++\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+ +(4 rows) + +peter@localhost testdb=> \fB\epset border 0\fR +Border style is 0\&. +peter@localhost testdb=> \fBSELECT * FROM my_table;\fR +first second +\-\-\-\-\- \-\-\-\-\-\- + 1 one + 2 two + 3 three + 4 four +(4 rows) + +peter@localhost testdb=> \fB\epset border 1\fR +Border style is 1\&. +peter@localhost testdb=> \fB\epset format csv\fR +Output format is csv\&. +peter@localhost testdb=> \fB\epset tuples_only\fR +Tuples only is on\&. +peter@localhost testdb=> \fBSELECT second, first FROM my_table;\fR +one,1 +two,2 +three,3 +four,4 +peter@localhost testdb=> \fB\epset format unaligned\fR +Output format is unaligned\&. +peter@localhost testdb=> \fB\epset fieldsep \*(Aq\et\*(Aq\fR +Field separator is " "\&. +peter@localhost testdb=> \fBSELECT second, first FROM my_table;\fR +one 1 +two 2 +three 3 +four 4 +.fi +.if n \{\ +.RE +.\} +.sp +Alternatively, use the short commands: +.sp +.if n \{\ +.RS 4 +.\} +.nf +peter@localhost testdb=> \fB\ea \et \ex\fR +Output format is aligned\&. +Tuples only is off\&. +Expanded display is on\&. +peter@localhost testdb=> \fBSELECT * FROM my_table;\fR +\-[ RECORD 1 ]\- +first | 1 +second | one +\-[ RECORD 2 ]\- +first | 2 +second | two +\-[ RECORD 3 ]\- +first | 3 +second | three +\-[ RECORD 4 ]\- +first | 4 +second | four +.fi +.if n \{\ +.RE +.\} +.PP +Also, these output format options can be set for just one query by using +\eg: +.sp +.if n \{\ +.RS 4 +.\} +.nf +peter@localhost testdb=> \fBSELECT * FROM my_table\fR +peter@localhost testdb\-> \fB\eg (format=aligned tuples_only=off expanded=on)\fR +\-[ RECORD 1 ]\- +first | 1 +second | one +\-[ RECORD 2 ]\- +first | 2 +second | two +\-[ RECORD 3 ]\- +first | 3 +second | three +\-[ RECORD 4 ]\- +first | 4 +second | four +.fi +.if n \{\ +.RE +.\} +.PP +Here is an example of using the +\fB\edf\fR +command to find only functions with names matching +int*pl +and whose second argument is of type +bigint: +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fB\edf int*pl * bigint\fR + List of functions + Schema | Name | Result data type | Argument data types | Type +\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\- + pg_catalog | int28pl | bigint | smallint, bigint | func + pg_catalog | int48pl | bigint | integer, bigint | func + pg_catalog | int8pl | bigint | bigint, bigint | func +(3 rows) +.fi +.if n \{\ +.RE +.\} +.PP +When suitable, query results can be shown in a crosstab representation with the +\fB\ecrosstabview\fR +command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fBSELECT first, second, first > 2 AS gt2 FROM my_table;\fR + first | second | gt2 +\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\- + 1 | one | f + 2 | two | f + 3 | three | t + 4 | four | t +(4 rows) + +testdb=> \fB\ecrosstabview first second\fR + first | one | two | three | four +\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\- + 1 | f | | | + 2 | | f | | + 3 | | | t | + 4 | | | | t +(4 rows) +.fi +.if n \{\ +.RE +.\} +.sp +This second example shows a multiplication table with rows sorted in reverse numerical order and columns with an independent, ascending numerical order\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +testdb=> \fBSELECT t1\&.first as "A", t2\&.first+100 AS "B", t1\&.first*(t2\&.first+100) as "AxB",\fR +testdb(> \fBrow_number() over(order by t2\&.first) AS ord\fR +testdb(> \fBFROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC\fR +testdb(> \fB\ecrosstabview "A" "B" "AxB" ord\fR + A | 101 | 102 | 103 | 104 +\-\-\-+\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\- + 4 | 404 | 408 | 412 | 416 + 3 | 303 | 306 | 309 | 312 + 2 | 202 | 204 | 206 | 208 + 1 | 101 | 102 | 103 | 104 +(4 rows) +.fi +.if n \{\ +.RE +.\} + diff --git a/doc/src/sgml/man1/reindexdb.1 b/doc/src/sgml/man1/reindexdb.1 new file mode 100644 index 0000000..8d677a2 --- /dev/null +++ b/doc/src/sgml/man1/reindexdb.1 @@ -0,0 +1,330 @@ +'\" t +.\" Title: reindexdb +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "REINDEXDB" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +reindexdb \- reindex a PostgreSQL database +.SH "SYNOPSIS" +.HP \w'\fBreindexdb\fR\ 'u +\fBreindexdb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\ \fB\-S\fR\ |\ \fB\-\-schema\fR\ \fIschema\fR\ ]... [\ \fB\-t\fR\ |\ \fB\-\-table\fR\ \fItable\fR\ ]... [\ \fB\-i\fR\ |\ \fB\-\-index\fR\ \fIindex\fR\ ]... [\fIdbname\fR] +.HP \w'\fBreindexdb\fR\ 'u +\fBreindexdb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] \fB\-a\fR | \fB\-\-all\fR +.HP \w'\fBreindexdb\fR\ 'u +\fBreindexdb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] \fB\-s\fR | \fB\-\-system\fR [\fIdbname\fR] +.SH "DESCRIPTION" +.PP +reindexdb +is a utility for rebuilding indexes in a +PostgreSQL +database\&. +.PP +reindexdb +is a wrapper around the SQL command +\fBREINDEX\fR\&. There is no effective difference between reindexing databases via this utility and via other methods for accessing the server\&. +.SH "OPTIONS" +.PP +reindexdb +accepts the following command\-line arguments: +.PP +\fB\-a\fR +.br +\fB\-\-all\fR +.RS 4 +Reindex all databases\&. +.RE +.PP +\fB\-\-concurrently\fR +.RS 4 +Use the +CONCURRENTLY +option\&. See +\fBREINDEX\fR(7), where all the caveats of this option are explained in detail\&. +.RE +.PP +\fB[\-d]\fR\fB \fR\fB\fIdbname\fR\fR +.br +\fB[\-\-dbname=]\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to be reindexed, when +\fB\-a\fR/\fB\-\-all\fR +is not used\&. If this is not specified, the database name is read from the environment variable +\fBPGDATABASE\fR\&. If that is not set, the user name specified for the connection is used\&. The +\fIdbname\fR +can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. +.RE +.PP +\fB\-e\fR +.br +\fB\-\-echo\fR +.RS 4 +Echo the commands that +reindexdb +generates and sends to the server\&. +.RE +.PP +\fB\-i \fR\fB\fIindex\fR\fR +.br +\fB\-\-index=\fR\fB\fIindex\fR\fR +.RS 4 +Recreate +\fIindex\fR +only\&. Multiple indexes can be recreated by writing multiple +\fB\-i\fR +switches\&. +.RE +.PP +\fB\-j \fR\fB\fInjobs\fR\fR +.br +\fB\-\-jobs=\fR\fB\fInjobs\fR\fR +.RS 4 +Execute the reindex commands in parallel by running +\fInjobs\fR +commands simultaneously\&. This option may reduce the processing time but it also increases the load on the database server\&. +.sp +reindexdb +will open +\fInjobs\fR +connections to the database, so make sure your +max_connections +setting is high enough to accommodate all connections\&. +.sp +Note that this option is incompatible with the +\fB\-\-index\fR +and +\fB\-\-system\fR +options\&. +.RE +.PP +\fB\-q\fR +.br +\fB\-\-quiet\fR +.RS 4 +Do not display progress messages\&. +.RE +.PP +\fB\-s\fR +.br +\fB\-\-system\fR +.RS 4 +Reindex database\*(Aqs system catalogs only\&. +.RE +.PP +\fB\-S \fR\fB\fIschema\fR\fR +.br +\fB\-\-schema=\fR\fB\fIschema\fR\fR +.RS 4 +Reindex +\fIschema\fR +only\&. Multiple schemas can be reindexed by writing multiple +\fB\-S\fR +switches\&. +.RE +.PP +\fB\-t \fR\fB\fItable\fR\fR +.br +\fB\-\-table=\fR\fB\fItable\fR\fR +.RS 4 +Reindex +\fItable\fR +only\&. Multiple tables can be reindexed by writing multiple +\fB\-t\fR +switches\&. +.RE +.PP +\fB\-\-tablespace=\fR\fB\fItablespace\fR\fR +.RS 4 +Specifies the tablespace where indexes are rebuilt\&. (This name is processed as a double\-quoted identifier\&.) +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Print detailed information during processing\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +reindexdb +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +reindexdb +command line arguments, and exit\&. +.RE +.PP +reindexdb +also accepts the following command\-line arguments for connection parameters: +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +reindexdb +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +reindexdb +will automatically prompt for a password if the server demands password authentication\&. However, +reindexdb +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +\fB\-\-maintenance\-db=\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to connect to to discover which databases should be reindexed, when +\fB\-a\fR/\fB\-\-all\fR +is used\&. If not specified, the +postgres +database will be used, or if that does not exist, +template1 +will be used\&. This can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. Also, connection string parameters other than the database name itself will be re\-used when connecting to other databases\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGDATABASE\fR +.br +\fBPGHOST\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "DIAGNOSTICS" +.PP +In case of difficulty, see +\fBREINDEX\fR(7) +and +\fBpsql\fR(1) +for discussions of potential problems and error messages\&. The database server must be running at the targeted host\&. Also, any default connection settings and environment variables used by the +libpq +front\-end library will apply\&. +.SH "NOTES" +.PP +reindexdb +might need to connect several times to the +PostgreSQL +server, asking for a password each time\&. It is convenient to have a +~/\&.pgpass +file in such cases\&. See +Section\ \&34.16 +for more information\&. +.SH "EXAMPLES" +.PP +To reindex the database +test: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBreindexdb test\fR +.fi +.if n \{\ +.RE +.\} +.PP +To reindex the table +foo +and the index +bar +in a database named +abcd: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBreindexdb \-\-table=foo \-\-index=bar abcd\fR +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBREINDEX\fR(7) diff --git a/doc/src/sgml/man1/vacuumdb.1 b/doc/src/sgml/man1/vacuumdb.1 new file mode 100644 index 0000000..bcbe5e9 --- /dev/null +++ b/doc/src/sgml/man1/vacuumdb.1 @@ -0,0 +1,584 @@ +'\" t +.\" Title: vacuumdb +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "VACUUMDB" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +vacuumdb \- garbage\-collect and analyze a PostgreSQL database +.SH "SYNOPSIS" +.HP \w'\fBvacuumdb\fR\ 'u +\fBvacuumdb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\ \fB\-t\fR\ |\ \fB\-\-table\fR\ \fItable\fR\ [(\ \fIcolumn\fR\ [,\&.\&.\&.]\ )]\ ]... [\fIdbname\fR] +.HP \w'\fBvacuumdb\fR\ 'u +\fBvacuumdb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] \fB\-a\fR | \fB\-\-all\fR +.SH "DESCRIPTION" +.PP +vacuumdb +is a utility for cleaning a +PostgreSQL +database\&. +vacuumdb +will also generate internal statistics used by the +PostgreSQL +query optimizer\&. +.PP +vacuumdb +is a wrapper around the SQL command +\fBVACUUM\fR\&. There is no effective difference between vacuuming and analyzing databases via this utility and via other methods for accessing the server\&. +.SH "OPTIONS" +.PP +vacuumdb +accepts the following command\-line arguments: +.PP +\fB\-a\fR +.br +\fB\-\-all\fR +.RS 4 +Vacuum all databases\&. +.RE +.PP +\fB[\-d]\fR\fB \fR\fB\fIdbname\fR\fR +.br +\fB[\-\-dbname=]\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to be cleaned or analyzed, when +\fB\-a\fR/\fB\-\-all\fR +is not used\&. If this is not specified, the database name is read from the environment variable +\fBPGDATABASE\fR\&. If that is not set, the user name specified for the connection is used\&. The +\fIdbname\fR +can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. +.RE +.PP +\fB\-\-disable\-page\-skipping\fR +.RS 4 +Disable skipping pages based on the contents of the visibility map\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This option is only available for servers running +PostgreSQL +9\&.6 and later\&. +.sp .5v +.RE +.RE +.PP +\fB\-e\fR +.br +\fB\-\-echo\fR +.RS 4 +Echo the commands that +vacuumdb +generates and sends to the server\&. +.RE +.PP +\fB\-f\fR +.br +\fB\-\-full\fR +.RS 4 +Perform +\(lqfull\(rq +vacuuming\&. +.RE +.PP +\fB\-F\fR +.br +\fB\-\-freeze\fR +.RS 4 +Aggressively +\(lqfreeze\(rq +tuples\&. +.RE +.PP +\fB\-\-force\-index\-cleanup\fR +.RS 4 +Always remove index entries pointing to dead tuples\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This option is only available for servers running +PostgreSQL +12 and later\&. +.sp .5v +.RE +.RE +.PP +\fB\-j \fR\fB\fInjobs\fR\fR +.br +\fB\-\-jobs=\fR\fB\fInjobs\fR\fR +.RS 4 +Execute the vacuum or analyze commands in parallel by running +\fInjobs\fR +commands simultaneously\&. This option may reduce the processing time but it also increases the load on the database server\&. +.sp +vacuumdb +will open +\fInjobs\fR +connections to the database, so make sure your +max_connections +setting is high enough to accommodate all connections\&. +.sp +Note that using this mode together with the +\fB\-f\fR +(FULL) option might cause deadlock failures if certain system catalogs are processed in parallel\&. +.RE +.PP +\fB\-\-min\-mxid\-age \fR\fB\fImxid_age\fR\fR +.RS 4 +Only execute the vacuum or analyze commands on tables with a multixact ID age of at least +\fImxid_age\fR\&. This setting is useful for prioritizing tables to process to prevent multixact ID wraparound (see +Section\ \&25.1.5.1)\&. +.sp +For the purposes of this option, the multixact ID age of a relation is the greatest of the ages of the main relation and its associated +TOAST +table, if one exists\&. Since the commands issued by +vacuumdb +will also process the +TOAST +table for the relation if necessary, it does not need to be considered separately\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This option is only available for servers running +PostgreSQL +9\&.6 and later\&. +.sp .5v +.RE +.RE +.PP +\fB\-\-min\-xid\-age \fR\fB\fIxid_age\fR\fR +.RS 4 +Only execute the vacuum or analyze commands on tables with a transaction ID age of at least +\fIxid_age\fR\&. This setting is useful for prioritizing tables to process to prevent transaction ID wraparound (see +Section\ \&25.1.5)\&. +.sp +For the purposes of this option, the transaction ID age of a relation is the greatest of the ages of the main relation and its associated +TOAST +table, if one exists\&. Since the commands issued by +vacuumdb +will also process the +TOAST +table for the relation if necessary, it does not need to be considered separately\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This option is only available for servers running +PostgreSQL +9\&.6 and later\&. +.sp .5v +.RE +.RE +.PP +\fB\-\-no\-index\-cleanup\fR +.RS 4 +Do not remove index entries pointing to dead tuples\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This option is only available for servers running +PostgreSQL +12 and later\&. +.sp .5v +.RE +.RE +.PP +\fB\-\-no\-process\-toast\fR +.RS 4 +Skip the TOAST table associated with the table to vacuum, if any\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This option is only available for servers running +PostgreSQL +14 and later\&. +.sp .5v +.RE +.RE +.PP +\fB\-\-no\-truncate\fR +.RS 4 +Do not truncate empty pages at the end of the table\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This option is only available for servers running +PostgreSQL +12 and later\&. +.sp .5v +.RE +.RE +.PP +\fB\-P \fR\fB\fIparallel_workers\fR\fR +.br +\fB\-\-parallel=\fR\fB\fIparallel_workers\fR\fR +.RS 4 +Specify the number of parallel workers for +parallel vacuum\&. This allows the vacuum to leverage multiple CPUs to process indexes\&. See +\fBVACUUM\fR(7)\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This option is only available for servers running +PostgreSQL +13 and later\&. +.sp .5v +.RE +.RE +.PP +\fB\-q\fR +.br +\fB\-\-quiet\fR +.RS 4 +Do not display progress messages\&. +.RE +.PP +\fB\-\-skip\-locked\fR +.RS 4 +Skip relations that cannot be immediately locked for processing\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +This option is only available for servers running +PostgreSQL +12 and later\&. +.sp .5v +.RE +.RE +.PP +\fB\-t \fR\fB\fItable\fR\fR\fB [ (\fR\fB\fIcolumn\fR\fR\fB [,\&.\&.\&.]) ]\fR +.br +\fB\-\-table=\fR\fB\fItable\fR\fR\fB [ (\fR\fB\fIcolumn\fR\fR\fB [,\&.\&.\&.]) ]\fR +.RS 4 +Clean or analyze +\fItable\fR +only\&. Column names can be specified only in conjunction with the +\fB\-\-analyze\fR +or +\fB\-\-analyze\-only\fR +options\&. Multiple tables can be vacuumed by writing multiple +\fB\-t\fR +switches\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +If you specify columns, you probably have to escape the parentheses from the shell\&. (See examples below\&.) +.sp .5v +.RE +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Print detailed information during processing\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +vacuumdb +version and exit\&. +.RE +.PP +\fB\-z\fR +.br +\fB\-\-analyze\fR +.RS 4 +Also calculate statistics for use by the optimizer\&. +.RE +.PP +\fB\-Z\fR +.br +\fB\-\-analyze\-only\fR +.RS 4 +Only calculate statistics for use by the optimizer (no vacuum)\&. +.RE +.PP +\fB\-\-analyze\-in\-stages\fR +.RS 4 +Only calculate statistics for use by the optimizer (no vacuum), like +\fB\-\-analyze\-only\fR\&. Run three stages of analyze; the first stage uses the lowest possible statistics target (see +default_statistics_target) to produce usable statistics faster, and subsequent stages build the full statistics\&. +.sp +This option is only useful to analyze a database that currently has no statistics or has wholly incorrect ones, such as if it is newly populated from a restored dump or by +\fBpg_upgrade\fR\&. Be aware that running with this option in a database with existing statistics may cause the query optimizer choices to become transiently worse due to the low statistics targets of the early stages\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +vacuumdb +command line arguments, and exit\&. +.RE +.PP +vacuumdb +also accepts the following command\-line arguments for connection parameters: +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +vacuumdb +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +vacuumdb +will automatically prompt for a password if the server demands password authentication\&. However, +vacuumdb +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.PP +\fB\-\-maintenance\-db=\fR\fB\fIdbname\fR\fR +.RS 4 +Specifies the name of the database to connect to to discover which databases should be vacuumed, when +\fB\-a\fR/\fB\-\-all\fR +is used\&. If not specified, the +postgres +database will be used, or if that does not exist, +template1 +will be used\&. This can be a +connection string\&. If so, connection string parameters will override any conflicting command line options\&. Also, connection string parameters other than the database name itself will be re\-used when connecting to other databases\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGDATABASE\fR +.br +\fBPGHOST\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters +.RE +.PP +\fBPG_COLOR\fR +.RS 4 +Specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.SH "DIAGNOSTICS" +.PP +In case of difficulty, see +\fBVACUUM\fR(7) +and +\fBpsql\fR(1) +for discussions of potential problems and error messages\&. The database server must be running at the targeted host\&. Also, any default connection settings and environment variables used by the +libpq +front\-end library will apply\&. +.SH "NOTES" +.PP +vacuumdb +might need to connect several times to the +PostgreSQL +server, asking for a password each time\&. It is convenient to have a +~/\&.pgpass +file in such cases\&. See +Section\ \&34.16 +for more information\&. +.SH "EXAMPLES" +.PP +To clean the database +test: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBvacuumdb test\fR +.fi +.if n \{\ +.RE +.\} +.PP +To clean and analyze for the optimizer a database named +bigdb: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBvacuumdb \-\-analyze bigdb\fR +.fi +.if n \{\ +.RE +.\} +.PP +To clean a single table +foo +in a database named +xyzzy, and analyze a single column +bar +of the table for the optimizer: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBvacuumdb \-\-analyze \-\-verbose \-\-table=\*(Aqfoo(bar)\*(Aq xyzzy\fR +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +\fBVACUUM\fR(7) diff --git a/doc/src/sgml/man1/vacuumlo.1 b/doc/src/sgml/man1/vacuumlo.1 new file mode 100644 index 0000000..81b8fdd --- /dev/null +++ b/doc/src/sgml/man1/vacuumlo.1 @@ -0,0 +1,190 @@ +'\" t +.\" Title: vacuumlo +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.4 Documentation +.\" Source: PostgreSQL 15.4 +.\" Language: English +.\" +.TH "VACUUMLO" "1" "2023" "PostgreSQL 15.4" "PostgreSQL 15.4 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +vacuumlo \- remove orphaned large objects from a PostgreSQL database +.SH "SYNOPSIS" +.HP \w'\fBvacuumlo\fR\ 'u +\fBvacuumlo\fR [\fIoption\fR...] \fIdbname\fR... +.SH "DESCRIPTION" +.PP +vacuumlo +is a simple utility program that will remove any +\(lqorphaned\(rq +large objects from a +PostgreSQL +database\&. An orphaned large object (LO) is considered to be any LO whose OID does not appear in any +oid +or +lo +data column of the database\&. +.PP +If you use this, you may also be interested in the +\fBlo_manage\fR +trigger in the +lo +module\&. +\fBlo_manage\fR +is useful to try to avoid creating orphaned LOs in the first place\&. +.PP +All databases named on the command line are processed\&. +.SH "OPTIONS" +.PP +vacuumlo +accepts the following command\-line arguments: +.PP +\fB\-l \fR\fB\fIlimit\fR\fR +.br +\fB\-\-limit=\fR\fB\fIlimit\fR\fR +.RS 4 +Remove no more than +\fIlimit\fR +large objects per transaction (default 1000)\&. Since the server acquires a lock per LO removed, removing too many LOs in one transaction risks exceeding +max_locks_per_transaction\&. Set the limit to zero if you want all removals done in a single transaction\&. +.RE +.PP +\fB\-n\fR +.br +\fB\-\-dry\-run\fR +.RS 4 +Don\*(Aqt remove anything, just show what would be done\&. +.RE +.PP +\fB\-v\fR +.br +\fB\-\-verbose\fR +.RS 4 +Write a lot of progress messages\&. +.RE +.PP +\fB\-V\fR +.br +\fB\-\-version\fR +.RS 4 +Print the +vacuumlo +version and exit\&. +.RE +.PP +\fB\-?\fR +.br +\fB\-\-help\fR +.RS 4 +Show help about +vacuumlo +command line arguments, and exit\&. +.RE +.PP +vacuumlo +also accepts the following command\-line arguments for connection parameters: +.PP +\fB\-h \fR\fB\fIhost\fR\fR +.br +\fB\-\-host=\fR\fB\fIhost\fR\fR +.RS 4 +Database server\*(Aqs host\&. +.RE +.PP +\fB\-p \fR\fB\fIport\fR\fR +.br +\fB\-\-port=\fR\fB\fIport\fR\fR +.RS 4 +Database server\*(Aqs port\&. +.RE +.PP +\fB\-U \fR\fB\fIusername\fR\fR +.br +\fB\-\-username=\fR\fB\fIusername\fR\fR +.RS 4 +User name to connect as\&. +.RE +.PP +\fB\-w\fR +.br +\fB\-\-no\-password\fR +.RS 4 +Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a +\&.pgpass +file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&. +.RE +.PP +\fB\-W\fR +.br +\fB\-\-password\fR +.RS 4 +Force +vacuumlo +to prompt for a password before connecting to a database\&. +.sp +This option is never essential, since +vacuumlo +will automatically prompt for a password if the server demands password authentication\&. However, +vacuumlo +will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing +\fB\-W\fR +to avoid the extra connection attempt\&. +.RE +.SH "ENVIRONMENT" +.PP +\fBPGHOST\fR +.br +\fBPGPORT\fR +.br +\fBPGUSER\fR +.RS 4 +Default connection parameters\&. +.RE +.PP +This utility, like most other +PostgreSQL +utilities, also uses the environment variables supported by +libpq +(see +Section\ \&34.15)\&. +.PP +The environment variable +\fBPG_COLOR\fR +specifies whether to use color in diagnostic messages\&. Possible values are +always, +auto +and +never\&. +.SH "NOTES" +.PP +vacuumlo +works by the following method: First, +vacuumlo +builds a temporary table which contains all of the OIDs of the large objects in the selected database\&. It then scans through all columns in the database that are of type +oid +or +lo, and removes matching entries from the temporary table\&. (Note: Only types with these names are considered; in particular, domains over them are not considered\&.) The remaining entries in the temporary table identify orphaned LOs\&. These are removed\&. +.SH "AUTHOR" +.PP +Peter Mount +<peter@retep\&.org\&.uk> |