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 cluster on Hazelcast Cloud. 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 Cloud 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.

Step 1. Add Configuration for the Development Cluster

Make sure that your development cluster is running before you start.

Sign in to Cloud and select the development cluster.
From the cluster dashboard, click CLI to open the Quick Connection Guide for the Hazelcast CLC client.
Run the clc config import command in step 2. This command imports the cluster configuration to your local machine.
Run the clc -c pr-<CLUSTER_ID> command in step 3 to connect to your cluster using the Hazelcast CLC.
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 production cluster is running before you start.

Sign in to Cloud and select the production cluster.
From the cluster dashboard, click CLI to open the Quick Connection Guide for the Hazelcast CLC client.
Run the clc config import command in step 2. This command imports the cluster configuration to your local machine.
Run the clc -c pr-<CLUSTER_ID> command in step 3 to connect to your cluster using the Hazelcast CLC.
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
prod
```
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.

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 connect to the development cluster. Replace the placeholder $CLUSTER_NAME with the name of your cluster:
```
clc -c $CLUSTER_NAME
```
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 production cluster.
```
clc -c $CLUSTER_NAME
```
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 create a map on your development cluster, 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. Replace the placeholder $CLUSTER_NAME with the name of your cluster:
```
clc sql -c $CLUSTER_NAME "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 $CLUSTER_NAME "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 $CLUSTER_NAME "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 5. 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 a cluster.

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, replacing the placeholder $CLUSTER_NAME with the name of your development cluster:
```
cat myscript.sql | clc -c $CLUSTER_NAME
```
Then, to run the script on your production cluster, execute the following command:
```
cat myscript.sql | clc -c $CLUSTER_NAME
```

To run the script on your development cluster, replacing the placeholder $CLUSTER_NAME with the name of your development cluster:
```
type myscript.sql | clc -c $CLUSTER_NAME
```
Then, to run the script on your production cluster, execute the following command:
```
type myscript.sql | clc -c $CLUSTER_NAME
```

Step 6. 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:

Connect to a development cluster on Cloud.
Connect to a production cluster on Cloud.
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: