Quick start

Create a local cluster on a single host

The local cluster setup on a single host is intended for development and learning. For production deployment, performance benchmarking, or deploying a true multi-node on multi-host setup, see Deploy YugabyteDB.

Install YugabyteDB

Installing YugabyteDB involves completing prerequisites and them performing the actual installation.

Note that the Docker option to run local clusters is recommended only for advanced Docker users. This is due to the fact that running stateful applications such as YugabyteDB in Docker is more complex and error-prone than running stateless applications.

Prerequisites

Before installing YugabyteDB, ensure that you have the Docker runtime installed on your localhost. To download and install Docker, select one of the following environments:

Docker for Mac

Docker for CentOS

Docker for Ubuntu

Docker for Debian

Docker for Windows

Install

Pull the YugabyteDB container by executing the following command:

docker pull yugabytedb/yugabyte:2.15.1.0-b175

Create a local cluster

To create a 1-node cluster with a replication factor (RF) of 1, run the following command:

docker run -d --name yugabyte  -p7000:7000 -p9000:9000 -p5433:5433 -p9042:9042\
 yugabytedb/yugabyte:latest bin/yugabyted start\
 --daemon=false

In the preceding docker run command, the data stored in YugabyteDB does not persist across container restarts. To make YugabyteDB persist data across restarts, you can add a volume mount option to the docker run command, as follows:

  • Create a ~/yb_data directory by executing the following command:

    mkdir ~/yb_data
    
  • Run Docker with the volume mount option by executing the following command:

    docker run -d --name yugabyte \
             -p7000:7000 -p9000:9000 -p5433:5433 -p9042:9042 \
             -v ~/yb_data:/home/yugabyte/yb_data \
             yugabytedb/yugabyte:latest bin/yugabyted start \
             --base_dir=/home/yugabyte/yb_data --daemon=false
    

Clients can now connect to the YSQL and YCQL APIs at http://localhost:5433 and http://localhost:9042 respectively.

Check cluster status

Run the following command to check the cluster status:

docker ps
CONTAINER ID        IMAGE                 COMMAND                  CREATED             STATUS              PORTS                                                                                                                                                                     NAMES
5088ca718f70        yugabytedb/yugabyte   "bin/yugabyted start…"   46 seconds ago      Up 44 seconds       0.0.0.0:5433->5433/tcp, 6379/tcp, 7100/tcp, 0.0.0.0:7000->7000/tcp, 0.0.0.0:9000->9000/tcp, 7200/tcp, 9100/tcp, 10100/tcp, 11000/tcp, 0.0.0.0:9042->9042/tcp, 12000/tcp   yugabyte

Check cluster status with Admin UI

The cluster you have created consists of two processes: YB-Master which keeps track of various metadata (list of tables, users, roles, permissions, and so on) and YB-TServer which is responsible for the actual end user requests for data updates and queries.

Each of the processes exposes its own Admin UI that can be used to check the status of the corresponding process, as well as perform certain administrative operations. The yb-master Admin UI is available at http://localhost:7000 and the yb-tserver Admin UI is available at http://localhost:9000. To avoid port conflicts, you should make sure other processes on your machine do not have these ports mapped to localhost.

Overview and YB-Master status

The following illustration shows the YB-Master home page with a cluster with a replication factor of 1, a single node, and no tables. The YugabyteDB version is also displayed.

master-home

The Masters section shows the 1 YB-Master along with its corresponding cloud, region, and zone placement.

YB-TServer status

Click See all nodes to open the Tablet Servers page that lists the YB-TServer along with the time since it last connected to the YB-Master using regular heartbeats, as per the following illustration:

master-home

Connect to the database

Using the YugabyteDB SQL shell, ysqlsh, you can connect to your cluster and interact with it using distributed SQL. ysqlsh is installed with YugabyteDB and is located in the bin directory of the YugabyteDB home directory.

To open the YSQL shell, run ysqlsh.

$ docker exec -it yugabyte /home/yugabyte/bin/ysqlsh --echo-queries
ysqlsh (11.2-YB-2.1.0.0-b0)
Type "help" for help.

yugabyte=#

To load sample data and explore an example using ysqlsh, refer to Retail Analytics.

Build a Java application

Prerequisites

Before building a Java application, perform the following:

  • While YugabyteDB is running, use the yb-ctl utility to create a universe with a 3-node RF-3 cluster with some fictitious geo-locations assigned, as follows:

    cd <path-to-yugabytedb-installation>
    
    ./bin/yb-ctl create --rf 3 --placement_info "aws.us-west.us-west-2a,aws.us-west.us-west-2a,aws.us-west.us-west-2b"
    
  • Ensure that Java Development Kit (JDK) 1.8 or later is installed. JDK installers can be downloaded from OpenJDK.

  • Ensure that Apache Maven 3.3 or later is installed.

