diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index dabbedf5fc5..385224a934f 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -62,7 +62,7 @@ - + @@ -117,8 +117,10 @@ - - + + + + diff --git a/doc/src/sgml/ref/commands.sgml b/doc/src/sgml/ref/commands.sgml index 005dbb4d6a9..770c3a20543 100644 --- a/doc/src/sgml/ref/commands.sgml +++ b/doc/src/sgml/ref/commands.sgml @@ -1,67 +1,69 @@ - -SQL Commands + + SQL Commands - -This is reference information for the SQL -commands supported by Postgres. - + + + This is reference information for the SQL + commands supported by Postgres. + + -&abort; -&alterTable; -&alterUser; -&begin; -&close; -&cluster; -&commit; -© -&createAggregate; -&createDatabase; -&createFunction; -&createIndex; -&createLanguage; -&createOperator; -&createRule; -&createSequence; -&createTable; -&createTrigger; -&createType; -&createUser; -&createView; -&declare; -&delete; -&dropAggregate; -&dropDatabase; -&dropFunction; -&dropIndex; -&dropLanguage; -&dropOperator; -&dropRule; -&dropSequence; -&dropTable; -&dropTrigger; -&dropType -&dropUser; -&dropView; -&explain; -&fetch; -&grant; -&insert; -&listen; -&load; -&lock; -&move; -¬ify; -&reset; -&revoke; -&rollback; -&select; -&set; -&show; -&unlisten; -&update; -&vacuum; - - + &abort; + &alterTable; + &alterUser; + &begin; + &close; + &cluster; + &commit; + ©Table; + &createAggregate; + &createDatabase; + &createFunction; + &createIndex; + &createLanguage; + &createOperator; + &createRule; + &createSequence; + &createTable; + &createTrigger; + &createType; + &createUser; + &createView; + &declare; + &delete; + &dropAggregate; + &dropDatabase; + &dropFunction; + &dropIndex; + &dropLanguage; + &dropOperator; + &dropRule; + &dropSequence; + &dropTable; + &dropTrigger; + &dropType + &dropUser; + &dropView; + &explain; + &fetch; + &grant; + &insert; + &listen; + &load; + &lock; + &move; + ¬ify; + &reset; + &revoke; + &rollback; + &select; + &set; + &show; + &unlisten; + &update; + &vacuum; + + - -Utility Applications + + Utility Applications - -This is reference information for the -Postgres support utilities. - + + + This is reference information for the + Postgres support utilities. + + -&createdb; -&createuser; -&destroydb; -&destroyuser; -&initdb; -&initlocation; -&pgDump; -&pgDumpall; -&psqlRef; -&vacuumdb; + &createdb; + &createuser; + &destroydb; + &destroyuser; + &initdb; + &initlocation; + &pgAccess; + &pgAdmin; + &pgDump; + &pgDumpall; + &psqlRef; + &vacuumdb; - + diff --git a/doc/src/sgml/ref/pgaccess-ref.sgml b/doc/src/sgml/ref/pgaccess-ref.sgml new file mode 100644 index 00000000000..ec9b9a1b65a --- /dev/null +++ b/doc/src/sgml/ref/pgaccess-ref.sgml @@ -0,0 +1,74 @@ + + + + pgaccess + + Application + + + + pgaccess + + + Postgres graphical interactive client + + + + + 1999-05-19 + + +pgaccess [ dbname ] + + + + + 1999-05-19 + + + Inputs + + + + + + + + 1999-05-19 + + + Outputs + + + + + + + + + 1999-05-19 + + + Description + + + + + + + diff --git a/doc/src/sgml/ref/pgadmin-ref.sgml b/doc/src/sgml/ref/pgadmin-ref.sgml new file mode 100644 index 00000000000..476923a455d --- /dev/null +++ b/doc/src/sgml/ref/pgadmin-ref.sgml @@ -0,0 +1,74 @@ + + + + pgadmin + + Application + + + + pgadmin + + + Postgres graphical interactive client + + + + + 1999-05-19 + + +pgadmin [ dbname ] + + + + + 1999-05-19 + + + Inputs + + + + + + + + 1999-05-19 + + + Outputs + + + + + + + + + 1999-05-19 + + + Description + + + + + + + diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 96860281f94..454e4c0ec4f 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1,1063 +1,1111 @@ - - -psql - -Application - - - -psql - - -Postgres interactive client - - - - -1998-09-26 - - + + + psql + + Application + + + + psql + + + Postgres interactive client + + + + + 1998-09-26 + + psql [ dbname ] psql -A [ -c query ] [ -d dbname ] -e -E [ -f filename ] [ -F separator ] [ -h hostname ] -Hln [ -o filename ] [ -p port ] -qsSt ] [ -T table_options ] -ux [ dbname ] - + - - - 1998-09-26 - - - Inputs - + + + 1998-09-26 + + + Inputs + + + psql accepts many command-line arguments, + a rich set of meta-commands, and the full SQL language + supported by Postgres. The most common + command-line arguments are: + + + + + dbname + + + + The name of an existing database to access. + dbname + defaults to the value of the + USER + environment variable or, if that's not set, to the Unix account name of the + current user. + + + + + + + -c query + + + + A single query to run. psql will exit on completion. + + + + + + + + The full set of command-line arguments and meta-commands are described in a subsequent + section. + + + There are some environment variables which can be used in liu of + command line arguments. + Additionally, the Postgres frontend library used by + the psql application + looks for other optional environment variables to configure, for example, + the style of date/time representation and the local time zone. Refer + to the chapter on libpq in the + Programmer's Guide for more details. + + + You may set any of the following environment variables to avoid + specifying command-line options: + + + + + PGHOST + + + + The DNS host name of the database server. + Setting PGHOST to a non-zero-length string causes + TCP/IP communication + to be used, rather than the default local Unix domain sockets. + + + + + + + PGPORT + + + + The port number on which a Postgres server is listening. + Defaults to 5432. + + + + + + + PGTTY + + + + The target for display of messages from the client support library. + Not required. + + + + + + + PGOPTION + + + + If PGOPTION + is specified, then the options it contains are parsed + before + any command-line options. + + + + + + + PGREALM + + + + PGREALM + only applies if + Kerberos + authentication is in use. + If this environment variable is set, Postgres + will attempt authentication with servers for this realm and will use + separate ticket files to avoid conflicts with local ticket files. + See the PostgreSQL Administrator's Guide + for additional information on + Kerberos. + + + + + + + + + + 1998-09-26 + + + Outputs + + + psql + returns 0 to the shell on successful completion of all queries, + 1 for errors, 2 for abrupt disconnection from the backend. + The default TAB delimiter is used. + psql + will also return 1 if the connection to a database could not be made for + any reason. + + + + + + + 1998-09-26 + + + Description + + + psql is a character-based front-end to + Postgres. + It enables you to + type in queries interactively, issue them to Postgres, + and see the query + results. + + + psql + is a Postgres client application. Hence, a + postmaster process + must be running on the database server host before + psql + is executed. In addition, the correct parameters to identify + the database server, such as the + postmaster host name, + may need to be specified + as described below. + + + When + psql + starts, it reads SQL commands from + /etc/psqlrc + and then from + $(HOME)/.psqlrc + This allows SQL commands like + SET + which can be used to set the date style to be run at the start of + every session. + + + + + 1998-09-26 + + + Connecting To A Database + + + psql + attempts to make a connection to the database at the hostname and + port number specified on the command line. If the connection could not + be made for any reason (e.g. insufficient privileges, postmaster is not + running on the server, etc) + .IR psql + will return an error that says + + Connection to database failed. + + The reason for the connection failure is not provided. + + + + + + 1998-09-26 + + + Entering Queries + + + In normal operation, + psql provides a prompt with the name of the + database that psql is current connected to + followed by the string "=>". + For example, + +$ psql testdb +Welcome to the POSTGRESQL interactive sql monitor: + Please read the file COPYRIGHT for copyright terms of POSTGRESQL +[PostgreSQL 6.5.0 on i686-pc-linux-gnu, compiled by gcc 2.7.2.3] + + type \? for help on slash commands + type \q to quit + type \g or terminate with semicolon to execute query + You are currently connected to the database: testdb + +testdb=> + + + + At the prompt, the user may type in SQL queries. + Unless the -S option + is set, input lines are sent to the backend when a query-terminating + semicolon is reached. + + + Whenever a query is executed, + psql also polls for asynchronous notification + events generated by LISTEN and NOTIFY. + + + psql + can be used in a pipe sequence, and automatically detects when it + is not listening or talking to a real tty. + + + + + Paging To Screen + + + Author + + From Brett McCormick on the mailing list 1998-04-04. + + + + + To affect the paging behavior of your psql output, + set or unset your PAGER environment variable. I always have to set mine + before it will pause. And of course you have to do this before + starting the program. + + + + In csh/tcsh or other C shells: + + +% unsetenv PAGER + + + while in sh/bash or other Bourne shells: + + +% unset PAGER + + + + + + + + 1998-09-26 + + + Command-line Options + + + psql + understands the following command-line options: + + + + + -A + + - psql accepts many command-line arguments, - a rich set of meta-commands, and the full SQL language - supported by Postgres. The most common - command-line arguments are: + Turn off fill justification when printing out table elements. + + + - - - - dbname - - - - The name of an existing database to access. - dbname - defaults to the value of the - USER - environment variable or, if that's not set, to the Unix account name of the - current user. - - - - - - - - -c query - - - - A single query to run. psql will exit on completion. - - - - - - - - The full set of command-line arguments and meta-commands are described in a subsequent - section. - - - There are some environment variables which can be used in liu of - command line arguments. - Additionally, the Postgres frontend library used by - the psql application - looks for other optional environment variables to configure, for example, - the style of date/time representation and the local time zone. Refer - to the chapter on libpq in the - Programmer's Guide for more details. - - - You may set any of the following environment variables to avoid - specifying command-line options: - - - - - PGHOST - - - - The DNS host name of the database server. - Setting PGHOST to a non-zero-length string causes - TCP/IP communication - to be used, rather than the default local Unix domain sockets. - - - - - - - PGPORT - - - - The port number on which a Postgres server is listening. - Defaults to 5432. - - - - - - - PGTTY - - - - The target for display of messages from the client support library. - Not required. - - - - - - - PGOPTION - - - - If PGOPTION - is specified, then the options it contains are parsed - before - any command-line options. - - - - - - - PGREALM - - - - PGREALM - only applies if - Kerberos - authentication is in use. - If this environment variable is set, Postgres - will attempt authentication with servers for this realm and will use - separate ticket files to avoid conflicts with local ticket files. - See the PostgreSQL Administrator's Guide - for additional information on - Kerberos. - - - - - - - - - - 1998-09-26 - - - Outputs - + + + -c query + + - - psql - returns 0 to the shell on successful completion of all queries, - 1 for errors, 2 for abrupt disconnection from the backend. - The default TAB delimiter is used. - psql - will also return 1 if the connection to a database could not be made for - any reason. + Specifies that + psql + is to execute one query string, + query, + and then exit. This is useful for shell scripts, typically in + conjunction with the option in shell scripts. - - - - - - 1998-09-26 - - - Description - - - psql is a character-based front-end to - Postgres. - It enables you to - type in queries interactively, issue them to Postgres, - and see the query - results. - - - psql - is a Postgres client application. Hence, a - postmaster process - must be running on the database server host before - psql - is executed. In addition, the correct parameters to identify - the database server, such as the - postmaster host name, - may need to be specified - as described below. - - - When - psql - starts, it reads SQL commands from - /etc/psqlrc - and then from - $(HOME)/.psqlrc - This allows SQL commands like - SET - which can be used to set the date style to be run at the start of - every session. - + + - - - 1998-09-26 - - - Connecting To A Database - - - psql - attempts to make a connection to the database at the hostname and - port number specified on the command line. If the connection could not - be made for any reason (e.g. insufficient privileges, postmaster is not - running on the server, etc) - .IR psql - will return an error that says - - Connection to database failed. - - The reason for the connection failure is not provided. + + + -d dbname + + + + Specifies the name of the database to connect to. This is equivalent to specifying + dbname as the last field in the + command line. - + + - - - 1998-09-26 - - - Entering Queries - - - In normal operation, - psql provides a prompt with the name of the - database that psql is current connected to - followed by the string "=>". - For example, - - $ psql testdb - Welcome to the POSTGRESQL interactive sql monitor: - Please read the file COPYRIGHT for copyright terms of POSTGRESQL - - type \e? for help on slash commands - type \eq to quit - type \eg or terminate with semicolon to execute query - You are currently connected to the database: testdb - - testdb=> - + + + -e + + + + Echo the query sent to the backend - - At the prompt, the user may type in SQL queries. - Unless the -S option - is set, input lines are sent to the backend when a query-terminating - semicolon is reached. + + + + + + -E + + + + Echo the actual query generated by \d and other backslash commands - - Whenever a query is executed, - psql also polls for asynchronous notification - events generated by LISTEN and NOTIFY. + + + + + + -f filename + + + + Use the file filename + as the source of queries instead of reading queries interactively. + This file must be specified for and visible to the client frontend. - - psql - can be used in a pipe sequence, and automatically detects when it - is not listening or talking to a real tty. + + + + + + -F separator + + + + Use separator + as the field separator. + The default is an ASCII vertical bar ("|"). - - + + - - - 1998-09-26 - - - Command-line Options - - - psql - understands the following command-line options: + + + -h hostname + + + + Specifies the host name of the machine on which the + postmaster + is running. + Without this option, communication is performed using + local Unix domain sockets. + + + - - - - -A - - - - Turn off fill justification when printing out table elements. - - - - - - - -c query - - - - Specifies that - psql - is to execute one query string, - query, - and then exit. This is useful for shell scripts, typically in - conjunction with the option in shell scripts. - - - - - - - -d dbname - - - - Specifies the name of the database to connect to. This is equivalent to specifying - dbname as the last field in the - command line. - - - - - - - -e - - - - Echo the query sent to the backend - - - + + + -H + + + + Turns on + HTML 3.0 + tabular output. + + + - - - -E - - - - Echo the actual query generated by \d and other backslash commands - - - + + + -l + + + + Lists all available databases, then exit. Other non-connection options are ignored. + + + - - - -f filename - - - - Use the file filename - as the source of queries instead of reading queries interactively. - This file must be specified for and visible to the client frontend. - - - - - - - -F separator - - - - Use separator - as the field separator. - The default is an ASCII vertical bar ("|"). - - - + + + -n + + + + Do not use the readline library for input line editing and command history. + + + - - - -h hostname - - - - Specifies the host name of the machine on which the - postmaster - is running. - Without this option, communication is performed using - local Unix domain sockets. - - - - - - - -H - - - - Turns on - HTML 3.0 - tabular output. - - - - - - - -l - - - - Lists all available databases, then exit. Other non-connection options are ignored. - - - - - - - -n - - - - Do not use the readline library for input line editing and command history. - - - - - - - -o filename - - - - Put all output into file filename. - The path must be writable by the client. - - - - - - - -p port - - - - Specifies the TCP/IP port or, by omission, the local Unix domain socket file - extension on which the - postmaster - is listening for connections. Defaults to the value of the - PGPORT - environment variable, if set, or to 5432. - - - - - - - -q - - - - Specifies that - psql - should do its work quietly. By default, it - prints welcome and exit messages and prompts for each query, and prints - out the number of rows returned from a query. - If this option is used, none of this happens. This is useful with the - option. - - - - - - - -s - - - - Run in single-step mode where the user is prompted for each query before - it is sent to the backend. - - - - - - - -S - - - - Runs in single-line mode where each query is terminated by a newline, - instead of a semicolon. - - - - - - - -t - - - - Turn off printing of column names. - This is useful with the - - option in shell scripts. - - - - - - - -T table_options - - - - Allows you to specify options to be placed within the - table ... tag for HTML 3.0 - tabular output.For example, border - will give you tables with borders. - This must be used in conjunction with the option. - - - - - - - -u - - - - Asks the user for the user name and password before connecting to the database. - If the database does not require password authentication then these are - ignored. If the option is not used (and the PGPASSWORD environment variable - is not set) and the database requires password authentication, then the - connection will fail. The user name is ignored anyway. - - - + + + -o filename + + + + Put all output into file filename. + The path must be writable by the client. + + + - - - -x - - - - Turns on extended row format mode. When enabled each row will have its column - names printed on the left with the column values printed on the right. - This is useful for rows which are otherwise too long to fit into - one screen line. HTML row output supports this mode also. - - - - - - - You may set environment variables to avoid typing some of the above - options. See the section on environment variables below. - - + + + -p port + + + + Specifies the TCP/IP port or, by omission, the local Unix domain socket file + extension on which the + postmaster + is listening for connections. Defaults to the value of the + PGPORT + environment variable, if set, or to 5432. + + + - - - 1998-09-26 - - - <application>psql</application> Meta-Commands - - - Anything you enter in psql - that begins with an unquoted backslash is a psql - meta-command. Anything else is SQL - and simply goes into the current query buffer - (and once you have at least one complete query, it gets automatically - submitted to the backend). - psql meta-commands are also called slash commands. - - - 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 white space characters. - - - With single character command verbs, you don't actually need to separate the - command verb from the argument with white space, for historical reasons. - You should anyway. - - - The following meta-commands are defined: + + + -q + + + + Specifies that + psql + should do its work quietly. By default, it + prints welcome and exit messages and prompts for each query, and prints + out the number of rows returned from a query. + If this option is used, none of this happens. This is useful with the + option. + + + - - - - \a - - - - Toggle field alignment when printing out table elements. - - - + + + -s + + + + Run in single-step mode where the user is prompted for each query before + it is sent to the backend. + + + - - - \C caption - - - - Set the HTML3.0 table caption to - caption. - - - + + + -S + + + + Runs in single-line mode where each query is terminated by a newline, + instead of a semicolon. + + + - - - \connect dbname [ username ] - - - - Establish a connection to a new database, using the default - username if none is specified. - The previous connection is closed. - - - + + + -t + + + + Turn off printing of column names. + This is useful with the + + option in shell scripts. + + + - - - \copy dbname { FROM | TO } filename - - - - Perform a frontend (client) copy. This is an operation that runs a SQL COPY command, - but instead of the backend reading or writing the specified file, and - consequently requiring backend access and special user privilege, - psql reads or writes the - file and routes the data to or from the backend. The default tab - delimiter is used. - - - - This operation is not as efficient as the SQL - COPY command because all data must pass through the - client/server IP or socket connection. For large amounts of data this other - technique may be preferable. - - - - + + + -T table_options + + + + Allows you to specify options to be placed within the + table ... tag for HTML 3.0 + tabular output.For example, border + will give you tables with borders. + This must be used in conjunction with the option. + + + - - - \d [ table ] - - - - List tables in the database, or if table - is specified, list the columns in that table. - If table name is specified as an asterisk (*), - list all tables and column information for each tables. - - - + + + -u + + + + Asks the user for the user name and password before connecting to the database. + If the database does not require password authentication then these are + ignored. If the option is not used (and the PGPASSWORD environment variable + is not set) and the database requires password authentication, then the + connection will fail. The user name is ignored anyway. + + + - - - \da - - - - List all available aggregates. - - - + + + -x + + + + Turns on extended row format mode. When enabled each row will have its column + names printed on the left with the column values printed on the right. + This is useful for rows which are otherwise too long to fit into + one screen line. HTML row output supports this mode also. + + + + + + + You may set environment variables to avoid typing some of the above + options. See the section on environment variables below. + + - - - \dd object - - - - List the description from pg_description - of the specified object, which can be a - table, table.column, type, operator, or aggregate. - - - - Not all objects have a description in pg_description. - This meta-command can be useful to get a quick description of a native - Postgres feature. - - - - + + + 1998-09-26 + + + <application>psql</application> Meta-Commands + + + Anything you enter in psql + that begins with an unquoted backslash is a psql + meta-command. Anything else is SQL + and simply goes into the current query buffer + (and once you have at least one complete query, it gets automatically + submitted to the backend). + psql meta-commands are also called slash commands. + + + 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 white space characters. + + + With single character command verbs, you don't actually need to separate the + command verb from the argument with white space, for historical reasons. + You should anyway. + + + The following meta-commands are defined: - - - \df - - - - List functions. - - - + + + + \a + + + + Toggle field alignment when printing out table elements. + + + - - - \di - - - - List only indexes. - - - + + + \C caption + + + + Set the HTML3.0 table caption to + caption. + + + - - - \do - - - - List only operators. - - - + + + \connect dbname [ username ] + + + + Establish a connection to a new database, using the default + username if none is specified. + The previous connection is closed. + + + - - - \ds - - - - List only sequences. - - - - - - - \dS - - - - List system tables and indexes. - - - - - - - \dt - - - - List only non-system tables. - - - + + + \copy dbname { FROM | TO } filename + + + + Perform a frontend (client) copy. This is an operation that runs a SQL COPY command, + but instead of the backend reading or writing the specified file, and + consequently requiring backend access and special user privilege, + psql reads or writes the + file and routes the data to or from the backend. The default tab + delimiter is used. + + + + This operation is not as efficient as the SQL + COPY command because all data must pass through the + client/server IP or socket connection. For large amounts of data this other + technique may be preferable. + + + + - - - \dT - - - - List types. - - - + + + \d [ table ] + + + + List tables in the database, or if table + is specified, list the columns in that table. + If table name is specified as an asterisk (*), + list all tables and column information for each tables. + + + - - - \e [ filename ] - - - - Edit the current query buffer or the contents of the file - filename. - - - + + + \da + + + + List all available aggregates. + + + - - - \E [ filename ] - - - - Edit the current query buffer or the contents of the file - filename - and execute it upon editor exit. - - - + + + \dd object + + + + List the description from pg_description + of the specified object, which can be a + table, table.column, type, operator, or aggregate. + + + + Not all objects have a description in pg_description. + This meta-command can be useful to get a quick description of a native + Postgres feature. + + + + - - - \f [ separator ] - - - - Set the field separator. Default is a single blank space. - - - + + + \df + + + + List functions. + + + - - - \g [ { filename | |command } ] - - - - Send the current query input buffer to the backend and optionally - save the output in filename - or pipe the output into a separate Unix shell to execute - command. - - - + + + \di + + + + List only indexes. + + + - - - \h [ command ] - - - - Give syntax help on the specified SQL command. - If command is not a defined SQL command - (or is not documented in psql), or if - command is not specified, - then psql will - list all the commands for which syntax help is - available. If command - is an asterisk (*), then - give syntax help on all SQL commands. - - - + + + \do + + + + List only operators. + + + - - - \H - - - - Toggle HTML3 output. This is equivalent to the - command-line option. - - - + + + \ds + + + + List only sequences. + + + - - - \i filename - - - - Read queries from the file filename - into the query input buffer. - - - - - - - \l - - - - List all the databases in the server. - - - - - - - \m - - - - Toggle the old monitor-like table display, which includes border characters - surrounding the table. - This is standard SQL output. - By default, psql includes only field separators - between columns. - - - + + + \dS + + + + List system tables and indexes. + + + - - - \o [ { filename | |command } ] - - - - Save future query results to the file - filename or pipe future - results into a separate Unix shell to execute - command. - If no arguments are specified, send query results to - stdout. - - - + + + \dt + + + + List only non-system tables. + + + - - - \p - - - - Print the current query buffer. - - - + + + \dT + + + + List types. + + + - - - \q - - - - Quit the psql program. - - - + + + \e [ filename ] + + + + Edit the current query buffer or the contents of the file + filename. + + + - - - \r - - - - Reset(clear) the query buffer. - - - - - - - \s [ filename ] - - - - Print or save the command line history to - filename. - If filename is omitted, - do not save subsequent commands to a history file. - This option is only available if psql is - configured to use readline. - - - - - - - \t - - - - Toggle display of output column name headings and row count footer (defaults to on). - - - - - - - \T table_options - - - - Allows you to specify options to be placed within the - table ... tag - for HTML 3.0 - tabular output.For example, border - will give you tables with borders. - This must be used in conjunction with the \H meta-command. - - - + + + \E [ filename ] + + + + Edit the current query buffer or the contents of the file + filename + and execute it upon editor exit. + + + - - - \x - - - - Toggles extended row format mode. When enabled each row will have its column - names printed on the left with the column values printed on the right. - This is useful for rows which are otherwise too long to fit into - one screen line. HTML row output mode supports this flag too. - - - + + + \f [ separator ] + + + + Set the field separator. Default is a single blank space. + + + - - - \w filename - - - - Outputs the current query buffer to the file - filename. - - - - - - - \z - - - - Produces a list of all tables in the database with their appropriate ACLs - (grant/revoke permissions) listed. - - - + + + \g [ { filename | |command } ] + + + + Send the current query input buffer to the backend and optionally + save the output in filename + or pipe the output into a separate Unix shell to execute + command. + + + - - - \! [ command ] - - - - Escape to a separate Unix shell or execute the Unix command - command. - - - + + + \h [ command ] + + + + Give syntax help on the specified SQL command. + If command is not a defined SQL command + (or is not documented in psql), or if + command is not specified, + then psql will + list all the commands for which syntax help is + available. If command + is an asterisk (*), then + give syntax help on all SQL commands. + + + - - - \? - - - - Get help information about the slash (\) commands. - - - - - - + + + \H + + + + Toggle HTML3 output. This is equivalent to the + command-line option. + + + + + + + \i filename + + + + Read queries from the file filename + into the query input buffer. + + + + + + + \l + + + + List all the databases in the server. + + + + + + + \m + + + + Toggle the old monitor-like table display, which includes border characters + surrounding the table. + This is standard SQL output. + By default, psql includes only field separators + between columns. + + + + + + + \o [ { filename | |command } ] + + + + Save future query results to the file + filename or pipe future + results into a separate Unix shell to execute + command. + If no arguments are specified, send query results to + stdout. + + + + + + + \p + + + + Print the current query buffer. + + + + + + + \q + + + + Quit the psql program. + + + + + + + \r + + + + Reset(clear) the query buffer. + + + + + + + \s [ filename ] + + + + Print or save the command line history to + filename. + If filename is omitted, + do not save subsequent commands to a history file. + This option is only available if psql is + configured to use readline. + + + + + + + \t + + + + Toggle display of output column name headings and row count footer (defaults to on). + + + + + + + \T table_options + + + + Allows you to specify options to be placed within the + table ... tag + for HTML 3.0 + tabular output.For example, border + will give you tables with borders. + This must be used in conjunction with the \H meta-command. + + + + + + + \x + + + + Toggles extended row format mode. When enabled each row will have its column + names printed on the left with the column values printed on the right. + This is useful for rows which are otherwise too long to fit into + one screen line. HTML row output mode supports this flag too. + + + + + + + \w filename + + + + Outputs the current query buffer to the file + filename. + + + + + + + \z + + + + Produces a list of all tables in the database with their appropriate ACLs + (grant/revoke permissions) listed. + + + + + + + \! [ command ] + + + + Escape to a separate Unix shell or execute the Unix command + command. + + + + + + + \? + + + + Get help information about the slash (\) commands. + + + + + + + + diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml index bac4c069148..12c9e47fcc5 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -1,689 +1,704 @@ - - -SET - -SQL - Language Statements - - - -SET - - + + + SET + + SQL - Language Statements + + + + SET + + Set run-time parameters for session - - - - -1998-09-24 - - - - + + + + + 1998-09-24 + + SET variable { TO | = } { 'value' | DEFAULT } SET TIME ZONE { 'timezone' | LOCAL }; - + - - - 1998-09-24 - - - Inputs - - + + + 1998-09-24 + + + Inputs + + - - - - variable - - - - Settable global parameter. - - - - - - value - - - - New value of parameter. - - - - - - - The possible variables and allowed values are: + + + + variable + + + + Settable global parameter. + + + + + + value + + + + New value of parameter. + + + + + + + The possible variables and allowed values are: - - - - DateStyle - - - - - - - - ISO - - - - use ISO 8601-style dates and times - - - - - - SQL - - - - use Oracle/Ingres-style dates and times - - - - - - Postgres - - - - use traditional Postgres format - - - - - - European - - - - use dd/mm/yyyy for numeric date representations. - - - - - - NonEuropean - - - - use mm/dd/yyyy for numeric date representations. - - - - - - German - - - - use dd.mm.yyyy for numeric date representations. - - - - - - US - - - - same as 'NonEuropean' - - - - - - default - - - - restores the default values ('US,Postgres') - - - - - - - - - - - Date format initialization my be done by: - - - Setting PGDATESTYLE environment variable. - - - Running postmaster using -oe parameter to set - dates to the 'European' convention. - Note that this affects only the some combinations of date styles; for example - the ISO style is not affected by this parameter. - - - Changing variables in - src/backend/utils/init/globals.c. - - - - - The variables in globals.c which can be changed are: - - bool EuroDates = false - true - int DateStyle = USE_ISO_DATES - USE_POSTGRES_DATES - USE_ISO_DATES - USE_SQL_DATES - USE_GERMAN_DATES - - - - - - - TIMEZONE - - - - The possible values for timezone depends on your operating - system. For example on Linux /usr/lib/zoneinfo contains the - database of timezones. - - - Here are some valid values for timezone: - - - - - 'PST8PDT' - - - - set the timezone for California - - - - - - 'Portugal' - - - - set time zone for Portugal. - - - - - - 'Europe/Rome' - - - - set time zone for Italy. - - - - - - DEFAULT - - - - set time zone to your local timezone - (value of the TZ environment variable). - - - - - - - If an invalid time zone is specified, the time zone - becomes GMT (on most systems anyway). - - - A frontend which uses libpq may be initialized by setting the PGTZ - environment variable. - - - The second syntax shown above, allows one to set the timezone - with a syntax similar to SQL92 SET TIME ZONE. - The LOCAL keyword is just an alternate form - of DEFAULT for SQL92 compatibility. - - - - - - - There are also several internal or optimization - parameters which can be specified - by the SET command: - - - - - COST_HEAP - - - - Sets the default cost of a heap scan for use by the optimizer. - - - - - float4 - - - - Set the cost of a heap scan to the specified floating point value. - - - - - - - DEFAULT - - - - Sets the cost of a heap scan to the default value. - - - - - - - The frontend may be initialized by setting the PGCOSTHEAP - environment variable. - - - - - COST_INDEX - - - - Sets the default cost of an index scan for use by the optimizer. - - - - - - - float4 - - - - Set the cost of an index scan to the specified floating point value. - - - - - - - DEFAULT - - - - Sets the cost of an index scan to the default value. - - - - - - - - - - The frontend may be initialized by setting the PGCOSTINDEX - environment variable. - - - - - GEQO - - - - Sets the threshold for using the genetic optimizer algorithm. - - - - - - On - - - - enables the genetic optimizer algorithm - for statements with 6 or more tables. - - - - - - On=# - - - - Takes an integer argument to enable the genetic optimizer algorithm - for statements with # - or more tables in the query. - - - - - - Off - - - - disables the genetic optimizer algorithm. - - - - - - DEFAULT - - - - Equivalent to specifying SET GEQO='on' - - - - - - - - - - This algorithm is on by default, which used GEQO for - statements of eleven or more tables. - (See the chapter on GEQO in the Programmer's Guide - for more information). - - - The frontend may be initialized by setting PGGEQO - environment variable. - - - It may be useful when joining big relations with - small ones. This algorithm is off by default. - It's not used by GEQO anyway. - - - - - KSQO - - - - Key Set Query Optimizer forces the query optimizer - to optimize repetative OR clauses such as generated by - MicroSoft Access: - - - - - - On - - - - enables this optimization. - - - - - - - Off - - - - disables this optimization. - - - - - - - DEFAULT - - - - Equivalent to specifying SET KSQO='off'. - - - - - - - - - - It may be useful when joining big relations with - small ones. This algorithm is off by default. - It's not used by GEQO anyway. - - - The frontend may be initialized by setting the PGKSQO - environment variable. - - - - QUERY_LIMIT - - - - Sets the number of rows returned by a query. - - - - - - Value - - - - Maximum number of rows to return for a query. The default is to allow - an unlimited number of rows. - - - - - - # - - - - Sets the maximum number of rows returned by a - query to #. - - - - - - DEFAULT - - - - Sets the maximum number of rows returned by a query to be unlimited. - - - - - - By default, there is no limit to the number of rows - returned by a query. - - - - - - + + + + DateStyle + + + - - - 1998-09-24 - - - Outputs - - - - - - - SET VARIABLE - - - - Message returned if successfully. - - - - - - - WARN: Bad value for variable (value) - - - - If the command fails to set variable. - - - - - + + + + ISO + + + + use ISO 8601-style dates and times + + + + + + SQL + + + + use Oracle/Ingres-style dates and times + + + + + + Postgres + + + + use traditional Postgres format + + + + + + European + + + + use dd/mm/yyyy for numeric date representations. + + + + + + NonEuropean + + + + use mm/dd/yyyy for numeric date representations. + + + + + + German + + + + use dd.mm.yyyy for numeric date representations. + + + + + + US + + + + same as 'NonEuropean' + + + + + + default + + + + restores the default values ('US,Postgres') + + + + + + + + + + + Date format initialization my be done by: + + + Setting PGDATESTYLE environment variable. + + + Running postmaster using -oe parameter to set + dates to the 'European' convention. + Note that this affects only the some combinations of date styles; for example + the ISO style is not affected by this parameter. + + + Changing variables in + src/backend/utils/init/globals.c. + + + + + The variables in globals.c which can be changed are: + + + bool EuroDates = false | true + + + int DateStyle = USE_ISO_DATES | USE_POSTGRES_DATES | USE_SQL_DATES | USE_GERMAN_DATES + + + + + + + + + TIMEZONE + + + + The possible values for timezone depends on your operating + system. For example on Linux /usr/lib/zoneinfo contains the + database of timezones. + + + Here are some valid values for timezone: + + + + + 'PST8PDT' + + + + set the timezone for California + + + + + + 'Portugal' + + + + set time zone for Portugal. + + + + + + 'Europe/Rome' + + + + set time zone for Italy. + + + + + + DEFAULT + + + + set time zone to your local timezone + (value of the TZ environment variable). + + + + + + + If an invalid time zone is specified, the time zone + becomes GMT (on most systems anyway). + + + A frontend which uses libpq may be initialized by setting the PGTZ + environment variable. + + + The second syntax shown above, allows one to set the timezone + with a syntax similar to SQL92 SET TIME ZONE. + The LOCAL keyword is just an alternate form + of DEFAULT for SQL92 compatibility. + + + + + + + There are also several internal or optimization + parameters which can be specified + by the SET command: + + + + + COST_HEAP + + + + Sets the default cost of a heap scan for use by the optimizer. + + + + + float4 + + + + Set the cost of a heap scan to the specified floating point value. + + + + + + + DEFAULT + + + + Sets the cost of a heap scan to the default value. + + + + + + + The frontend may be initialized by setting the PGCOSTHEAP + environment variable. + + + + + COST_INDEX + + + + Sets the default cost of an index scan for use by the optimizer. - - + + + + + + float4 + + + + Set the cost of an index scan to the specified floating point value. + + + + + + + DEFAULT + + + + Sets the cost of an index scan to the default value. + + + + + + + + + + The frontend may be initialized by setting the PGCOSTINDEX + environment variable. + + + + + GEQO + + + + Sets the threshold for using the genetic optimizer algorithm. + + + + + + On + + + + enables the genetic optimizer algorithm + for statements with 6 or more tables. + + + + + + On=# + + + + Takes an integer argument to enable the genetic optimizer algorithm + for statements with # + or more tables in the query. + + + + + + Off + + + + disables the genetic optimizer algorithm. + + + + + + DEFAULT + + + + Equivalent to specifying SET GEQO='on' + + + + + + + + + + This algorithm is on by default, which used GEQO for + statements of eleven or more tables. + (See the chapter on GEQO in the Programmer's Guide + for more information). + + + The frontend may be initialized by setting PGGEQO + environment variable. + + + It may be useful when joining big relations with + small ones. This algorithm is off by default. + It's not used by GEQO anyway. + + + + + KSQO + + + + Key Set Query Optimizer forces the query optimizer + to optimize repetative OR clauses such as generated by + MicroSoft Access: + + + + + + On + + + + enables this optimization. + + + + + + + Off + + + + disables this optimization. + + + + + + + DEFAULT + + + + Equivalent to specifying SET KSQO='off'. + + + + + + + + + + It may be useful when joining big relations with + small ones. This algorithm is off by default. + It's not used by GEQO anyway. + + + The frontend may be initialized by setting the PGKSQO + environment variable. + + + + QUERY_LIMIT + + + + Sets the number of rows returned by a query. + + + + + + Value + + + + Maximum number of rows to return for a query. The default is to allow + an unlimited number of rows. + + + + + + # + + + + Sets the maximum number of rows returned by a + query to #. + + + + + + DEFAULT + + + + Sets the maximum number of rows returned by a query to be unlimited. + + + + + + By default, there is no limit to the number of rows + returned by a query. + + + + + + - - - 1998-09-24 - - - Description - - - SET will modify configuration parameters for variable during + + + 1998-09-24 + + + Outputs + + + + + + + SET VARIABLE + + + + Message returned if successfully. + + + + + + + WARN: Bad value for variable (value) + + + + If the command fails to set variable. + + + + + + + + + + + + 1998-09-24 + + + Description + + + SET will modify configuration parameters for variable during a session. - - - Current values can be obtained using SHOW, and values - can be restored to the defaults using RESET. - Parameters and values are case-insensitive. Note that the value - field is always specified as a string, so is enclosed in - single-quotes. - - - SET TIME ZONE changes the session's - default time zone offset. - A SQL-session always begins with an initial default time zone - offset. - The SET TIME ZONE statement is used to change the default - time zone offset for the current SQL session. - + + + Current values can be obtained using SHOW, and values + can be restored to the defaults using RESET. + Parameters and values are case-insensitive. Note that the value + field is always specified as a string, so is enclosed in + single-quotes. + + + SET TIME ZONE changes the session's + default time zone offset. + A SQL-session always begins with an initial default time zone + offset. + The SET TIME ZONE statement is used to change the default + time zone offset for the current SQL session. + + + + + 1998-09-24 + + + Notes + + + The SET variable + statement is a Postgres language extension. + + + Refer to SHOW and RESET to + display or reset the current values. + + + + + + + Usage + + + + + --Set the style of date to ISO: + -- + SET DATESTYLE TO 'ISO'; + + + --Enable GEQO for queries with 4 or more tables + -- + SET GEQO ON=4; + + + --Set GEQO to default: + -- + SET GEQO = DEFAULT; + + + --set the timezone for Berkeley, California: + SET TIME ZONE 'PST8PDT'; + + SELECT CURRENT_TIMESTAMP AS today; + + today + ---------------------- + 1998-03-31 07:41:21-08 + + + --set the timezone for Italy: + SET TIME ZONE 'Europe/Rome'; + + SELECT CURRENT_TIMESTAMP AS today; + + today + ---------------------- + 1998-03-31 17:41:31+02 + + + - - - 1998-09-24 - - - Notes - - - The SET variable - statement is a Postgres language extension. - - - Refer to SHOW and RESET to - display or reset the current values. - - - - - - - Usage - - - - - --Set the style of date to ISO: - -- - SET DATESTYLE TO 'ISO'; - - - --Enable GEQO for queries with 4 or more tables - -- - SET GEQO ON=4; - - - --Set GEQO to default: - -- - SET GEQO = DEFAULT; - - - --set the timezone for Berkeley, California: - SET TIME ZONE 'PST8PDT'; - - SELECT CURRENT_TIMESTAMP AS today; - - today - ---------------------- - 1998-03-31 07:41:21-08 - - - --set the timezone for Italy: - SET TIME ZONE 'Europe/Rome'; - - SELECT CURRENT_TIMESTAMP AS today; - - today - ---------------------- - 1998-03-31 17:41:31+02 - - - - - - - Compatibility - - - - - - - 1998-09-24 - - - SQL92 - - - There is no - SET variable - in SQL92. - - The SQL92 syntax for SET TIME ZONE - is slightly different, - allowing only a single integer value for time zone specification: - - - SET TIME ZONE { interval_value_expression | LOCAL } - - - - + + + Compatibility + + + + + + + 1998-09-24 + + + SQL92 + + + There is no + SET variable + in SQL92. + + The SQL92 syntax for SET TIME ZONE + is slightly different, + allowing only a single integer value for time zone specification: + + + SET TIME ZONE { interval_value_expression | LOCAL } + + + + + +