CRDB-CLI Commands

An Active-Active database (also known as CRDB or Conflict-free, Replicated DataBase) replicates your dataset across Redis Enterprise Software (RS) clusters located in geographically distributed regions. Active-Active databases allow read-write access in all locations, making them ideal for distributed applications that require the fastest response times, and also for disaster recovery.

The Active-Active database on an individual cluster is called an instance. Each cluster that hosts an instance is called a participating cluster.

An Active-Active database requires two or more participating clusters. Each instance is responsible for updating the instances residing on other participating clusters with the transactions it receives. Write conflicts are resolved using CRDTs.

To programmatically maintain an Active-Active database and its instances, you can use the CRDB-CLI command-line tool.

Using the crdb-cli

To use the CRDB-CLI tool, use SSH to log in to an RS host with a user that belongs to the group that RS was installed with (Default: redislabs). If you log in with a non-root user, you must add /opt/redislabs/bin/ to your PATH environment variables.

CRDB-CLI commands use the syntax: crdb-cli <command> <arguments> to let you:

• Create, list, update, flush, or delete an Active-Active database
• Add or remove an instance of the Active-Active database on a specific cluster

Each command creates a task. By default, the command runs immediately and you see the result of the command in the command output. If you use the --no-wait flag, the command runs in the background so that your application is not delayed by the response. You can track the task with crdb-cli task status.

For each CRDB-CLI command, you can use --help for additional information about the command.

Active-Active database operations

Active-Active database operations affect the configuration and data of the database.

Creating an Active-Active database

The crdb create command lets you create a customized Active-Active database and create instances of the database on specified participating clusters. Before you create an Active-Active database you must have:

• At least two participating clusters
• Network connectivity between the participating clusters

When you create an Active-Active database, you must specify:

The syntax for the command is:

crdb-cli crdb create --name <name> /
--memory-size <maximum_memory> --port <port_number> /
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password> /
--instance fqdn=<cluster_fqdn>,username=<username>,password=<password> /
[--no-wait] /
[--db-config-json <file_content>] /
[--db-config-json-file <filename>] /
[--compression (0-6)] /
[--causal-consistency true] /
[--password <password>] /
[--replication true] /
[--encryption true] /
[--sharding false] /
[-- shards-count <number_of_shards>] /
[--shard-key-regex <regex_rule>] /
[--oss-sharding BOOLEAN] /
[--oss-cluster true]
[--bigstore true]
[--bigstore-ram-size <maximum_memory>]
[--with-module name=<module_name>,version=<module_version>,args=<module_args>]

After you run the command, the response shows the globally unique identifier (GUID) of the task and the GUID of the Active-Active database that was created:

Task 2b3d62c6-395b-4679-87b1-eef006ad4a38 created
  ---> Status changed: queued -> started
  ---> CRDB GUID Assigned: crdb:552bbccb-99f3-4142-bd17-93d245f0bc79
  ---> Status changed: started -> finished

If you only specify the required fields, the properties of the database are::

• Compression level 3
• Causal consistency is off
• No password
• No replication
• No encryption
• 1 shard
• Shard key regex: {u'regex': u'.*\\{(?<tag>.*)\\}.*'}, {u'regex': u'(?<tag>.*)'}

The crdb create command supports several additional options:

crdb create examples

To create an Active-Active database with two shards in each instance and with encrypted traffic between the clusters:

crdb-cli crdb create --name mycrdb --memory-size 100mb --port 12000 --instance fqdn=cluster1.local,username=test,password=test --instance fqdn=cluster2.local,username=test,password=test --shards-count 2 --encrypted true

To create an Active-Active database with two shards and with RediSearch 2.0.6 module:

crdb-cli crdb create --name mycrdb --memory-size 100mb --port 12000 --instance fqdn=cluster1.local,username=test,password=test --instance fqdn=cluster2.local,username=test,password=test --shards-count 2 --with-module name=search,version="2.0.6",args="PARTITIONS AUTO"

