Explore YugabyteDB

The Explore documentation introduces you to YugabyteDB's features, often through examples.

Most examples demonstrating database features, such as API compatibility, can be run on a single-node universe either on your computer, using the free Sandbox universe (cluster) in YugabyteDB Aeon, or using a universe created via YugabyteDB Anywhere. More advanced scenarios use a multi-node deployment. Refer to Set up YugabyteDB universe for instructions on creating universes to run the examples.

Overview

The following table describes the YugabyteDB features you can explore, along with the setup required to run the examples (single- or multi-node universe):

Set up YugabyteDB universe

You can run examples using a universe set up on your local machine or in a cloud, assuming you have performed one of the following:

• Installed YugabyteDB.
• Created an account in YugabyteDB Aeon.
• Installed YugabyteDB Anywhere and configured it to run in AWS.

  Local
</a>

  YugabyteDB Aeon
</a>

  YugabyteDB Anywhere
</a>

To run the examples, you need to create a single- or multi-node universe.

Use the yugabyted utility to create and manage universes.

The following instructions show how to simulate a single- or multi-node universe on a single computer. To deploy an actual multi-zone universe using yugabyted, follow the instructions in Create a multi-zone cluster.

{{< tabpane text=true >}}

{{% tab header="Single-node universe" lang="Single-node universe" %}}

If a local universe is currently running, first destroy it.

You can create a single-node local universe with a replication factor (RF) of 1 by running the following command:

./bin/yugabyted start --advertise_address=127.0.0.1

Or, if you are running macOS Monterey, use the following command:

./bin/yugabyted start --advertise_address=127.0.0.1 \
                      --master_webserver_port=9999

To check the status of a running single-node universe, run the following command:

./bin/yugabyted status

For more information, refer to Quick Start.

{{% /tab %}}

{{% tab header="Multi-node universe" lang="Multi-node universe" %}}

{{<setup/local>}}

{{% /tab %}}

{{< /tabpane >}}

Connect to universes

To run the examples in your universe, you use either the ysqlsh or ycqlsh CLI to interact with YugabyteDB via the YSQL or YCQL API.

You can start ysqlsh as follows:

./bin/ysqlsh

ysqlsh (11.2-YB-{{<yb-version version="v2024.2">}}-b0)
Type "help" for help.

yugabyte=#

You can start ycqlsh as follows:

./bin/ycqlsh

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

To run the examples in YugabyteDB Aeon, create a single- or multi-node universe (which is referred to as cluster in YugabyteDB Aeon).

{{< tabpane text=true >}}

{{% tab header="Single-node cluster" lang="YBM Single" %}}

Examples requiring a single-node cluster can be run using the free Sandbox cluster.

If you haven't already created your sandbox cluster, log in to YugabyteDB Aeon, on the Clusters page click Add Cluster, and follow the instructions in the Create Cluster wizard.

{{% /tab %}}

{{% tab header="Multi-node cluster" lang="YBM Multi" %}}

Before you can create a multi-node cluster in YugabyteDB Aeon, you need to add your billing profile and payment method, or you can request a free trial.

To create a single region three-node cluster, refer to Create a single-region cluster. Set Fault tolerance to None and Nodes to 3.

{{% /tab %}}

{{< /tabpane >}}

Save your cluster credentials in a convenient location. You will use them to connect to your cluster.

Connect to your clusters

You can run Explore exercises in YugabyteDB Aeon using the Cloud Shell:

1. In YugabyteDB Aeon, on the Clusters page, select your cluster.
2. Click Connect.
3. Click Launch Cloud Shell.
4. Enter the user name from the cluster credentials you downloaded when you created the cluster.
5. Select the API to use (YSQL or YCQL) and click Confirm. The shell displays in a separate browser page. Cloud Shell can take up to 30 seconds to be ready.
6. Enter the password from the cluster credentials you downloaded when you created the cluster.

Note that if your Cloud Shell session is idle for more than 5 minutes, your browser may disconnect you. To resume, close the browser tab and connect again.

To run the examples, you need to create a single- or multi-node universe.

For instructions on creating a universe in YugabyteDB Anywhere, refer to Create a multi-zone universe.

Set up YB Workload Simulator

