Get Started With the Hazelcast CLC
In this tutorial, you’ll learn the basics of how to configure the Hazelcast CLC, start it, and connect it to a Hazelcast Viridian Serverless development cluster and a Serverless production cluster. You’ll also see how to switch between clusters, using the Hazelcast CLC. Finally, you’ll perform some basic operations on a cluster from the command line and then by running a script to automate the same actions.
Before You Begin
You need the following:
-
The Hazelcast CLC installed on your local machine
-
Two Hazelcast Viridian Serverless clusters. For this tutorial, you’ll use one development and one production cluster, to show how you might use the CLC for basic administration and deployment tasks.
You can download Go client samples from the Hazelcast Viridian console. For details, see Connecting to Hazelcast Viridian Clusters. |
Step 1. Add Configuration for the Development Cluster
Make sure that your Viridian development cluster is running before you start.
The Hazelcast CLC can use a Go client sample for Viridian to discover the configuration for your Viridian cluster.
-
Download the Go client sample for your development cluster from the Viridian console. Once the sample is downloaded, you can use the
clc config import
command to import the configuration. -
From the command line, execute the following command, replacing
PATH-TO-SAMPLE.zip
with the path to the downloaded sample:clc config import dev PATH-TO-SAMPLE.zip clc -c dev
-
You can use the
clc config list
command to confirm that the configuration was imported. The output will look something like this:clc config list default dev
-
The CLC only connects to the cluster when necessary. Run a command that requires a connection to the cluster, such as
object list
:CLC> \object list Connected to cluster: pr-3814
As this is a new cluster, no objects are returned.
-
Press Ctrl+D or type
\exit
to shut down the Hazelcast CLC while you complete the configuration for your production cluster.
Step 2. Add Configuration for the Production Cluster
The configuration of the production cluster is the same as the previous step, but using the production cluster configuration.
Make sure that your Viridian production cluster is running before you start.
-
Download the Go client sample for your production cluster from the Viridian console.
-
From the command line, execute the following command, replacing
PATH-TO-SAMPLE.zip
with the path to the downloaded sample:clc config import prod PATH-TO-SAMPLE.zip clc -c prod
-
CLC only connects to the cluster when necessary. Run a command that requires a connection to the cluster, such as
object list
:CLC> \object list Connected to cluster: pr-3690 ------------------------------------ Service Name | Object Name ------------------------------------ executor | hot-backup-executor ------------------------------------
Step 3. Switch Between Clusters
Having separate local configurations for your development and production clusters allows you to switch between them without leaving the command line. Make sure both clusters are running before you start.
-
Execute the following command to use the
dev
configuration to connect to your development cluster:clc -c dev
As before, the Hazelcast CLC connects to your development cluster.
-
Type
\exit
to return to the command line. -
Execute the following command to use the new configuration file for your production cluster.
clc -c prod
The Hazelcast CLC shell is started, using the configuration for the production cluster. You can exit the shell by typing
\exit
.
Step 4. Write Data to a Map
Now that you’ve connected to both your clusters, try using the Hazelcast CLC to write data to a map on your development cluster. Let’s write a script that adds some data to a map.
-
Create a file called
data.script
on your local machine and copy in the following lines.data.script\map set -n currency -k i32 1 -v json '{"Code": "CAD", "Currency": "Canadian Dollar"}' \map set -n currency -k i32 2 -v json '{"Code": "INR", "Currency": "Indian Rupee"}' \map set -n currency -k i32 3 -v json '{"Code": "MXN", "Currency": "Mexican Peso"}' \map set -n currency -k i32 4 -v json '{"Code": "GBP", "Currency": "Pounds Sterling"}' \map set -n currency -k i32 5 -v json '{"Code": "TRY", "Currency": "Turkish Lira"}' \map set -n currency -k i32 6 -v json '{"Code": "USD", "Currency": "United States Dollar"}'
-
Run the script in the
data.script
file to update thecurrency
map:On Linux and MacOS:
cat data.script | clc -c dev
On Windows:
type data.script | clc -c dev
Do a quick check on your cluster to make sure that your data has been written successfully.
-
Open the dashboard of the development cluster and click Management Center.
-
Go to Storage > Maps. You’ll see that your cluster has a map called
currency
with six entries.
Step 5. Query Map Data
You can use SQL to query the data in your currency
map.
-
Start by creating a mapping to the
currency
map.clc sql -c dev "CREATE OR REPLACE MAPPING currency (__key INT, Code VARCHAR, Currency VARCHAR) TYPE IMap OPTIONS('keyFormat'='int', 'valueFormat'='json-flat')"
The SQL mapping statement does a number of things:
-
Adds column headings for currencies and codes
-
Creates a SQL connection to the map
-
Tells Hazelcast how to serialize and deserialize the keys and values.
-
-
Try running some simple queries against the
currency
map. For example, this query returns all data in the map and orders it by the currency code.clc sql -c dev "SELECT * FROM currency ORDER BY Code" -f table
The results look like this:
-------------------------------------------------------------------------------- __key | Code | Currency -------------------------------------------------------------------------------- 1 | CAD | Canadian Dollar 4 | GBP | Pounds Sterling 2 | INR | Indian Rupee 3 | MXN | Mexican Peso 5 | TRY | Turkish Lira 6 | USD | United States Dollar --------------------------------------------------------------------------------
Step 6. Automate Actions
When you’re ready, combine the commands that you’ve learned about so far into a script and run them from the command line.
The script first writes the currency data to a new map called currencydata
on your development server, queries it and then switches to your production cluster to perform the same actions.
-
Copy the following commands into a script.
myscript.sqlCREATE OR REPLACE MAPPING currencydata ( __key INT, Code VARCHAR, Currency VARCHAR ) TYPE IMap OPTIONS( 'keyFormat'='int', 'valueFormat'='json-flat' ); INSERT INTO currencydata VALUES (1, 'CAD', 'Canadian Dollar'), (2, 'INR', 'Indian Rupee'), (3, 'MXN', 'Mexican Peso'), (4, 'GBP', 'Pounds Sterling'), (5, 'TRY', 'Turkish Lira'), (6, 'USD', 'United States Dollar'); SELECT * FROM currencydata ORDER BY Code;
-
Save your script as
myscript.sql
.
-
To run the script on your development cluster, execute the following command:
cat myscript.sql | clc -c dev
-
Then, to run the script on your production cluster, execute the following command:
cat myscript.sql | clc -c prod
-
To run the script on your development cluster, execute the following command:
type myscript.sql | clc -c dev
-
Then, to run the script on your production cluster, execute the following command:
type myscript.sql | clc -c prod
Summary
In this tutorial, you learned how to do the following:
-
Connect to a Hazelcast Viridian Serverless development cluster.
-
Connect to a Hazelcast Viridian Serverless production cluster.
-
Switch between clusters from the command line.
-
Write data to a map and query the data using SQL.
-
Automate commands by running a sequence of actions from a shell script.