Create and configure the Java project

Perform the following to create a sample Java project:

  1. Create a project called DriverDemo, as follows:

    mvn archetype:generate \
        -DgroupId=com.yugabyte \
        -DartifactId=DriverDemo \
        -DarchetypeArtifactId=maven-archetype-quickstart \
        -DinteractiveMode=false
    
    cd DriverDemo
    
  2. Open the pom.xml file in a text editor and add the following below the <url> element:

    <properties>
      <maven.compiler.source>1.8</maven.compiler.source>
      <maven.compiler.target>1.8</maven.compiler.target>
    </properties>
    
  3. Add the following dependencies for the driver HikariPool in the <dependencies> element in pom.xml:

    <dependency>
      <groupId>com.yugabyte</groupId>
      <artifactId>jdbc-yugabytedb</artifactId>
      <version>42.3.0</version>
    </dependency>
    
    <!-- https://mvnrepository.com/artifact/com.zaxxer/HikariCP -->
    <dependency>
      <groupId>com.zaxxer</groupId>
      <artifactId>HikariCP</artifactId>
      <version>5.0.0</version>
    </dependency>
    
  4. Save and close the pom.xml file.

  5. Install the added dependency by executing the following command:

    mvn install
    

Create a sample Java application

The following steps demonstrate how to create two Java applications, UniformLoadBalance and TopologyAwareLoadBalance. In each, you can create connections in one of two ways: using the DriverManager.getConnection() API or using YBClusterAwareDataSource and HikariPool. Both approaches are described.

Uniform load balancing

  1. Create a file called ./src/main/java/com/yugabyte/UniformLoadBalanceApp.java by executing the following command:

    touch ./src/main/java/com/yugabyte/UniformLoadBalanceApp.java
    
  2. Paste the following into UniformLoadBalanceApp.java:

    package com.yugabyte;
    
    import com.zaxxer.hikari.HikariConfig;
    import com.zaxxer.hikari.HikariDataSource;
    
    import java.sql.Connection;
    import java.sql.DriverManager;
    import java.sql.SQLException;
    import java.util.ArrayList;
    import java.util.List;
    import java.util.Properties;
    import java.util.Scanner;
    
    public class UniformLoadBalanceApp {
    
      public static void main(String[] args) {
        makeConnectionUsingDriverManager();
        makeConnectionUsingYbClusterAwareDataSource();
    
        System.out.println("Execution of Uniform Load Balance Java App complete!!");
      }
    
      public static void makeConnectionUsingDriverManager() {
        // List to store the connections so that they can be closed at the end
        List<Connection> connectionList = new ArrayList<>();
    
        System.out.println("Lets create 6 connections using DriverManager");
    
        String yburl = "jdbc:yugabytedb://127.0.0.1:5433/yugabyte?user=yugabyte&password=yugabyte&load-balance=true";
    
        try {
          for(int i=0; i<6; i++) {
            Connection connection = DriverManager.getConnection(yburl);
            connectionList.add(connection);
          }
    
          System.out.println("You can verify the load balancing by visiting http://<host>:13000/rpcz as discussed before");
          System.out.println("Enter a integer to continue once verified:");
          int x = new Scanner(System.in).nextInt();
    
          System.out.println("Closing the connections!!");
          for(Connection connection : connectionList) {
             connection.close();
          }
        }
        catch (SQLException exception) {
          exception.printStackTrace();
        }
      }
    
      public static void makeConnectionUsingYbClusterAwareDataSource() {
        System.out.println("Now, Lets create 10 connections using YbClusterAwareDataSource and Hikari Pool");
    
        Properties poolProperties = new Properties();
        poolProperties.setProperty("dataSourceClassName", "com.yugabyte.ysql.YBClusterAwareDataSource");
        // The pool will create  10 connections to the servers
        poolProperties.setProperty("maximumPoolSize", String.valueOf(10));
        poolProperties.setProperty("dataSource.serverName", "127.0.0.1");
        poolProperties.setProperty("dataSource.portNumber", "5433");
        poolProperties.setProperty("dataSource.databaseName", "yugabyte");
        poolProperties.setProperty("dataSource.user", "yugabyte");
        poolProperties.setProperty("dataSource.password", "yugabyte");
        // If you want to provide additional end points
        String additionalEndpoints = "127.0.0.2:5433,127.0.0.3:5433";
        poolProperties.setProperty("dataSource.additionalEndpoints", additionalEndpoints);
    
        HikariConfig config = new HikariConfig(poolProperties);
        config.validate();
        HikariDataSource hikariDataSource = new HikariDataSource(config);
    
        System.out.println("Wait for some time for Hikari Pool to setup and create the connections...");
        System.out.println("You can verify the load balancing by visiting http://<host>:13000/rpcz as discussed before.");
        System.out.println("Enter a integer to continue once verified:");
        int x = new Scanner(System.in).nextInt();
    
        System.out.println("Closing the Hikari Connection Pool!!");
        hikariDataSource.close();
    
      }
    
    }
    

    When using DriverManager.getConnection(), you need to include the load-balance=true property in the connection URL. In the case of YBClusterAwareDataSource, load balancing is enabled by default.

  3. Run the application, as follows:

    mvn -q package exec:java -DskipTests -Dexec.mainClass=com.yugabyte.UniformLoadBalanceApp
    

