Getting Started With GridGain 9

This guide shows you how to start working with GridGain. In it, we will download GridGain from the website, install it, start the database and perform some simple SQL queries by using the provided CLI tool.

We will be using the zip archive to demonstrate how to use GridGain. When using deb or rpm packages, or when running GridGain in Docker, some steps may be different.

If you are more comfortable with running the database from Java code, you can try starting GridGain from code.

Prerequisites

This section describes the platform requirements for machines running GridGain. GridGain system requirements scale depending on the size of the cluster.

JDK

11 and later

Linux (Debian and Red Hat flavours), Windows 10 or 11

ISA

x86 or x64

Install GridGain

Download GridGain from the website. This archive contains everything related to the GridGain database itself.
On the same page, request a free license key. Our team will soon provide a valid license that can be used to complete this tutorial and more.
Also from the same page, download the GridGain command line interface. This tool is the main way of interacting with GridGain database and will be used in the tutorial

Unpack the downloaded archives:

unzip gridgain9-db-9.0.11.zip
unzip gridgain9-cli-9.0.11.zip

Expand-Archive gridgain9-db-9.0.11.zip -DestinationPath .
Expand-Archive gridgain9-cli-9.0.11.zip -DestinationPath .

unzip -xf gridgain9-db-9.0.11.zip
unzip -xf gridgain9-cli-9.0.11.zip

Now you should have the gridgain9-db-9.0.11 and gridgain9-cli-9.0.11 directories that we will be using in this tutorial, and the license file provided via e-mail.

Start GridGain Node

GridGain is a distributed database, that runs on a collection of nodes - GridGain database instances that contain data. When running GridGain, you would typically run multiple nodes - a cluster, that shares information and evenly distributes data across its nodes. In this part of the tutorial, we will only run one node, but a later part shows how you can start multiple.

To start a locally running node:

Navigate to the gridgain9-db-9.0.11 directory.
Run the gridgain9db script:
bin/gridgain9db
You need to install Java in the Bash environment to run GridGain on Windows.
bash bin\gridgain9db

Start the GridGain CLI

The primary means of interacting with your nodes and cluster is the GridGain CLI. It can connect to a node running on a local or remote machine, and is the main tool that is used to manually configure and manage the database. In this example, we will be connecting to a local node.

To start the GridGain CLI:

Navigate to the gridgain9-cli-9.0.11 directory.
Run the following command:
bin/gridgain9
You need to install Java in the Bash environment to run GridGain on Windows.
bash bin\gridgain9
Confirm the connection the CLI tool attempts to establish with the node running on the default URI.
If your node is running at a different address, use the connect command to connect to the node. For example:
connect http://127.0.0.1:10300
Connected to http://127.0.0.1:10300

Initialize Your Cluster

GridGain database functions as a cluster. Even if we are currently only running a single node, theoretically you could start another node and have it join the already running cluster. When the nodes are started, they find each other and wait for the user to start the cluster. The process of starting a cluster is called initialization.

To initialize the cluster, you select the metastorage group nodes - the group of nodes that will be responsible for managing the cluster, and provide a GridGain license.

To initialize the cluster with the node you have started (see Start GridGain Node), run the following command:

cluster init --name=sampleCluster --metastorage-group=defaultNode --config-files=license.conf

Cluster was initialized successfully

The --metastorage-group parameter specifies the nodes that will be used to store cluster meta information. In most scenarios, you want to have 3, 5 or 7 metastorage group nodes. For more information on what they are and cluster lifecycle, see Cluster Lifecycle.
The --config-files parameter specifies the relative path to the cluster configuration file. As license is part of cluster configuration, we can just provide it in this parameter. Any parameters not specified in the configuration will be assigned default values. The relative path to the configuration file is resolved based on the directory the CLI tool is started from. You can also provide the absolute path to the file.

Cluster and node configurations in GridGain are separated and cannot be used interchangeably. When initializing a cluster, make sure to provide the cluster configuration file.

Run SQL Statements Against the Cluster

