Explore YugabyteDB
For production, use the latest stable version (v2024.1).
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.0.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 isyugabyte
).<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 isyugabyte
). -
<dbuser>
and<dbpassword>
- The user name and password for the YugabyteDB database. -
<cloud.region.zone>
- The zones in your universe, comma-separated, in the formatcloud.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.