Zero Downtime Migration (ZDM) Proxy is an open-source component developed in Go and based on client-server architecture. It enables you to migrate from one Apache Cassandra® cluster to another without downtime or code changes in the application client.

For details on ZDM Proxy, see zdm-proxy GitHub.

When using ZDM Proxy, the client connects to the proxy rather than to the source cluster. The proxy connects both to the source cluster and the target cluster. It sends read requests to the source cluster only, while write requests are forwarded to both clusters.

For details on how ZDM Proxy works, see Introduction to Zero Downtime Migration.

• Apache Cassandra instance to migrate to the Aiven platform (migration source)
• Aiven for Apache Cassandra service where to migrate your external instance (migration target)
• Aiven CLI client installed
• cqlsh installed

Connect to your Aiven for Apache Cassandra service using cqlsh, for example.

cqlsh --ssl-u avnadmin -p YOUR_SECRET_PASSWORD cassandra-target-cluster-name.a.avns.net 12345

You can expect to receive output similar to the following:

Connected to a1b2c3d4-1a2b-3c4d-5e6f-a1b2c3d4e5f6 at cassandra-target-cluster-name.a.avns.net:12345
[cqlsh 6.1.0 | Cassandra 4.0.11 | CQL spec 3.4.5 | Native protocol v5]

In your target service, create the same keyspaces and tables you have in your source Apache Cassandra cluster.

create keyspace KEYSPACE_NAME with replication ={'class':'SimpleStrategy', 'replication_factor':3};
create table KEYSPACE_NAME.TABLE_NAME (n_id int, value int, primary key (n_id));

Download the ZDM Proxy's binary from ZDM Proxy releases.

wget https://github.com/datastax/zdm-proxy/releases/download/v2.1.0/zdm-proxy-linux-amd64-v2.1.0.tgz
tar xf zdm-proxy-linux-amd64-v2.1.0.tgz

Check if the binary has been downloaded successfully using ls in the relevant directory. You can expect to receive output similar to the following:

LICENSE  zdm-proxy-linux-amd64-v2.1.0.tgz  zdm-proxy-v2.1.0

1. Specify connection information by setting ZDM_TARGET_* and ZDM_ORIGIN_* environment variables using the export command.

   note

   ORIGIN refers to the source service.

2. Run the binary.

exportZDM_ORIGIN_CONTACT_POINTS=localhost
exportZDM_ORIGIN_USERNAME=cassandra
exportZDM_ORIGIN_PASSWORD=cassandra
exportZDM_ORIGIN_PORT=1234
exportZDM_TARGET_CONTACT_POINTS=cassandra-target-cluster-name.a.avns.net
exportZDM_TARGET_USERNAME=avnadmin
exportZDM_TARGET_PASSWORD=YOUR_SECRET_PASSWORD
exportZDM_TARGET_PORT=12345
exportZDM_TARGET_TLS_SERVER_CA_PATH="/tmp/ca.pem"
exportZDM_TARGET_ENABLE_HOST_ASSIGNMENT=false
# ZDM_ORIGIN_ENABLE_HOST_ASSIGNMENT=false  # (may be needed, see note)
./zdm-proxy-v2.1.0

To connect to ZDM Proxy, use, for example, cqlsh. Provide connection details and, if your source or target require authentication, specify target username and password.

Check more details on using the credentials in Client application credentials.

The port that ZDM Proxy uses is 14002, which can be overridden.

1. Connect using ZDM Proxy.

   cqlsh -u avnadmin -p YOUR_SECRET_PASSWORD localhost 14002
   

   You can expect to receive output similar to the following:

   Connected to CLUSTER_NAME at localhost:14002
   [cqlsh 6.1.0 | Cassandra 4.1.3 | CQL spec 3.4.6 | Native protocol v4]
   

2. Check data in the table.

   select * from KEYSPACE_NAME.TABLE_NAME;
   

   You can expect to receive output similar to the following:

   n_id | value
   ------+-------
   1|42
   2|44
   3|46
   (3 rows)
   

3. Insert more data into the table to test how ZDM Proxy handles write request.

   insert into KEYSPACE_NAME.TABLE_NAME (n_id, value) values (4, 48);
   insert into KEYSPACE_NAME.TABLE_NAME (n_id, value) values (5, 50);
   

4. Check again data inside the table.

   select * from KEYSPACE_NAME.TABLE_NAME;
   

   You can expect to receive output similar to the following:

   n_id | value
   ------+-------
   5|50
   1|42
   2|44
   4|48
   3|46
   (5 rows)
   

1. Connect to the source:

   cqlsh localhost 1234
   

   You can expect to receive output similar to the following:

   Connected to SOURCE_CLUSTER_NAME at localhost:1234
   [cqlsh 6.1.0 | Cassandra 4.1.3 | CQL spec 3.4.6 | Native protocol v5]
   

2. Check data in the table:

   select * from KEYSPACE_NAME.TABLE_NAME;
   

   You can expect to receive output similar to the following:

   n_id | value
   ------+-------
   5|50
   1|42
   2|44
   4|48
   3|46
   (5 rows)
   

   ZDM Proxy has forwarded both the write request and the read request to the source cluster. As a result, all the values are there: both newly-added ones (50 and 48) and previously added ones (42, 44, and 46).

1. Connect to the target service.

   cqlsh --ssl-u avnadmin -p YOUR_SECRET_PASSWORD cassandra-target-cluster-name.a.avns.net 12345
   

   You can expect to receive output similar to the following:

   Connected to a1b2c3d4-1a2b-3c4d-5e6f-a1b2c3d4e5f6 at cassandra-target-cluster-name.a.avns.net:12345
   [cqlsh 6.1.0 | Cassandra 4.0.11 | CQL spec 3.4.5 | Native protocol v5]
   

2. Check data in the table.

   select * from KEYSPACE_NAME.TABLE_NAME;
   

   You can expect to receive output similar to the following:

   n_id | value
   ------+-------
   5|50
   4|48
   (2 rows)
   

   50 and 48 are there in the target table since ZDM Proxy has forwarded the write request to the target service. 42, 44, and 46 are not there since ZDM Proxy has not sent the read request to the target service.

• zdm-proxy GitHub
• Introduction to Zero Downtime Migration
• ZDM Proxy releases
• Client application credentials