Set up clusters for running Explore examples

{{< tip title="Docs MCP Server" >}} Developing with YugabyteDB? Access the YugabyteDB Docs AI from your IDE or CLI. See Docs MCP Server. {{< /tip >}}

Use the following instructions to set up universes for running the examples in Explore.

  Local
</a>

  YugabyteDB Aeon
</a>

  YugabyteDB Anywhere
</a>

Set up YugabyteDB cluster

You can run examples using a cluster on YugabyteDB Aeon, assuming you have Created an account in YugabyteDB Aeon.

Sandbox cluster

Most examples in Explore can be run using the free Sandbox cluster.

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

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

Multi-node universe

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.

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.

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.

The application is used to demonstrate the following Explore topics:

• Horizontal scalability
• Resiliency (this example is not available for Aeon)
• Multi-region deployment

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

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.

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.