Topology-aware load balancing

  1. Create a file called ./src/main/java/com/yugabyte/TopologyAwareLoadBalanceApp.java by executing the following command:

    touch ./src/main/java/com/yugabyte/TopologyAwareLoadBalanceApp.java
    
  2. Paste the following into TopologyAwareLoadBalanceApp.java:

    package com.yugabyte;
    
    import com.zaxxer.hikari.HikariConfig;
    import com.zaxxer.hikari.HikariDataSource;
    
    import java.sql.Connection;
    import java.sql.DriverManager;
    import java.sql.SQLException;
    import java.util.ArrayList;
    import java.util.List;
    import java.util.Properties;
    import java.util.Scanner;
    
    public class TopologyAwareLoadBalanceApp {
    
      public static void main(String[] args) {
    
        makeConnectionUsingDriverManager();
        makeConnectionUsingYbClusterAwareDataSource();
    
        System.out.println("Execution of Uniform Load Balance Java App complete!!");
      }
    
      public static void makeConnectionUsingDriverManager() {
        // List to store the connections so that they can be closed at the end
        List<Connection> connectionList = new ArrayList<>();
    
        System.out.println("Lets create 6 connections using DriverManager");
        String yburl = "jdbc:yugabytedb://127.0.0.1:5433/yugabyte?user=yugabyte&password=yugabyte&load-balance=true"
          + "&topology-keys=aws.us-west.us-west-2a";
    
        try {
          for(int i=0; i<6; i++) {
            Connection connection = DriverManager.getConnection(yburl);
            connectionList.add(connection);
          }
    
          System.out.println("You can verify the load balancing by visiting http://<host>:13000/rpcz as discussed before");
          System.out.println("Enter a integer to continue once verified:");
          int x = new Scanner(System.in).nextInt();
    
          System.out.println("Closing the connections!!");
          for(Connection connection : connectionList) {
            connection.close();
          }
    
        }
        catch (SQLException exception) {
          exception.printStackTrace();
        }
    
      }
    
      public static void makeConnectionUsingYbClusterAwareDataSource() {
        System.out.println("Now, Lets create 10 connections using YbClusterAwareDataSource and Hikari Pool");
    
        Properties poolProperties = new Properties();
        poolProperties.setProperty("dataSourceClassName", "com.yugabyte.ysql.YBClusterAwareDataSource");
        // The pool will create  10 connections to the servers
        poolProperties.setProperty("maximumPoolSize", String.valueOf(10));
        poolProperties.setProperty("dataSource.serverName", "127.0.0.1");
        poolProperties.setProperty("dataSource.portNumber", "5433");
        poolProperties.setProperty("dataSource.databaseName", "yugabyte");
        poolProperties.setProperty("dataSource.user", "yugabyte");
        poolProperties.setProperty("dataSource.password", "yugabyte");
        // If you want to provide additional end points
        String additionalEndpoints = "127.0.0.2:5433,127.0.0.3:5433";
        poolProperties.setProperty("dataSource.additionalEndpoints", additionalEndpoints);
    
        // If you want to load balance between specific geo locations using topology keys
        String geoLocations = "aws.us-west.us-west-2a";
        poolProperties.setProperty("dataSource.topologyKeys", geoLocations);
        HikariConfig config = new HikariConfig(poolProperties);
        config.validate();
        HikariDataSource hikariDataSource = new HikariDataSource(config);
    
        System.out.println("Wait for some time for Hikari Pool to setup and create the connections...");
        System.out.println("You can verify the load balancing by visiting http://<host>:13000/rpcz as discussed before.");
        System.out.println("Enter a integer to continue once verified:");
        int x = new Scanner(System.in).nextInt();
    
        System.out.println("Closing the Hikari Connection Pool!!");
        hikariDataSource.close();
    
      }
    
    }
    

    When using DriverManager.getConnection(), you need to include the load-balance=true property in the connection URL. In the case of YBClusterAwareDataSource, load balancing is enabled by default, but you must set property dataSource.topologyKeys.

  3. Run the application, as follows:

     mvn -q package exec:java -DskipTests -Dexec.mainClass=com.yugabyte.TopologyAwareLoadBalanceApp