Create the target environment

After you review the compatibility requirements and prepare the ZDM Proxy infrastructure, you must prepare your target cluster for the migration.

This includes the following:

Create the new cluster that will be the target of your migration.
Recreate the schema from your origin cluster on the target cluster.
Gather authentication credentials and connection details for the target cluster.

The preparation steps depend on your target platform.

For complex migrations, such as those that involve multi-datacenter clusters, many-to-one/one-to-many mappings, or unresolvable mismatched schemas, see the considerations for complex migrations.

Migrate to Astra
Migrate to HCD, DSE, or open-source Apache Cassandra®
Other CQL-compatible data stores

Sign in to the Astra Portal and switch to the organization where you want to create the new database.

ZDM Proxy can be used with any Astra subscription plan. However, paid plans offer premium features that can facilitate your migration, including support for Astra DB Sideloader, more databases, and no automatic database hibernation.
Create a database with your preferred database name, cloud provider, region, and other details.

All databases start with an initial keyspace. If the name of this keyspace doesn’t match your origin cluster’s schema, you can delete the initial keyspace after recreating the schema later in this process.
When your database reaches Active status, create an application token with a role like Read/Write User or Database Administrator, and then store the credentials (Client ID, Client Secret, and Token) securely.

These credentials are used by the client application and ZDM Proxy to read and write to your target database. Make sure the token’s role has sufficient permission to perform the actions required by your client application.

Download your database’s Secure Connect Bundle (SCB). The SCB is a zip file that contains TLS encryption certificates and other metadata required to connect to your database. It is used during and after the migration process to securely connect to your Astra DB database.

The SCB contains sensitive information that establishes a connection to your database, including key pairs and certificates. Treat it as you would any other sensitive values, such as passwords or tokens.

Use your preferred method to copy the SCB to your client application instance. For example, you could use scp:
```
scp -i some-key.pem /path/to/scb.zip user@client-ip-or-host:
```

Recreate your client application’s schema on your Astra DB database, including each keyspace and table that you want to migrate.

On your new database, the keyspace names, table names, column names, data types, and primary keys must be identical to the schema on the origin cluster or the migration will fail.

To help you prepare the schema from the DDL in your origin cluster, consider using the generate-ddl functionality in the DSBulk Migrator.

Note the following limitations and exceptions for tables in Astra DB:

In Astra DB, you must create keyspaces in the Astra Portal or with the DevOps API because CQL for Astra DB doesn’t support CREATE KEYSPACE.
You can use cqlsh, drivers, or the Data API to create tables in Astra DB. However, the only optional table properties that Astra DB supports are default_time_to_live and comment. As a best practice, omit unsupported DDL properties, such as compaction strategy and gc_grace_seconds, when creating tables in Astra DB.
Astra DB doesn’t support Materialized Views (MVs) and certain types of indexes. You must adjust your data model and application logic to discard or replace these structures before beginning your migration. For more information, see Limitations on CQL for Astra DB.
If you plan to use Astra DB Sideloader for Phase 2, see the target database configuration requirements for migrating data with Astra DB Sideloader.

Provision the cluster infrastructure, and then create your HCD, DSE, or Cassandra cluster with your desired configuration:

Determine the correct topology and specifications for your new cluster, and then provision infrastructure that meets those requirements. Your target infrastructure can be hosted on a cloud provider, in a private cloud, or on bare metal machines.

For specific infrastructure, installation, and configuration instructions, see the HCD, DSE, or Cassandra documentation.

Because ZDM Proxy supports separate connection details for each cluster, you can configure the new cluster as needed, independent of the origin cluster’s configuration. This is a good opportunity to establish your desired configuration state on the new cluster and implement new patterns that might have been unavailable or impractical on the old cluster, such as enabling authentication or configuring TLS encryption.

Recommended: Consider testing your new cluster to ensure it meets your performance requirements, and then tune it as necessary before beginning the migration.
If you enabled authentication in your cluster, create a user with the required permissions for your client application to use to read and write to the cluster.

Store the authentication credentials securely for use by your client application and ZDM Proxy later in the migration process.
Note your cluster’s connection details, including the contact points (IP addresses or hostnames) and port number.
Recreate your origin cluster’s schema on your new cluster, including each keyspace and table that you want to migrate.

On your new cluster, the keyspace names, table names, column names, data types, and primary keys must be identical to the schema on the origin cluster or the migration will fail.

To copy the schema, you can run CQL DESCRIBE on the origin cluster to get the schema that is being migrated, and then run the output on your new cluster. Alternatively, you can use the generate-ddl functionality in the DSBulk Migrator.

If your origin cluster is running an earlier version, you might need to edit CQL clauses that are no longer supported in newer versions, such as COMPACT STORAGE. For specific changes in each version, see the release notes for your database platform and Cassandra driver.

Support for other CQL-compatible data stores isn’t guaranteed for ZDM Proxy.

If your origin and target clusters meet the protocol version compatibility requirements, you might be able to use ZDM Proxy for your migration. As with any migration, DataStax recommends that you test this in isolation before attempting a full-scale production migration.

See your data store provider’s documentation for information about creating your cluster and schema, generating authentication credentials, and gathering the connection details.

After you create the target cluster, try connecting your client application directly to the target cluster without ZDM Proxy. This ensures that the connection will work when you disconnect ZDM Proxy at the end of the migration.

Additionally, DataStax recommends running performance tests and measuring benchmarks in a test environment where your client application is connected directly to your target cluster. This helps you understand how your application workloads will perform on the new cluster. This is particularly valuable when migrating to a new platform, such as DSE to Astra, where you might be unfamiliar with the platform’s performance characteristics.

Depending on the results of your tests, you might need to adjust your application logic, data model, or cluster configuration to achieve your performance goals. For example, you might need to optimize queries to avoid anti-patterns that were acceptable on your origin cluster but degrade performance on the target cluster.

Next, learn about rollback options before you begin Phase 1 of the migration process.

Create the target environment

Was this helpful?

Give Feedback