Explore YugabyteDB

Learn about YugabyteDB features, with examples

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):

Section	Purpose	Universe setup
SQL features	Learn about YugabyteDB's compatibility with PostgreSQL, including data types, queries, expressions, operators, extensions, and more.	Single-node local/cloud
YCQL features	Learn about YugabyteDB's Apache Cassandra-compatible YCQL language features.	Single-node local/cloud
Going beyond SQL	Learn about YugabyteDB exclusive features such as follower reads, tablespaces, built-in connection pooling, and more.	Multi-node local
Resiliency	Learn how YugabyteDB achieves resiliency when a node fails.	Multi-node local
Horizontal scalability	See how YugabyteDB handles loads while dynamically adding or removing nodes.	Multi-node local
Transactions	Understand how distributed transactions and isolation levels work in YugabyteDB.	Single-node local/cloud
Colocation	YugabyteDB allows for closely related data to reside together via colocation. Learn how to co-locate tables.	Single-node local/cloud
Multi-region deployments	Learn about the different multi-region topologies that you can deploy using YugabyteDB.	Multi-node local
Query tuning	Learn about the tools available to identify and optimize queries in YSQL.	Single-node local/cloud
Cluster management	Learn how to roll back database changes to a specific point in time using point in time recovery.	Single-node local
Change data capture	Learn about YugabyteDB support for streaming data to Kafka.	N/A
Security	Learn how to secure data in YugabyteDB, using authentication, authorization (RBAC), encryption, and more.	Single-node local/cloud
Observability	Export metrics into Prometheus and create dashboards using Grafana.	Multi-node local

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.

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.

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.

Set up a local cluster

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

Start a local three-node universe with an RF of 3 by first creating a single node, as follows:

./bin/yugabyted start \
                --advertise_address=127.0.0.1 \
                --base_dir=${HOME}/var/node1 \
                --cloud_location=aws.us-east-2.us-east-2a

On macOS, the additional nodes need loopback addresses configured, as follows:

sudo ifconfig lo0 alias 127.0.0.2
sudo ifconfig lo0 alias 127.0.0.3

Next, join more nodes with the previous node as needed. yugabyted automatically applies a replication factor of 3 when a third node is added.

Start the second node as follows:

./bin/yugabyted start \
                --advertise_address=127.0.0.2 \
                --base_dir=${HOME}/var/node2 \
                --cloud_location=aws.us-east-2.us-east-2b \
                --join=127.0.0.1

Start the third node as follows:

./bin/yugabyted start \
                --advertise_address=127.0.0.3 \
                --base_dir=${HOME}/var/node3 \
                --cloud_location=aws.us-east-2.us-east-2c \
                --join=127.0.0.1

After starting the yugabyted processes on all the nodes, configure the data placement constraint of the universe, as follows:

./bin/yugabyted configure data_placement --base_dir=${HOME}/var/node1 --fault_tolerance=zone

This command can be executed on any node where you already started YugabyteDB.

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

./bin/yugabyted status --base_dir=${HOME}/var/node1

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

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.

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:

In YugabyteDB Aeon, on the Clusters page, select your cluster.
Click Connect.
Click Launch Cloud Shell.
Enter the user name from the cluster credentials you downloaded when you created the cluster.
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.
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 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 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 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.
<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.