YB Workload Simulator is a Java application that simulates workloads against YugabyteDB and provides live metrics of latency and throughput from the application's point of view. Some Explore topics use the application to demonstrate features of YugabyteDB.

The application uses the YugabyteDB JDBC Smart Driver, which features universe- and topology-aware connection load balancing. The driver automatically balances application connections across the nodes in a universe, and re-balances connections when a node fails. For more information, see YB Workload Simulator.

Download

YB Workload Simulator requires Java 11 or later installed on your computer. {{% jdk-setup %}}

Download the YB Workload Simulator JAR file using the following command:

wget https://github.com/YugabyteDB-Samples/yb-workload-simulator/releases/download/v0.0.8/yb-workload-sim-0.0.8.jar

Use the application

  Local
</a>

  YugabyteDB Aeon
</a>

  YugabyteDB Anywhere
</a>

To connect the application to your cluster, ensure that you have downloaded the cluster SSL certificate and your computer is added to the IP allow list. Refer to Before you begin.

To start the application against a running YugabyteDB Aeon cluster, use the following command:

java -Dnode=<host name> \
    -Ddbname=<dbname> \
    -Ddbuser=<dbuser> \
    -Ddbpassword=<dbpassword> \
    -Dssl=true \
    -Dsslmode=verify-full \
    -Dsslrootcert=<path-to-cluster-certificate> \
    -jar ./yb-workload-sim-0.0.8.jar

• <host name> - The host name of your YugabyteDB cluster. For YugabyteDB Aeon, select your cluster on the Clusters page, and click Settings. The host is displayed under Connection Parameters.
• <dbname> - The name of the database you are connecting to (the default is yugabyte).
• <dbuser> and <dbpassword> - The username and password for the YugabyteDB database. Use the credentials in the credentials file you downloaded when you created your cluster.

• <path-to-cluster-certificate> with the path to the cluster certificate on your computer.

  </div> <div id="localworkload" class="tab-pane fade show active" role="tabpanel" aria-labelledby="local-tab">

To start the application against a running local universe, use the following command:

java -jar \
    -Dnode=127.0.0.1 \
    ./yb-workload-sim-0.0.8.jar

The -Dnode flag specifies the IP address of the node to which to connect.

The -Dspring.datasource flag enables topology-aware load balancing for the application connections. If you created a universe using different zones, replace the zones with the corresponding zones in your universe, comma-separated, in the format cloud.region.zone.

To start the application against a running YugabyteDB Anywhere universe, use the following command from a local terminal:

java -Dnode=<node_ip> \
      -Ddbname=<dbname> \
      -Ddbuser=<dbuser> \
      -Ddbpassword=<dbpassword> \
      -Dspring.datasource.hikari.data-source-properties.topologyKeys=<cloud.region.zone> \
      -jar ./yb-workload-sim-0.0.8.jar

Replace the following:

• <node_ip> - The IP address of the node in your YugabyteDB Anywhere universe. You can find this information by navigating to Universes > UniverseName > Nodes in YugabyteDB Anywhere.

• <dbname> - The name of the database you are connecting to (the default is yugabyte).

• <dbuser> and <dbpassword> - The user name and password for the YugabyteDB database. <!-- - `<port>` - 5433. -->

• <cloud.region.zone> - The zones in your universe, comma-separated, in the format cloud.region.zone, to be used as topology keys for topology-aware load balancing. Node details are displayed in Universes > UniverseName > Nodes. For example, to add topology keys for a single-region multi-zone universe, you would enter the following:

  shCopy

  -Dspring.datasource.hikari.data-source-properties.topologyKeys=aws.us-east-1.us-east-1a,aws.us-east-1.us-east-1b,aws.us-east-1.us-east-1c
  

To view the application UI, navigate to http://<machine_ip_or_dns>:8080 (for example, http://localhost:8080).

Start a read and write workload

You can start a workload that performs read and write operations across all the nodes of the universe as follows:

1. In the application UI, click the hamburger icon at the top of the page beside Active Workloads for Generic.
2. Select Usable Operations.
3. Under Create Tables, click Run Create Tables Workload to add tables to the database.
4. Under Seed Data, click Run Seed Data Workload to add data to the tables.
5. Under Simulation, select the Include new Inserts option, and click Run Simulation Workload.
6. Click Close.

The Latency and Throughput charts show the workload running on the universe.