Command Reference

For details about gsql parameters, see Table Common parameters, Table Input and output parameters, Table Output format parameters, and Table Connection parameters.

Table 1 Common parameters

Parameter	Description	Value Range
-c, --command=COMMAND	Specifies that gsql is to run a string command and then exit.	-
-d, --dbname=DBNAME	Specifies the name of the database to connect to. In addition, gsql allows you to use extended database names, that is, connection strings in the format of postgres[ql]://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&…]or [key=value] [...] as database names. gsql parses connection information from the connection strings and preferentially uses the information.	Character string
-f, --file=FILENAME	Specifies that files are used as the command source instead of interactively-entered commands. After the files are processed, gsql exits. If FILENAME is - (hyphen), then standard input is read. NOTE: Environment scenario: one primary and one standby (8 CPUs and 32 GB memory) Test result: It takes about 8 minutes and 21 seconds to read a 200 MB data file. It takes about 18 minutes and 41 seconds to read a 500 MB data file. Suggestion: The file read time increases with the file data volume. If the file size is too large, the file needs to be read again when an exception occurs. In addition, the I/O of the system OS will be overloaded. It is recommended that the file size be about 500 MB.	An absolute path or relative path that meets the OS path naming convention
-l, --list	Lists all available databases and then exits.	-
-v, --set, --variable=NAME=VALUE	Sets variable NAME to VALUE. For details about variable examples and descriptions, see variables.	-
-X, --no-gsqlrc	Does not read the startup file (neither the system-wide gsqlrc file nor the user's ~/.gsqlrc file). NOTE: The startup file is ~/.gsqlrc by default or it can be specified by the environment variable PSQLRC.	-
-1 ("one"), --single-transaction	When gsql uses the -f parameter to execute a script, START TRANSACTION and COMMIT are added to the start and end of the script, respectively, so that the script is executed as one transaction. This ensures that the script is executed successfully. If the script cannot be executed, the script is invalid. NOTE: If the script has used START TRANSACTION, COMMIT, or ROLLBACK, this parameter is invalid.	-
-?, --help	Displays help information about gsql command parameters, and exits.	-
-V, --version	Prints the gsql version and exits.	-
-C, --enable-client-encryption	When -C is used to connect to a local or remote database, you can use this option to enable the encrypted database function.	-

Table 2 Input and output parameters

Parameter	Description	Value Range
-a, --echo-all	Prints all input lines to standard output as they are read. CAUTION: When this parameter is used in some SQL statements, the sensitive information, such as user password, may be disclosed. Use this parameter with caution.	-
-e, --echo-queries	Displays all SQL commands sent to the server to the standard output as well. CAUTION: When this parameter is used in some SQL statements, the sensitive information, such as user password, may be disclosed. Use this parameter with caution.	-
-E, --echo-hidden	Echoes the actual queries generated by \d and other backslash commands.	-
-k, --with-key=KEY	Uses gsql to decrypt imported encrypted files. NOTICE: - For key characters, such as the single quotation mark (') or double quotation mark (") in shell commands, Linux shell checks whether the input single quotation mark (') or double quotation mark (") matches. If no match is found, Linux shell does not enter the gsql program until input is complete. - Stored procedures and functions cannot be decrypted and imported.	-
-L, --log-file=FILENAME	Writes normal output source and all query output into the FILENAME file. CAUTION: - When this parameter is used in some SQL statements, the sensitive information, such as user password, may be disclosed. Use this parameter with caution. - This parameter retains only the query result in the corresponding file, so that the result can be easily found and parsed by other invokers (for example, automatic O&M scripts). Logs about gsql operations are not retained.	An absolute path or relative path that meets the OS path naming convention
-m, --maintenance	Allows MogDB to be connected during two-phase transaction recovery. NOTE: The parameter is for engineers only. When this parameter is used, gsql can be connected to the standby server to check data consistency between the primary server and standby server.	-
-n, --no-libedit	Closes command line editing.	-
-o, --output=FILENAME	Puts all query output into the FILENAME file.	An absolute path or relative path that meets the OS path naming convention
-q, --quiet	Indicates the quiet mode and no additional information will be printed.	By default, gsql displays various information.
-s, --single-step	Runs in single-step mode. It indicates that the user is prompted before each command is sent to the server. This option can be also used for canceling execution. Use this option to debug scripts. CAUTION: When this parameter is used in some SQL statements, the sensitive information, such as user password, may be disclosed. Use this parameter with caution.	-
-S, --single-line	Runs in single-line mode where a line break terminates an SQL command, as a semicolon does.	-

Table 3 Output format parameters

Parameter	Description	Value Range
-A, --no-align	Switches to unaligned output mode.	The default output mode is aligned.
-F, --field-separator=STRING	Specifies the field separator. The default is the vertical bar (|).	-
-H, --html	Turns on the HTML tabular output.	-
-P, --pset=VAR[=ARG]	Specifies the print option in the \pset format in the command line. NOTE: The equal sign (=), instead of the space, is used here to separate the name and value. For example, enter -P format=latex to set the output format to LaTeX.	-
-R, --record-separator=STRING	Sets the record separator.	-
-r	Enables the function of recording historical client operations.	This function is disabled by default.
-t, --tuples-only	Prints only tuples.	-
-T, --table-attr=TEXT	Specifies options to be placed within the HTML table tag. Use this parameter with the -H,-html parameter to specify the output to the HTML format.	-
-x, --expanded	Turns on the expanded table formatting mode.	-
-z, --field-separator-zero	Sets the field separator in the unaligned output mode to be blank. Use this parameter with the -A, -no-align parameter to switch to unaligned output mode.	-
-0, --record-separator-zero	Sets the record separator in the unaligned output mode to be blank. Use this parameter with the -A, -no-align parameter to switch to unaligned output mode.	-
-2, –pipeline	Uses a pipe to transmit the password. This parameter cannot be used on devices and must be used together with the -c or -f parameter.	-
-g,	Prints all SQL statements from a file.	-

Table 4 Connection parameters

Parameter	Description	Value Range
-h, --host=HOSTNAME	Specifies the host name of the machine on which the server is running or the directory for the Unix-domain socket.	If the host name is omitted, gsql connects to the server of the local host over the Unix domain socket or over TCP/IP to connect to local host without the Unix domain socket.
-p, --port=PORT	Specifies the port number of the database server. You can modify the default port number using the -p, -port=PORT parameter.	The default value is 15400.
-U, --username=USERNAME	Specifies the user that connects to the database. NOTE: - If this parameter is specified, you also need to enter your password for identity authentication when connecting to the database. You can enter the password interactively or use the -W parameter to specify a password. - To connect to a database, add an escape character before any dollar sign ($) in the user name.	A character string. The default user is the current user that operates the system.
-W, --password=PASSWORD	Specifies the password when the -U parameter is used to connect to a remote database. NOTE: When the server where the primary database node is located connects to the local primary database node, the trust connection is used by default and this parameter is ignored. To connect to a database. If this parameter is not specified but database connection requires your password, you will be prompted to enter your password in interactive mode. The maximum length of the password is 999 bytes, which is restricted by the maximum value of the GUC parameter password_max_length.	The password must meet the complexity requirement.