Getting Started With GridGain 9
This guide shows you how to start working with GridGain using the GridGain CLI. 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.
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 |
OS |
Linux (Debian and Red Hat flavours), Windows 10 or 11 |
ISA |
x86 or x64 |
Install GridGain
-
Download GridGain from the website, and request a license key from the download page.
The downloaded package should include:
-
GridGain platform - this archive contains everything related to the GridGain database.
-
Command line interface - this archive contains the GridGain CLI tool. This tool is the main way of interacting with GridGain clusters and nodes.
-
-
Unpack the archive:
unzip gridgain9-db-9.0.7.zip unzip gridgain9-cli-9.0.7.zip
Expand-Archive gridgain9-db-9.0.7.zip -DestinationPath . Expand-Archive gridgain9-cli-9.0.7.zip -DestinationPath .
unzip -xf gridgain9-db-9.0.7.zip unzip -xf gridgain9-cli-9.0.7.zip
Now you have the gridgain9-db-9.0.7
and gridgain9-cli-9.0.7
directories that we will be using in this tutorial.
Start GridGain Node
When starting to work with GridGain, first we need to start a GridGain node that will be handling the API calls.
-
Navigate to the
gridgain9-db-9.0.7
directory. -
Run the
gridgain9db
script:bin/gridgain9db
bash bin\gridgain9db
Start the GridGain CLI
The primary means of interacting with your cluster is the GridGain CLI. It can connect to a node running on a local or remote machine. In this example, we will be connecting to a local node.
To start the GridGain CLI:
-
Navigate to the
gridgain9-cli-9.0.7
directory. -
Run the following command:
bin/gridgain9
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://localhost:10300
Connected to http://127.0.0.1:10300
Initialize Your Cluster
The process of starting a cluster is called initialization. To initialize the cluster, you select the metastorage group nodes 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. For more information on what they are and cluster lifecycle, see Cluster Lifecycle. -
The
--config-files
parameter specifies cluster configuration. As license is part of cluster configuration, we can just provide it in this parameter. The relative path to the license file is resolved based on the directory the CLI tool is started from. You can also provide the absolute path to the file.
Run SQL Statements Against the Cluster
Once your cluster has been initialized, you can manage it with SQL commands:
-
Use the
CREATE TABLE
statement to create a new table:sql "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:sql "INSERT INTO Person (id, city, name, age, company) VALUES ('1', 'London', 'John Doe', '42', 'Apache')" sql "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:
sql "SELECT * FROM Person"
╔════╤══════════╤══════════╤═════╤═════════╗ ║ ID │ CITY │ NAME │ AGE │ COMPANY ║ ╠════╪══════════╪══════════╪═════╪═════════╣ ║ 2 │ New York │ Jane Doe │ 36 │ Apache ║ ╟────┼──────────┼──────────┼─────┼─────────╢ ║ 1 │ London │ John Doe │ 42 │ Apache ║ ╚════╧══════════╧══════════╧═════╧═════════╝
Stop the Cluster
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.
Optional: Start Multiple GridGain Nodes in Docker
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.
To run multiple instances of GridGain, you would normally install it on multiple machines before starting a cluster. If you want to emulate a GridGain cluster for this tutorial:
-
Download the docker-compose and node configuration provided.
-
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:
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.