To create an Active-Active database with two shards and with encrypted traffic between the clusters:

crdb-cli crdb create --name mycrdb --memory-size 100mb --port 12000 --instance fqdn=cluster1.local,username=test,password=test --instance fqdn=cluster2.local,username=test,password=test --encrypted true --shards-count 2

To create an Active-Active database with 1 shard in each instance and not wait for the response:

crdb-cli crdb create --name mycrdb --memory-size 100mb --port 12000 --instance fqdn=cluster1.local,username=test,password=test --instance fqdn=cluster2.local,username=test,password=test --no-wait

Showing the list of Active-Active databases

The crdb list command shows all Active-Active databases that the cluster participates in. Each database is represented with a unique GUID, the name of the database, an instance ID, and the FQDN of the cluster that hosts the instance. You use the CRDB-GUID and REPL-ID in other commands, such as add-instance and remove-instance.

crdb-cli crdb list

For example:

# crdb-cli crdb list
CRDB-GUID                                              NAME    REPL-ID     CLUSTER-FQDN
e7ef4552-3705-4790-9f30-6a8e9f4bef28  shopping-cart  1        cluster1.local
e7ef4552-3705-4790-9f30-6a8e9f4bef28  shopping-cart  2        cluster2.local

Updating the configuration of an Active-Active database

The crdb update command lets you change the configuration of the Active-Active instances of an existing Active-Active database. This command requires the CRDB-GUID of the database.

The syntax for the command is:

crdb-cli crdb update --crdb-guid <CRDB-GUID> /
[--no-wait] /
[--db-config-json <file_content>] /
[--db-config-json-file <filename>] /
[--compression (0-6)] /
[--causal-consistency true] /
[--password <password>] /
[--replication true] /
[--encryption true] /
[--oss-cluster true]
[--bigstore-ram-size <maximum_memory>]

The configuration options that you can update are:

Flushing the data from an Active-Active database

The crdb flush command deletes all data in all of the instances of an Active-Active database. This command requires the CRDB-GUID of the database.

To flush the data from an Active-Active database, run:

crdb-cli crdb flush --crdb-guid <CRDB-GUID>

Deleting an Active-Active database

The crdb delete command deletes the Active-Active database and its data. This command requires the CRDB-GUID of the database.

To delete an Active-Active database, run:

crdb-cli crdb delete --crdb-guid <CRDB-GUID>

Active-Active instance operations

Active-Active instance operations affect the placement of database instances on participating clusters, but do not change the configuration or data in the database.

Adding an instance to an Active-Active database

The crdb add-instance command lets you add instances to an existing Active-Active database in order to host the database on additional clusters. This creates a read-write copy of the database on the specified cluster.

When you add an instance to an Active-Active database, you must specify:

Removing an instance from an Active-Active database

The remove-instance command deletes all data from an Active-Active instance, deletes the instance from the participating cluster, and removes the instance from the list of instances for the Active-Active database.

When you remove an instance from an Active-Active database, you must specify:

Active-Active task status

Each crdb-cli crdb command creates a task ID that you can use to track the progress of the command. For example:

# crdb-cli crdb update --crdb-guid dda3d2f6-d1f3-4ecd-ab86-2399d16c1dcc --causal-consistency true
Task 29beaee9-39fd-4f93-af98-51dc223f218b created
  ---> Status changed: queued -> started
  ---> CRDB GUID Assigned: crdb:dda3d2f6-d1f3-4ecd-ab86-2399d16c1dcc
  ---> Status changed: started -> finished

The task status command shows the status of the task with the specified task ID.

To see the status of a task, run:

crdb-cli task status --task-id <task-ID>

For example:

# crdb-cli task status --task-id ef6c6088-72e3-4d32-8d62-23a665cb9eb1
Task-ID: ef6c6088-72e3-4d32-8d62-23a665cb9eb1
CRDB-GUID: d1053041-1c55-4b65-9ab9-f56b63afb55c
Status: started