gsql Usage Guide

Description

gsql, provided by GaussDB, is a database connection tool running in the command-line interface. You can use gsql to connect to the server and perform operations and maintenance on it. gsql enables users to perform basic operations on the database and provides several advanced features.

Basic functions:

• Connect to a database: By default, only the local server can be connected. To connect to a remote database, you must configure it on the local server. For details, see "Database Quick Start > Connecting to a Database > Using gsql to Connect to a Database > Remotely Connecting to a Database" in Developer Guide.
  

  If gsql is used to connect to a database, the connection timeout period will be 5 minutes. If the database has not correctly set up a connection and authenticated the identity of the client within this period, gsql will time out and exit. To resolve this problem, see FAQ.

• Run SQL statements: You can interactively enter SQL statements and run them, or run specified SQL statements in a file.
• Run meta-commands: Meta-commands can help administrators view database object information, query cache information, format SQL output, and connect to a new database. For details about meta-commands, see Meta-Command Reference.

Advanced functions:

Table 1 lists the advanced features of gsql.

\set varname value

\unset varname

• Variables
  To set a variable, run the \set meta-command of gsql. For example, to set variable foo to bar, run the following command:

  1	gaussdb=# \set foo bar

  To reference the value of a variable, add a colon (:) before the variable. For example, to view the value of variable foo, run the following command:

  1 2	gaussdb=# \echo :foo bar

  This variable reference method is applicable to regular SQL statements and meta-commands except \copy, \ef, \help, \sf, and \!.

  gsql pre-defines some special variables and plans the values of these variables. To ensure compatibility with later versions, do not use these variables for other purposes. For details about special variables, see Table 2.

  

  • All the special variables consist of upper-case letters, digits, and underscores (_).
  • To view the default value of a special variable, run the \echo :varname meta-command, for example, \echo :DBNAME.

  Table 2 Settings of special variables

  Variable	Setting Method	Description
  DBNAME	\set DBNAME dbname	Name of the connected database. This variable is set again when a database is connected.
  ECHO	\set ECHO all | queries	If this variable is set to all, only the query information is displayed. This has the same effect as specifying the -a parameter when gsql is used to connect to a database. If this variable is set to queries, the command line and query information are displayed. This has the same effect as specifying the -e parameter when gsql is used to connect to a database.
  ECHO_HIDDEN	\set ECHO_HIDDEN on | off | noexec	When a meta-command (such as \dg) is used to query database information, the value of this variable determines the query behavior. If this variable is set to on, the query statements that are called by the meta-command are displayed, and then the query result is displayed. This has the same effect as specifying the -E parameter when gsql is used to connect to a database. If this variable is set to off, only the query result is displayed. If this variable is set to noexec, only the query information is displayed, and the query is not run.
  ENCODING	\set ENCODING encoding	Character set encoding of the current client.
  FETCH_COUNT	\set FETCH_COUNT variable	If the value is an integer greater than 0, for example, n, n lines will be selected from the result set to the cache and displayed on the screen when the SELECT statement is run. If this variable is not set or set to a value less than or equal to 0, all results are selected at a time to the cache when the SELECT statement is run. NOTE: A proper variable value helps reduce the memory usage. The recommended value range is from 100 to 1000.
  HISTCONTROL	\set HISTCONTROL ignorespace | ignoredups | ignoreboth | none	ignorespace: A line started with a space is not written to the historical record. ignoredups: A line that exists in the historical record is not written to the historical record. ignoreboth, none, or other values: All the lines read in interaction mode are saved in the historical record. NOTE: none indicates that HISTCONTROL is not set.
  HISTFILE	\set HISTFILE filename	Specifies the file for storing historical records. The default value is ~/.bash_history.
  HISTSIZE	\set HISTSIZE size	Specifies the number of commands to store in the command history. The default value is 500.
  HOST	\set HOST hostname	Specifies the name of a connected host.
  IGNOREEOF	\set IGNOREEOF variable	If this variable is set to a number, for example, 10, the first nine EOF characters (generally Ctrl+C) entered in gsql are neglected and the gsql program exits when the tenth Ctrl+C is entered. If this variable is set to a non-numeric value, the default value is 10. If this variable is deleted, gsql exits when an EOF is entered.
  LASTOID	\set LASTOID oid	Specifies the last OID, which is the value returned by an INSERT or lo_import command. This variable is valid only before the output of the next SQL statement is displayed.
  ON_ERROR_ROLLBACK	\set ON_ERROR_ROLLBACK on | interactive | off	on: When an error occurs in a statement in a transaction block, the system automatically rolls back to the state before the previous command is executed and continues to execute subsequent commands. This mode works by implicitly creating a SAVEPOINT before each command of a transaction block. When an error occurs, the system automatically rolls back to the previously created SAVEPOINT to cancel the impact of the failed command. interactive: Automatic rollback is enabled only in interactive sessions. off (default value): The entire transaction is terminated when an error occurs in a statement in a transaction block.
  ON_ERROR_STOP	\set ON_ERROR_STOP on | off	on: The execution stops if an error occurs. In interactive mode, gsql returns the output of executed commands immediately. off (default value): An error, if occurring during the execution, is ignored, and the execution continues.
  PORT	\set PORT port	Specifies the port number of a connected database.
  USER	\set USER username	Specifies the database user you are currently connected as.
  VERBOSITY	\set VERBOSITY terse | default | verbose	This option is used to control redundant lines in error reports. terse: Only critical and major error texts and text locations are returned (which is generally suitable for single-line error information). default: Critical and major error texts and text locations, error details, and error messages (possibly involving multiple lines) are all returned. verbose: All error information is returned.

