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 downloading the packaged database.

Prerequisites

Before installing YugabyteDB, ensure that you have the following available:

  • macOS 10.12 or later.

  • Python 3. To check the version, execute the following command:

    python --version
    
    Python 3.7.3
    
  • wget or curl.

    Note that the following instructions use the wget command to download files. If you prefer to use curl (included in macOS), you can replace wget with curl -O.

    To install wget on your Mac, you can run the following command if you use Homebrew:

    brew install wget
    

Set file limits

Because each tablet maps to its own file, you can create a very large number of files in the current shell by experimenting with several hundred tables and several tablets per table. Execute the following command to ensure that the limit is set to a large number:

launchctl limit

It is recommended to have at least the following soft and hard limits:

maxproc     2500        2500
maxfiles    1048576     1048576

Edit /etc/sysctl.conf, if it exists, to include the following:

kern.maxfiles=1048576
kern.maxproc=2500
kern.maxprocperuid=2500
kern.maxfilesperproc=1048576

If this file does not exist, create the following two files:

  • /Library/LaunchDaemons/limit.maxfiles.plist and insert the following:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
      <dict>
        <key>Label</key>
          <string>limit.maxfiles</string>
        <key>ProgramArguments</key>
          <array>
            <string>launchctl</string>
            <string>limit</string>
            <string>maxfiles</string>
            <string>1048576</string>
            <string>1048576</string>
          </array>
        <key>RunAtLoad</key>
          <true/>
        <key>ServiceIPC</key>
          <false/>
      </dict>
    </plist>
    
  • /Library/LaunchDaemons/limit.maxproc.plist and insert the following:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
      <dict>
        <key>Label</key>
          <string>limit.maxproc</string>
        <key>ProgramArguments</key>
          <array>
            <string>launchctl</string>
            <string>limit</string>
            <string>maxproc</string>
            <string>2500</string>
            <string>2500</string>
          </array>
        <key>RunAtLoad</key>
          <true/>
        <key>ServiceIPC</key>
          <false/>
      </dict>
    </plist>
    

Ensure that the plist files are owned by root:wheel and have permissions -rw-r--r--. To take effect, you need to reboot your computer or run the following commands:

sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist
sudo launchctl load -w /Library/LaunchDaemons/limit.maxproc.plist

You might need to unload the service before loading it.

Download YugabyteDB

You download YugabyteDB as follows:

  1. Download the YugabyteDB tar.gz file by executing the following wget command:

    wget https://downloads.yugabyte.com/releases/2.15.2.0/yugabyte-2.15.2.0-b87-darwin-x86_64.tar.gz
    
  2. Extract the package and then change directories to the YugabyteDB home, as follows:

    tar xvfz yugabyte-2.15.2.0-b87-darwin-x86_64.tar.gz && cd yugabyte-2.15.2.0/
    

Create a local cluster

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

./bin/yugabyted start

If you are running macOS Monterey, run the following command:

./bin/yugabyted start --master_webserver_port=9999

macOS Monterey enables AirPlay receiving by default, which listens on port 7000. This conflicts with YugabyteDB and causes yugabyted start to fail. Using the --master_webserver_port flag when you start the cluster changes the default port number. Alternatively, you can disable AirPlay receiving, then start YugabyteDB normally, and then, optionally, re-enable AirPlay receiving.

Check the cluster status

Execute the following command to check the cluster status:

./bin/yugabyted status

Expect an output similar to the following:

+--------------------------------------------------------------------------------------------------+
|                                            yugabyted                                             |
+--------------------------------------------------------------------------------------------------+
| Status              : Running.                                                                   |
| Replication Factor  : 1                                                                          |
| Web console         : http://127.0.0.1:7000                                                      |
| JDBC                : jdbc:postgresql://127.0.0.1:5433/yugabyte?user=yugabyte&password=yugabyte  |
| YSQL                : bin/ysqlsh   -U yugabyte -d yugabyte                                       |
| YCQL                : bin/ycqlsh   -u cassandra                                                  |
| Data Dir            : /Users/myuser/var/data                                                     |
| Log Dir             : /Users/myuser/var/logs                                                     |
| Universe UUID       : fad6c687-e1dc-4dfd-af4b-380021e19be3                                       |
+--------------------------------------------------------------------------------------------------+

After the cluster has been created, clients can connect to the YSQL and YCQL APIs at http://localhost:5433 and http://localhost:9042 respectively. You can also check ~/var/data to see the data directory and ~/var/logs to see the logs directory.

If you have previously installed YugabyteDB version 2.8 or later and created a cluster on the same computer, you may need to upgrade the YSQL system catalog to run the latest features.

Use the 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://127.0.0.1:7000 (replace the port number if you've started yugabyted with the --master_webserver_port flag) and the YB-TServer Admin UI is available at http://127.0.0.1:9000.

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 displays 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. Because there are no user tables, User Tablet-Peers / Leaders is 0. As tables are added, new tablets (also known as shards) will be created automatically and distributed evenly across all the available tablet servers.

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.

./bin/ysqlsh
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

The following tutorial shows a small Java application that connects to a YugabyteDB cluster using the topology-aware YugabyteDB JDBC driver and performs basic SQL operations.

For examples using other languages, refer to Build an application.

Prerequisites

  • Java Development Kit (JDK) 1.8 or later. JDK installers can be downloaded from OpenJDK.
  • Apache Maven 3.3 or later.

Start a local multi-node cluster

First, destroy the currently running single-node cluster:

./bin/yugabyted destroy

Create the first node as follows:

./bin/yugabyted start --advertise_address=127.0.0.1 --base_dir=$HOME/yugabyte-2.15.2.0/node1 --cloud_location=aws.us-east.us-east-1a

The additional nodes need loopback addresses configured that allow you to simulate the use of multiple hosts or nodes:

sudo ifconfig lo0 alias 127.0.0.2
sudo ifconfig lo0 alias 127.0.0.3

The loopback addresses do not persist upon rebooting your computer.

Add two more nodes to the cluster using the join option:

./bin/yugabyted start --advertise_address=127.0.0.2 --join=127.0.0.1 --base_dir=$HOME/yugabyte-2.15.2.0/node2 --cloud_location=aws.us-east.us-east-2a

./bin/yugabyted start --advertise_address=127.0.0.3 --join=127.0.0.1 --base_dir=$HOME/yugabyte-2.15.2.0/node3 --cloud_location=aws.us-east.us-east-3a

After starting the yugabyted processes on all the nodes, configure the data placement constraint of the YugabyteDB cluster:

./bin/yugabyted configure --fault_tolerance=zone

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 block 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