Once your cluster has been initialized, you can start working with it. In this tutorial, we will be using the CLI tool to create a table, insert some rows and retrieve data. In most real scenarios you would have a client writing data to a cluster and retrieving it, but the CLI tool can still be used for debugging or minor adjustments.

To work with the SQL in CLI:

Enter the SQL REPL mode. In this mode, you will have access to SQL hints and command completion:

sql

sql-cli>

Use the CREATE TABLE statement to create a new table:

CREATE TABLE IF NOT EXISTS Person (id int primary key,  city varchar,  name varchar,  age int,  company varchar)

Updated 0 rows.

Fill the table with data using the INSERT statement:

INSERT INTO Person (id, city, name, age, company) VALUES ('1', 'London', 'John Doe', '42', 'Apache')
INSERT INTO Person (id, city, name, age, company) VALUES ('2', 'New York', 'Jane Doe', '36', 'Apache')

Updated 1 rows.

Get all the data you inserted in the previous step:

SELECT * FROM Person

╔════╤══════════╤══════════╤═════╤═════════╗
║ ID │ CITY     │ NAME     │ AGE │ COMPANY ║
╠════╪══════════╪══════════╪═════╪═════════╣
║ 2  │ New York │ Jane Doe │ 36  │ Apache  ║
╟────┼──────────┼──────────┼─────┼─────────╢
║ 1  │ London   │ John Doe │ 42  │ Apache  ║
╚════╧══════════╧══════════╧═════╧═════════╝

If needed, exit the REPL mode with the exit command.

Stop the Node

After you are done working with your cluster, you need to stop the node by stopping the gridgain9db process:

Unix: Control + C
Windows: Ctrl+C

You can also exit the CLI tool with the exit command.

The cluster will remain initialized, and ready once again when you restart the node.

Extended Cluster Startup Tutorial

GridGain 9 is designed to work in a cluster of 3 or more nodes at once. While a single node can be used in some scenarios and can be used for the tutorial, having multiple nodes in a cluster is the most common use case. The steps below provide optional alternatives to starting your cluster, in case you want to run the tutorial on multiple nodes in a cluster that is closer to what would be encountered in real scenarios.

Optional: Starting Multiple GridGain Nodes in Docker

To run multiple instances of GridGain, you would normally install it on multiple machines before starting a cluster. If you want to run a GridGain cluster on local VMs for this tutorial, we recommend using a Docker image:

Download the docker-compose and node configuration that will be used by docker compose to start the cluster. The node configuration should be in the same folder as docker compose file

Download the Docker image:

docker pull gridgain/gridgain9:latest

latest: Pulling from gridgain/gridgain9
3713021b0277: Pull complete
fea31cb87980: Pull complete
07f7cfe80ff6: Pull complete
ab1fd3f4849e: Pull complete
34896af28f87: Pull complete
Digest: sha256:43ab9cfb8f58b66e4a5027d4ed529216963d0bcab3fa3fc6d5e2042fa3dd5a74
Status: Downloaded newer image for gridgain/gridgain9:latest
docker.io/gridgain/gridgain9:latest

Run the Docker compose command, providing the previously downloaded compose file:

docker compose -f docker-compose.yml up -d

[+] Running 4/4
 ✔ Network gridgain9_default    Created                                                                            0.8s
 ✔ Container gridgain9-node1-1  Started                                                                            3.2s
 ✔ Container gridgain9-node2-1  Started                                                                            1.7s
 ✔ Container gridgain9-node3-1  Started                                                                            3.4s

3 nodes start in Docker and become available through the CLI tool that can be run locally.

Make sure you initialize your cluster before attempting to work with it:

cluster init --name=sampleCluster --metastorage-group=defaultNode --config-files=license.conf

Cluster was initialized successfully

Optional: Start Multiple GridGain Nodes on Different Hosts

In the examples above, we were running a single node, or a small cluster that used predefined configuration. Creating a GridGain cluster on several hosts involves adjustments to its configuration.

List all Nodes in NodeFinder

