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 the currency 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.sql

CREATE 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.

Linux and MacOS
Windows

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.

Learn More

Use these resources to continue learning: