Get Started with the Hazelcast CLC

In this tutorial, you’ll learn how to use Hazelcast CLC commands to authenticate with Hazelcast Cloud and create two production clusters. You’ll connect to and switch between the clusters from the command line. Finally, you’ll perform some basic operations on a cluster from both the command line and by running a script to automate the same actions.

Before You Begin

You need the following:

Hazelcast CLC installed on your local machine.
Cloud account
Cloud API key and secret

Step 1. Authenticating with Cloud

To allow the Hazelcast CLC to to interact with Cloud clusters, you must generate a Cloud token.

Execute the following command to retrieve the token.
```
clc viridian login
```
When prompted, enter your API key and secret. If both are correct, the token is retrieved and saved.

Step 2. Create Two Clusters on Cloud

In this step, you’ll create two production clusters called Test1 and Test2 from the command line, and run some commands to check their status.

Execute the following command to create your first production cluster.
```
clc viridian create-cluster --name Test1
```
Wait while the cluster is created and the cluster configuration is imported into the Hazelcast CLC.
Create your second production cluster in the same way.
```
clc viridian create-cluster --name Test2
```
Try running the following command to check your clusters have been created:
```
clc viridian list-clusters
```
The details of all clusters linked to your Cloud account are returned, including the Cluster ID, Cluster Name, Current Status, Hazelcast Version.

Step 3. Add Configuration to Connect to Cloud

To connect to each production cluster, you need to import additional cluster configuration from Cloud.

Run the clc config import to update the cluster configuration on your local machine.
```
clc viridian import-config Test1
```
Run the following command to connect to your cluster using the Hazelcast CLC.
```
clc -c Test1
```
The Hazelcast CLC only connects to the cluster when necessary. Run a command that requires a connection to the cluster, such as object list:
```
> \object list
Connected to cluster: pr-<CLUSTER-ID>
```
As this is a new cluster, no objects are returned.

This command shows the cluster ID prefixed with pr instead of the cluster name. You can see the cluster ID in Cluster Details on the Cloud console.
Press Ctrl+D or type \exit to shut down the Hazelcast CLC while you complete the configuration of your second production cluster.
Repeat steps 1 to 4 for Test2.

Step 4. Switch Between Clusters

Having separate local configurations for your two 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 connect to your Test1 cluster.
```
clc -c Test1
```
As before, the Hazelcast CLC connects to your Test1 cluster.
Type \exit to return to the command line.
Execute the same command to connect to Test2.
```
clc -c Test2
```
Again, type \exit to return to the command line.

Step 5. Write Data to a Map

Now that you’ve connected to both your clusters, try using the Hazelcast CLC to create a map on Test1, write some data to it, and query the data. You can use SQL to do this.

Start by creating a mapping to a new currency map.
```
clc sql -c Test1 "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.

Add some data to the map.

clc sql -c Test1 "INSERT INTO currency 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');"

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 Test1 "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 writes the currency data to a new map called currencydata on a cluster and queries it.

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 Test1 cluster, execute the following command.
```
cat myscript.sql | clc -c Test1
```
Then, to run the script on your Test2 cluster, execute the same command replacing the cluster name.
```
cat myscript.sql | clc -c Test2
```

To run the script on your Test1 cluster, execute the following command.
```
type myscript.sql | clc -c Test1
```
Then, to run the script on your Test2 cluster, execute the same command replacing the cluster name.
```
type myscript.sql | clc -c Test2
```

Step 7. Clean Up

To delete both test clusters from your account.

Sign in to Cloud and select a test cluster.
Click Delete and confirm your deletion.

Summary

In this tutorial, you learned how to do the following:

Authenticate with Cloud.
Create a cluster and check its status.
Connect to a Cloud 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: