Run the examples

Set up YugabyteDB to run Explore examples

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

Set up YugabyteDB universe

You can run examples using a universe, assuming you have Installed YugabyteDB Anywhere and configured it to run in AWS.

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.

The application is used to demonstrate the following Explore topics:

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 installers for Linux and macOS can be downloaded from Oracle, Adoptium (OpenJDK), or Azul Systems (OpenJDK). Homebrew users on macOS can install using brew install openjdk.

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

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

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