• SQL substitution
  gsql, like a parameter of a meta-command, provides a key feature that enables you to substitute a standard SQL statement for a gsql variable. gsql also provides a new alias or identifier for the variable. To replace the value of a variable using the SQL substitution method, add a colon (:) before the variable. For example:

  1 2 3 4 5 6 7 8 9 10

  gaussdb=# \set foo 'HR.areaS' -- Run the following command to query the HR.areaS table: gaussdb=# SELECT * FROM :foo; area_id | area_name ---------+------------------------ 4 | Middle East and Africa 3 | Asia 1 | Europe 2 | Americas (4 rows)

  

  The value of a variable is copied word by word and can even contain asymmetric quotation marks or backslash commands. Therefore, the input content must be meaningful.

• Prompts

  The gsql prompt can be set using the three variables in Table 3. These variables consist of characters and special escape characters.

  Table 3 Prompt variables

  Variable	Description	Example
  PROMPT1	Specifies the normal prompt used when gsql requests a new command. The default value of PROMPT1 is %o%R%#.	PROMPT1 can be used to change the prompt. Change the prompt to [local]: 1 2 gaussdb=# \set PROMPT1 %M local:/data/huawei/wisequery/perfadm_mppdb Change the prompt to name: 1 2 gaussdb=# \set PROMPT1 name name Change the prompt to =: 1 2 gaussdb=# \set PROMPT1 %R =
  PROMPT2	Specifies the prompt displayed when more input is expected (when the command is not terminated with a semicolon (;) or the quotation marks ("") are not in pair).	PROMPT2 can be used to display the prompt. 1 2 3 4 5 6 7 8 9 10 gaussdb=# \set PROMPT2 TEST gaussdb=# SELECT * FROM HR.areaS TEST; area_id | area_name ---------+-------------------- 1 | Europe 2 | Americas 4 | Middle East and Africa 3 | Asia (4 rows)
  PROMPT3	Specifies the prompt displayed when the COPY statement (such as COPY FROM STDIN) is run and data input is expected.	PROMPT3 can be used to display the COPY prompt. 1 2 3 4 5 6 7 gaussdb=# \set PROMPT3 '>>>>' gaussdb=# COPY HR.areaS FROM STDIN; Enter data to be copied followed by a newline. End with a backslash and a period on a line by itself. >>>>1 aa >>>>2 bb >>>>\.

  The value of the selected prompt variable is printed literally. However, a value containing a percent sign (%) is replaced by the predefined contents depending on the character following the percent sign (%). For details about the defined substitutions, see Table 4.

  Table 4 Defined substitutions

  Symbol	Description
  %M	Replaced by the full host name (with domain name). The full name is [local] if the connection is over a UDS, or [local:/dir/name] if the UDS is not at the compiled default location.
  %m	Replaced by the host name truncated at the first dot. It is [local] if the connection is over a UDS.
  %o	Database name. For the postgres database, gaussdb is displayed. For other databases, the database name is displayed.
  %>	Replaced by the number of the port that the host is listening on.
  %n	Replaced by the database session username.
  %/	Replaced by the name of the current database.
  %~	Similar to %/. However, the tilde (~) is used if the database is your default database.
  %#	The number sign (#) is used if the session user is the database administrator; otherwise, the greater-than sign (>) is used.
  %R	For PROMPT1, = typically, but ^ in single-line mode, or ! if the session is disconnected from the database (which can happen if \connect fails). For PROMPT2, it is replaced by a hyphen (-), an asterisk (*), a single or double quotation mark, or a dollar sign ($), depending on whether gsql expects more input, for example, the query is not terminated, in a /* ... */ the comment, enclosed with quotation marks, or in a dollar sign extension.
  %x	Replaced by the transaction status. An empty string when it is not in a transaction block An asterisk (*) when it is in a transaction block An exclamation mark (!) when it is in a failed transaction block A question mark (?) when the transaction status is indefinite (for example, because there is no connection).
  %digits	Replaced by the character with the specified byte.
  %:name	Replaced by the value of the name variable of gsql.
  %command	Replaced by the command output, similar to substitution with the "^" symbol.
  %[ . . . %]	Prompts may 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. For example: gaussdb=# \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%#' The output is a boldfaced (1;) yellow-on-black (33;40) prompt on VT100-compatible, color-capable terminals.

  Environment variables:

  For details about gsql-related environment variables, see Table 5.

  Table 5 Environment variables related to gsql

  Name	Description
  COLUMNS	If \set columns is set to 0, this parameter controls the width of the wrapped format. This width determines whether to change the wide output mode into the vertical output mode if automatic expansion is enabled.
  PAGER	If the query results do not fit on the screen, they are redirected through this command. You can use the \pset command to disable the pager. Typically, the more or less command is used for viewing the query result page by page. The default is platform-dependent. NOTE: Display of the less command is affected by the LC_CTYPE environment variable.
  PSQL_EDITOR	The \e and \ef commands use the editor specified by the environment variables. The variables are examined in the order listed. The default editor on Unix is vi.
  EDITOR
  VISUAL
  PSQL_EDITOR_LINENUMBER_ARG	When the \e or \ef command is used with a line number parameter, this variable specifies the command-line parameter used to pass the starting line number to the editor. For the Emacs or Vi editor, the value of this parameter is a plus sign (+). Include a space in the value of the variable if space is needed between the option name and the line number. For example: PSQL_EDITOR_LINENUMBER_ARG = '+' PSQL_EDITOR_LINENUMBER_ARG='--line ' A plus sign (+) is used by default on Unix.
  PSQLRC	Specifies the location of the user's .gsqlrc file.
  SHELL	Using the \! command has the same effect as executing the shell command.
  TMPDIR	Specifies the directory for storing temporary files. The default value is /tmp.