When nodes are running, they use the node finder configuration. When the node starts, it loads the configuration file from /etc/gridgain-config.conf. Add the addresses to the network.nodeFinder configuration, for example for the 3-node cluster:

{
  "ignite" : {
    "nodeFinder" : {
      "netClusterNodes" : [
        "localhost:3344",
        "otherhost:3344",
        "thirdhost:3344"
      ]
    }
  }
}

Now, when the node starts, it automatically tries to find nodes at the listed addresses. You can see the current configuration of a running node at any point by running the following command from the CLI tool:

node config show ignite.network.nodeFinder

{
  "netClusterNodes" : [ "localhost:3344", "otherhost:3344", "thirdhost:3344" ],
  "type" : "STATIC"
}

If the node is already running, you can also use the CLI tool to change node configuration, for example:

node config update ignite.network.nodeFinder.netClusterNodes=["localhost:3344", "otherHost:3344"]

This change requires the node restart to take effect.

Change Node Names

You need to make sure that all nodes in the cluster have different names. Node name is defined in the /etc/vars.env file. Change the NODE_NAME variable to have unique name for each node in cluster, otherwise it will be impossible for the nodes with conflicting names to enter the same cluster.

Start all Nodes

Start each node as described in Start GridGain Node.

Initialize Your Cluster

Before initializing the cluster, it is important to check that all nodes found each other and can connect into a cluster. Nodes visible to each other, but not necessarily connected into a cluster form physical topology. You can check it by connecting to any node using the CLI tool and executing the following command:

cluster topology physical

╔═══════╤════════════╤══════╤═══════════════╤══════════════════════════════════════╗
║ name  │ host       │ port │ consistent id │ id                                   ║
╠═══════╪════════════╪══════╪═══════════════╪══════════════════════════════════════╣
║ node1 │ 172.19.0.4 │ 3344 │ node1         │ 0c61dad3-bc4c-4c60-8772-1a903632dcb4 ║
╟───────┼────────────┼──────┼───────────────┼──────────────────────────────────────╢
║ node2 │ 172.19.0.2 │ 3344 │ node2         │ 21f516bd-0774-4c53-bbfb-ad21bc21c500 ║
╟───────┼────────────┼──────┼───────────────┼──────────────────────────────────────╢
║ node3 │ 172.19.0.3 │ 3344 │ node3         │ b2bbfbff-eb08-4252-b154-681c49164708 ║
╚═══════╧════════════╧══════╧═══════════════╧══════════════════════════════════════╝

The command lists the nodes visible to the node you are connecting to, their addresses, names, and IDs. Once you are certain all nodes are running and visible, initialize your cluster:

cluster init --name=sampleCluster --metastorage-group=node1 --config-files=valid-license.conf

Cluster was initialized successfully

Once the cluster starts, the nodes in it will form the logical topology. You can check if all nodes have entered the cluster by using the following command:

cluster topology logical

╔═══════╤════════════╤══════╤═══════════════╤══════════════════════════════════════╗
║ name  │ host       │ port │ consistent id │ id                                   ║
╠═══════╪════════════╪══════╪═══════════════╪══════════════════════════════════════╣
║ node1 │ 172.19.0.4 │ 3344 │ node1         │ 0c61dad3-bc4c-4c60-8772-1a903632dcb4 ║
╟───────┼────────────┼──────┼───────────────┼──────────────────────────────────────╢
║ node2 │ 172.19.0.2 │ 3344 │ node2         │ 21f516bd-0774-4c53-bbfb-ad21bc21c500 ║
╟───────┼────────────┼──────┼───────────────┼──────────────────────────────────────╢
║ node3 │ 172.19.0.3 │ 3344 │ node3         │ b2bbfbff-eb08-4252-b154-681c49164708 ║
╚═══════╧════════════╧══════╧═══════════════╧══════════════════════════════════════╝

If all nodes are in the command output, the cluster is now started and can be worked with.

Next Steps

From here, you may want to:

Check out the GridGain CLI Tool page for more detail on supported commands
Try out our examples

© 2024 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.

Last updated on Dec 18, 2024