Connect to a YugabyteDB Anywhere universe

Connect to your YugabyteDB database from your desktop using the YugabyteDB ysqlsh and ycqlsh client shells. Because YugabyteDB is compatible with PostgreSQL and Cassandra, you can also use psql and third-party tools to connect.

You can connect to the database on a universe in the following ways:

• Use SSH to tunnel to one of the universe nodes, and run ysqlsh or ycqlsh on the node.
• Download and run the client shells from your desktop.

Download the universe certificate

If the universe uses encryption in transit, to connect you need to first download the universe TLS root certificate. Do the following:

1. Navigate to Configs > Security > Encryption in Transit.

2. Find the certificate for your universe in the list and click Actions and download the certificate.

For more information on connecting to TLS-enabled universes, refer to Connect to clusters.

Connect to a universe node

The YugabyteDB shells are installed in the tserver/bin directory on each YB-TServer of a YugabyteDB universe.

Access your YugabyteDB Anywhere instance

To connect to a universe node, you first need to be signed on to the machine where YugabyteDB Anywhere is installed, or connected via SSH.

To SSH to a YugabyteDB Anywhere instance hosted on the cloud provider, you enter the following:

ssh -i <path_to_secret> username@<platform_machine_external_ip>

For example, for an AWS instance, you can SSH using a command similar to the following:

ssh -i ~/.yugabyte/yb-dev-aws-2.pem [email protected]

If your instance is on Kubernetes, use kubectl commands to connect. For example:

gcloud container clusters get-credentials --region us-west1 itest-release --project yugabyte
kubectl exec -it yw-ns-kvik-id7973-20230213-031611-yugaware-0 -n yw-ns-kvik-id7973-20230213-031611 -c yugaware -- bash

Connect to a node

To run a shell from a universe node, do the following:

1. In YugabyteDB Anywhere, navigate to your universe and select the Nodes tab.

2. Determine the node to which you wish to connect and click Actions > Connect.

3. Copy the SSH command displayed in the Access your node dialog shown in the following illustration:

4. From the machine where YugabyteDB Anywhere is installed, run the command you copied. For example:

   sh.outputCopy

   sudo ssh -i /opt/yugabyte/yugaware/data/keys/f000ad00-aafe-4a67-bd1f-34bdaf3bee00/yb-dev-yugabyte-google-provider_f033ad00-aafe-4a00-bd1f-34bdaf3bee00-key.pem -ostricthostkeychecking=no -p 22 yugabyte@<node_ip_address>
   
   Are you sure you want to continue connecting (yes/no)? yes
   [ec2-user@yb-dev-helloworld1-n1 ~]$
   

5. On the node, navigate to the tserver/bin directory:

   shCopy

   cd /home/yugabyte/tserver/bin
   

6. Run ysqlsh or ycqlsh as follows:

   shCopy

   ./ysqlsh -h <node_ip_address>
   

   shCopy

   ./ycqlsh <node_ip_address>
   

Connect from your desktop

Prerequisites

• If you are using a Yugabyte client shell, ensure you are running the latest versions of the shells (Yugabyte Client 2.6 or later).

  You can download using the following command on Linux or macOS:

  shCopy

  $ curl -sSL https://downloads.yugabyte.com/get_clients.sh | bash
  

  Windows client shells require Docker. For example:

  shCopy

  docker run -it yugabytedb/yugabyte-client ysqlsh -h <hostname> -p <port>
  

• If your universe has TLS/SSL (encryption in-transit) enabled, you need to download the certificate to your computer.

• The host address of an endpoint on your universe.

  To view your universe endpoints, navigate to your universe and click Connect.

Connect using a client shell

Use the ysqlsh, ycqlsh, and psql shells to connect to and interact with YugabyteDB using the YSQL and YCQL APIs.

To connect using ysqlsh, use the following connection string:

./ysqlsh "host=<HOST_ADDRESS> \
user=<DB USER> \
dbname=yugabyte \
sslmode=verify-full \
sslrootcert=<ROOT_CERT_PATH>"

Replace the following:

• <HOST_ADDRESS> with the IP address of an endpoint on your universe.
• <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.

To load sample data and explore an example using ysqlsh, follow the instructions in Install the Retail Analytics sample database.

To connect using ycqlsh, use the following connection string:

SSL_CERTFILE=<ROOT_CERT_PATH> \
./ycqlsh \
<HOST_ADDRESS> 9042 \
-u <DB USER> \
--ssl

Replace the following:

• <HOST_ADDRESS> with the IP address of an endpoint on your universe.

• <DB USER> with your database username.

• <ROOT_CERT_PATH> with the path to the root certificate on your computer.

  </div> <div id="psql" class="tab-pane fade" role="tabpanel" aria-labelledby="psql-tab">

To connect using psql, 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 IP address of an endpoint on your universe.

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

  </div>

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 address of an endpoint on your universe.
• 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 admin user is yugabyte (YSQL) or cassandra (YCQL).

Your client may also require the use of the universe certificate.

For information on using popular third-party tools with YugabyteDB, see GUI clients.

Run workloads

YugabyteDB Anywhere includes a number of sample applications provided in Docker containers.

To run sample applications on your universe, do the following:

1. Connect to a universe node.

2. Navigate to your universe and click Actions > Run Sample Apps to open the Run Sample Apps dialog shown in the following illustration:

3. Run the suggested Docker command in your SSH session on the node.

The Metrics tab of the universe allows you to see the metrics graphs, where server-side metrics tally with the client-side metrics reported by the load tester.

You can also view metrics at a per-node level.

You can stop the load tester as follows:

• Find the container by executing the following command:

  shellCopy

  user@yugaware-1:~$ sudo docker container ls | grep "yugabytedb/yb-sample-apps"
  

  Expect an output similar to the following:

  outputCopy

  <container_id> yugabytedb/yb-sample-apps "/usr/bin/java -jar …" 17 seconds ago Up 16 seconds                                                                                                            jovial_morse
  

  For example, if the container ID is ac144a49d57d, you would see the following output:

  outputCopy

  ac144a49d57d yugabytedb/yb-sample-apps "/usr/bin/java -jar …" 17 seconds ago Up 16 seconds                                                                                                            jovial_morse
  

• Stop the container by executing the following command:

  shellCopy

  user@yugaware-1:~$ sudo docker container stop <container_id>
  

  Expect the following output:

  outputCopy

  <container_id>
  

  For example, for a container with ID ac144a49d57d, you would need to execute the following command:

  shellCopy

  user@yugaware-1:~$ sudo docker container stop ac144a49d57d
  

  You would see the following output:

  outputCopy

  ac144a49d57d
  

Examine data

Connect to the YCQL service by executing the following command:

/home/yugabyte/tserver/bin/ycqlsh <ip_address_of_the_node>

You can view the table schema and the data, as follows:

ycqlsh> DESCRIBE ybdemo_keyspace.cassandrakeyvalue;

CREATE TABLE ybdemo_keyspace.cassandrakeyvalue (
  k text PRIMARY KEY,
  v blob
) WITH default_time_to_live = 0;

ycqlsh> SELECT * FROM ybdemo_keyspace.cassandrakeyvalue LIMIT 5;

 k          | v
------------+-----------------------------------------
 key:101323 | 0x4276616c3a3130313332336be1dd6597e2...
 key:159968 | 0x4276616c3a3135393936381ed99587c08f...
  key:24879 | 0x4276616c3a3234383739054071b34c3fb6...
 key:294799 | 0x4276616c3a3239343739398b312748e80e...
 key:297045 | 0x4276616c3a32393730343525764eedee94...

(5 rows)

Learn more

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