Prerequisites

• The user using gsql must have the permission to access the database.
• gsql must match the database version.

Precautions

• You can use the gsql_env.sh script in the release package to set environment variables, for example, source gsql_env.sh.
• If environment variables have been set, the environment variables in the script take precedence after the gsql_env.sh script is executed.

Format

gsql [OPTION]... [DBNAME [USERNAME]]

Parameters

For details about gsql parameters, see Table 6, Table 7, Table 8, and Table 9.

Example

Example 1

Connect to a database and run the command.

1. Connect to the GaussDB server using the gsql tool.

   The gsql tool uses the -d parameter to specify the target database name, the -U parameter to specify the database username, the -h parameter to specify the host name, and the -p parameter to specify the port number. For details about the gsql parameters, see Parameters.

   -- Connect to the 8000 port of the postgres database on the remote host as user jack. (Replace the parameter values as required.)
   gsql -h 10.180.123.163 -d postgres -U jack -p 8000

   

   • If the database name is not specified, the default database name generated during initialization is used.
   • If the database username is not specified, the current OS user is used as the database username by default.
   • When the preceding parameters (such as -d or -U) are not specified, if the database name is not specified in the connection command (-d), the parameter is interpreted as the database name; if the database name is specified (-d) but the database username is not specified (-U), this parameter is interpreted as the database username.

     For example, in the following command, postgres and omm are not options and are interpreted as the database name and username, respectively.

     gsql postgres omm -p 8000

     It is equivalent to the following command:

     gsql -d postgres -U omm -p 8000

