Connect via client shells

Connect to YugabyteDB Aeon databases from your desktop

Connect to your YugabyteDB cluster database from your desktop using the YugabyteDB client shells installed on your computer.

Client API Description
ysqlsh YSQL SQL shell for interacting with YugabyteDB using PostgreSQL-compatible YSQL API.
ycqlsh YCQL CQL shell for interacting with YugabyteDB using Cassandra-compatible YCQL API.

Because YugabyteDB is compatible with PostgreSQL and Cassandra, you can also use psql and third-party tools to connect.

Prerequisites

To connect a desktop client to a YugabyteDB Aeon cluster, you need to do the following:

  • Configure network access
  • Download the cluster certificate

Network access

Before you can connect using a shell or other client, you need to add your computer to the cluster IP allow list.

By default, clusters deployed in a VPC do not expose any publicly-accessible IP addresses. To add public IP addresses, enable Public Access on the cluster Settings > Network Access tab. Alternatively, use the Cloud shell instead.

For more information, refer to IP allow list.

Cluster certificate

YugabyteDB Aeon clusters have TLS/SSL (encryption in-transit) enabled. You need to download the cluster certificate to your computer.

For information on SSL in YugabyteDB Aeon, refer to Encryption in transit.

Connect using a client shell

Use the ysqlsh and ycqlsh shells to connect to and interact with YugabyteDB using the YSQL and YCQL APIs respectively. You can download and install the YugabyteDB client shells and connect to your database using the following steps for either YSQL or YCQL.

To connect to a cluster using ysqlsh:

  1. On the Clusters tab, select a cluster.

  2. Click Connect.

  3. Click YugabyteDB Client Shell.

  4. If you have not installed the YugabyteDB clients on your computer, select your operating system and copy the command to install the clients 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. If your cluster is deployed in a VPC, choose Private Address if you are connecting from a peered VPC. Otherwise, choose Public Address (only available if you have enabled Public Access for the cluster; not recommended for production).

  7. 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>"

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

  9. 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.

  10. Enter your password when prompted.

The ysqlsh shell opens connected to the remote cluster.

ysqlsh (11.2-YB-{{<yb-version version="preview">}}-b0)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
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. If you have not installed the YugabyteDB clients on your computer, select your operating system and copy the command to install the clients 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. If your cluster is deployed in a VPC, choose Private Address if you are connecting from a peered VPC. Otherwise, choose Public Address (only available if you have enabled Public Access for the cluster; not recommended for production).

  7. 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

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

  9. 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 under Connection Parameters on the Settings > Infrastructure 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 compatible with PostgreSQL and Cassandra, you can use third-party clients to connect to your YugabyteDB clusters in YugabyteDB Aeon.

To connect, follow the client's configuration steps for PostgreSQL or Cassandra, and use the following values:

  • host as shown under Connection Parameters on the Settings > Infrastructure tab for your cluster.
  • port 5433 for YSQL, 9042 for YCQL.
  • database name; the default YSQL database is yugabyte.
  • username and password of a user with permissions for the database; the default user is admin.

Your client may also require the use of the cluster's certificate. Refer to Download the cluster certificate.

For detailed steps for configuring popular third party tools, see GUI clients.

Next steps