ybsql Connections

This section describes how to connect to a database with ybsql.

Syntax Summary

ybsql [ connection_options ] [ options ] 

The order of the general options and connection options may be reversed in the command.

Connection Options

[ -h | --host hostname ] 
[ -p | --port portnumber ] 
[ -d | --dbname dbname [ -U | --username username ] ]
[ -W | --password ]
[ -w | --no-password ]
-d, --dbname
Name of the database for the connection. Alternatively, you can specify dbname by itself as the first argument on the command line. For example, all of the following syntax variations are valid, where premdb is the database name:
ybsql premdb
ybsql -d premdb
ybsql --dbname premdb
-U, --username
Name of the database user for the connection. Alternatively, you can specify username by itself as long as the database name precedes it. For example, all of the following syntax variations are valid, where bobr is the username:
ybsql -U bobr premdb
ybsql --username bobr premdb
ybsql premdb bobr
-W, --password
Prompt for the user's password before connecting. Regardless of this option, ybsql prompts for the password automatically when the server requires password authentication. This option remains in effect for the entire session and affects the use of any \connect commands.
-w, --no-password
Do not prompt for the user's password. If the server requires password authentication and a password is not set with the YBPASSWORD environment variable, the connection fails. This option may be useful for non-interactive batch jobs and scripts. It remains in effect for the entire session and affects the use of any \connect commands.
-h, --host
Host name of the appliance.
-p, --port
Port number for the connection (5432 by default).

Environment Variables

You can use the following environment variables to set connection parameters for ybsql connections:
Environmental Variable ybsql Option Description Example
YBDATABASE -d or --dbname Destination database name. Default: yellowbrick

See also SQL Identifiers.

export YBDATABASE=premdb
YBHOST -h or --host Destination server host name. Default: localhost
export YBHOST=test.ybsystem.io
YBPASSWORD -W or --password Interactive prompt for the database user's password. No default.
export YBPASSWORD=********
YBPORT Destination server port number. Default: 5432
export YBPORT=5433
YBSSLMODE Attempt an SSL connection and verify that the server certificate is issued by a trusted CA. export YBSSLMODE=verify-ca
YBUSER -U or --username Database login username. No default.
export YBUSER=bobr

Connecting with a Secure Password

You can use the ybsql \password command to reset a password for a user securely. Passwords set or changed with this command are not exposed in clear text or saved to any log files. For example:
premdb=# create user jamesbond;
CREATE ROLE
premdb=# \password jamesbond
Enter new password: 
Enter it again: 
...
premdb=# \c premdb jamesbond
Password for user jamesbond: 
You are now connected to database "premdb" as user "jamesbond".
...
CAUTION: If you create and update unencrypted passwords with CREATE ROLE and ALTER ROLE commands, passwords are transmitted in clear text and may appear in log messages.