Create the target environment for your migration

In this phase of the migration, you must create and prepare a new database (cluster) to be the target for your migration. You must also gather authentication credentials to allow ZDM Proxy and your client applications to connect to the new database.

Prepare the target database

The preparation steps depend on your target database platform.

Use an Astra DB database as the target
Use a generic CQL cluster as the target

To migrate data to an Astra DB database, do the following:

Sign in to your Astra account.

You can use any subscription plan tier. However, the Pay As You Go and Enterprise plans offer premium features that can facilitate your migration, including support for Astra DB Sideloader, more databases, and no automatic database hibernation. These plans also support advanced features like customer-managed encryption keys and metrics exports. For more information, see Astra DB Serverless billing and usage.
Create an Astra DB Serverless database with your preferred database name, keyspace name, region, and other details.

The keyspace is a handle that establishes the database’s context in subsequent DDL and DML statements.

For multi-region databases, see Considerations for multi-region migrations.
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, ZDM Proxy, and ZDM Proxy Automation to read and write to your target database.

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.

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.

Your client application uses the SCB to connect directly to Astra DB near the end of the migration, and Cassandra Data Migrator and DSBulk Migrator use the SCB to migrate and validate data in Astra DB.

Use scp to copy the SCB to your client application instance:

scp -i <your_ssh_key> /path/to/scb.zip <linux user>@<public IP of client application instance>:

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.

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. For instructions, see Manage keyspaces.
- You can use Astra DB’s built-in or standalone cqlsh to issue typical CQL statements 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 table properties, such as compaction strategy and gc_grace_seconds, when creating tables in Astra DB because CQL for Astra DB ignores all unsupported values.
- Astra DB doesn’t support Materialized Views (MVs) and certain types of indexes. You must replace these with supported indexes. For more information, see Limitations on CQL for Astra DB.

If you plan to use Astra DB Sideloader for your data migration, you can find more information and specific requirements in Migrate data with Astra DB Sideloader: Configure the target database.
To help you prepare the schema from the DDL in your origin cluster, consider using the generate-ddl functionality in the DSBulk Migrator. However, this tool doesn’t automatically convert MVs or indexes.

ZDM can be used to migrate to any type of CQL cluster, running in any cloud or on-premise.

To migrate data to any other generic CQL cluster, such as HCD or OSS Cassandra, do the following:

Provision infrastructure, and then create the new cluster with your desired database platform version and 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.
Create your cluster using your desired CQL cluster version. For specific infrastructure, installation, and configuration instructions, see the documentation for your infrastructure platform, database platform, and database platform version. Pay particular attention to the configuration that must be done at installation time.

Configure your new cluster as desired.

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.

For multi-region clusters, see Considerations for multi-region migrations.

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, create a user with the required permissions for your client application to use to read and write to the cluster.
Recreate your client application’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 match 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.

If you are migrating from an old 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 your driver’s changelog or release notes.

Considerations for multi-region migrations

Multi-region migrations require additional planning and action depending on factors like the amount of data, number of regions, data consistency requirements, and orchestration of multi-region traffic.

Multi-region migrations can include one or more of the following scenarios:

Your origin cluster is deployed to multiple regions, with or without enforced consistency.
Your target database is, or will be, deployed to multiple regions.
You need to support multiple regions in a live migration scenario.
You are migrating to Astra DB, and you need to prepare to follow the eventual consistency model for multi-region databases.

For relatively small migrations to Astra DB with consistent data across all regions, you can migrate the primary region first, and then add additional regions after the initial migration is complete. This strategy allows Astra DB’s eventual consistency model to replicate the data from the primary region to the additional regions. However, this approach isn’t suitable for all migrations.

It is difficult to provide a one-size-fits-all solution for multi-region migrations due to the potential complexity and variability of these scenarios. For assistance planning a multi-region migration, contact your DataStax account representative or DataStax Support.

Next steps

Understand the rollback options