2. Run an SQL statement.

   1 2 3

   -- Create the human_staff database. gaussdb=# CREATE DATABASE human_staff; CREATE DATABASE

3. Execute gsql meta-commands and SQL statements.

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

   -- List all databases and description information in GaussDB. gaussdb=# \l List of databases Name | Owner | Encoding | Collate | Ctype | Access privileges ----------------+----------+-----------+---------+-------+----------------------- human_resource | omm | SQL_ASCII | C | C | postgres | omm | SQL_ASCII | C | C | template0 | omm | SQL_ASCII | C | C | =c/omm + | | | | | omm=CTc/omm template1 | omm | SQL_ASCII | C | C | =c/omm + | | | | | omm=CTc/omm human_staff | omm | SQL_ASCII | C | C | gaussdb | omm | SQL_ASCII | C | C | (6 rows) -- Drop the human_staff database. gaussdb=# DROP DATABASE human_staff; DROP DATABASE

   For details about gsql meta-commands, see Meta-Command Reference.

Example 2

Obtain the help information.

gsql --help
gsql is the GaussDB Kernel interactive terminal.

Usage:
  gsql [OPTION]... [DBNAME [USERNAME]]

General options:
  -c, --command=COMMAND    run only single command (SQL or internal) and exit
  -d, --dbname=DBNAME      database name to connect to (default: "omm")
  -f, --file=FILENAME      execute commands from file, then exit
  -l, --list               list available databases, then exit
  -v, --set=, --variable=NAME=VALUE
                           set gsql variable NAME to VALUE
  -V, --version            output version information, then exit
  -X, --no-gsqlrc          do not read startup file (~/.gsqlrc)
  -1 ("one"), --single-transaction
                           execute command file as a single transaction
  -?, --help               show this help, then exit

Input and output options:
  -a, --echo-all           echo all input from script
  -e, --echo-queries       echo commands sent to server
  -E, --echo-hidden        display queries that internal commands generate
  -k, --with-key=KEY       the key for decrypting the encrypted file
  -L, --log-file=FILENAME  send session log to file
  -m, --maintenance        can connect to cluster during 2-pc transaction recovery
  -n, --no-libedit        disable enhanced command line editing (libedit)
  -o, --output=FILENAME    send query results to file (or |pipe)
  -q, --quiet              run quietly (no messages, only query output)
  -C, -C1, --enable-client-encryption=1
                           enable client encryption feature
  -C2, --enable-client-encryption=2
                           enable client sorting based client encryption feature
  -C3, --enable-client-encryption=3
                           enable Trusted Domain operation based on client encryption feature
  -s, --single-step        single-step mode (confirm each query)
  -S, --single-line        single-line mode (end of line terminates SQL command)
  -y, --slash-command      enable slash command to re-execute query in buffer

Output format options:
  -A, --no-align           unaligned table output mode
  -F, --field-separator=STRING
                           set field separator (default: "|")
  -H, --html               HTML table output mode
  -P, --pset=VAR[=ARG]     set printing option VAR to ARG (see \pset command)
  -R, --record-separator=STRING
                           set record separator (default: newline)
  -r                       if this parameter is set,use libedit
  -t, --tuples-only        print rows only
  -T, --table-attr=TEXT    set HTML table tag attributes (e.g., width, border)
  -x, --expanded           turn on expanded table output
  -z, --field-separator-zero
                           set field separator to zero byte
  -0, --record-separator-zero
                           set record separator to zero byte
  -2, --pipeline           use pipeline to pass the password, forbidden to use in terminal
                           must use with -c or -f

Connection options:
  -h, --host=HOSTNAME      database server host or socket directory (default: "/data/huawei/wisequery/perfadm_mppdb")
                           allow multi host IP address with comma separator, Use the
                           PGTARGETSESSIONATTRS(default: "primary") variable to select the
                           IP address to be connected.
                           (PGTARGETSESSIONATTRS can be {read-write|read-only|primary|
                            standby|prefer-standby|any})
  -p, --port=PORT          database server port (default: "5432")
  -U, --username=USERNAME  database user name (default: "omm")
  -W, --password=PASSWORD  the password of specified database user

For more information, type "\?" (for internal commands) or "\help" (for SQL
commands) from within gsql, or consult the gsql section in the GaussDB Kernel
documentation.