> Connect to clusters >

Connect via client shells

Connect to your YugabyteDB cluster from your desktop using the YugabyteDB ysqlsh and ycqlsh client shells installed on your computer. Because YugabyteDB is PostgreSQL-compatible, you can also use psql to connect.

You can download and install the YugabyteDB Client Shell and connect to your database by following the steps below for either YSQL or YCQL.

Before you can connect using a shell, you need to add your computer to an IP allow list for the cluster. Refer to Assign IP Allow Lists.

Note

You must add your computer to the cluster IP allow list before you can connect from a remote shell.

When connecting via Yugabyte Client Shell, ensure you are running the latest versions of the shells (Yugabyte Client 2.6 or later). See How do I connect to my cluster? in the FAQ for details.

Connect via Client Shell

To connect to a cluster using ysqlsh:

  1. On the Clusters tab, select a cluster.

  2. Click Connect.

  3. Click YugabyteDB Client Shell.

  4. Make sure you are running the latest version of the Yugabyte Client shell. If you have not installed Yugabyte Client on your computer, select your operating system and copy the command to install Yugabyte Client from the command line.

  5. Click Download CA Cert to download the root.crt certificate for TLS encryption, and install the certificate on your computer. If you are using Docker, copy the certificate to your Docker container.

  6. Copy the YSQL connection string.
    The connection string includes flags specifying the host (host), username (user), database (dbname), and TLS settings (sslmode and sslrootcert). The command specifies that the connection will use the CA certificate you installed on your computer. For information on using other SSL modes, refer to SSL modes in YSQL.


    Here's an example of the generated ysqlsh command:

    ./ysqlsh "host=740ce33e-4242-4242-a424-cc4242c4242b.aws.ybdb.io \
user=<DB USER> \
dbname=yugabyte \
sslmode=verify-full \
sslrootcert=<ROOT_CERT_PATH>"

  7. On your computer, change directories to the directory where you installed the client shell.

  8. Paste and run the command, replacing

    • <DB USER> with your database username.
    • yugabyte with the database name, if you're connecting to a database other than the default (yugabyte).
    • <ROOT_CERT_PATH> with the path to the root certificate on your computer.

The ysqlsh shell opens connected to the remote cluster.

ysqlsh (11.2-YB-2.6.1.0-b0)
Type "help" for help.

yugabyte=#

To connect to a cluster using ycqlsh:

  1. On the Clusters tab, select a cluster.

  2. Click Connect.

  3. Click YugabyteDB Client Shell.

  4. Make sure you are running the latest version of the Yugabyte Client shell. If you have not installed Yugabyte Client on your computer, select your operating system and copy the command to install Yugabyte Client from the command line.

  5. Click Download CA Cert to download the root.crt certificate for TLS encryption, and install the certificate on your computer. If you are using Docker, copy the certificate to your Docker container.

  6. Copy the YCQL connection string.
    The connection string includes the cluster host and port, with flags for the database username (-u), and TLS settings (--ssl). The command specifies that the connection will use the CA certificate you installed on your computer.


    Here's an example of the generated ycqlsh command:

    SSL_CERTFILE=<ROOT_CERT_PATH> \
./ycqlsh \
740ce33e-4242-4242-a424-cc4242c4242b.aws.ybdb.io 9042 \
-u <DB USER> \
--ssl

  7. On your computer, change directories to the directory where you installed the client shell.

  8. Paste and run the command, replacing

    • <ROOT_CERT_PATH> with the path to the root certificate on your computer.
    • <DB USER> with your database username.

The ycqlsh shell opens connected to the remote cluster.

Connected to local cluster at 35.236.85.97:12200.
[ycqlsh 5.0.1 | Cassandra 3.9-SNAPSHOT | CQL spec 3.4.2 | Native protocol v4]
Use HELP for help.
admin@ycqlsh>

Connect using psql

To connect using psql, first download the CA certificate for your cluster by clicking Connect, selecting YugabyteDB Client Shell, and clicking Download CA Cert. Then use the following connection string:

psql --host=<HOST_ADDRESS> --port=5433 \
--username=<DB USER> \
--dbname=yugabyte \
--set=sslmode=verify-full \
--set=sslrootcert=<ROOT_CERT_PATH>

Replace the following:

  • <HOST_ADDRESS> with the value for host as shown on the Settings tab for your cluster.
  • <DB USER> with your database username.
  • yugabyte with the database name, if you're connecting to a database other than the default (yugabyte).
  • <ROOT_CERT_PATH> with the path to the root certificate on your computer.

For information on using other SSL modes, refer to SSL modes in YSQL.

Connect using third party clients

Because YugabyteDB is PostgreSQL-compatible, you can use third party PostgreSQL clients to connect to your YugabyteDB clusters in Yugabyte Cloud. To create connections to your cluster in Yugabyte Cloud, follow the client's configuration steps for PostgreSQL, but use the value for host as shown on the Settings tab for your cluster, port 5433, and the username and password of a user with permissions for the cluster.

For detailed steps for configuring popular third party tools, see Third party tools. In that section, configuration steps are included for the following tools:

  • DBeaver
  • DbSchema
  • pgAdmin
  • SQL Workbench/J
  • TablePlus
  • Visual Studio Workbench
  • ysqlsh — Overview of the command line interface (CLI), syntax, and commands.
  • YSQL API — Reference for supported YSQL statements, data types, functions, and operators.
  • ycqlsh — Overview of the command line interface (CLI), syntax, and commands.
  • YCQL API — Reference for supported YCQL statements, data types, functions, and operators.

Next steps

Contact Us
Copyright © 2017-2022 Yugabyte, Inc. All rights reserved.