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.
-
Re-create the schema from your origin cluster on the target cluster.
-
Gather authentication credentials and connection details for the target cluster.
The following steps assume you are migrating to Astra DB Serverless. If that is not the case, see the ZDM documentation for your actual target cluster.
|
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. |
Prepare your target database
-
Sign in to the Astra Portal, and then switch to the organization where you want to create the new database.
ZDM Proxy can be used with any Astra plan. However, paid plans offer premium features that can facilitate your migration. For example, with a paid plan, Astra DB Serverless databases can use Astra DB Sideloader for data migration (Phase 2).
-
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 origin 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 Serverless 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 might use
scp:scp -i some-key.pem /path/to/scb.zip user@client-ip-or-host: -
Re-create your client application’s schema on your Astra DB Serverless 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:
-
In Astra, 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 the CQL shell (
cqlsh), Cassandra drivers, or the Data API to create tables. However, the only optional table properties that Astra supports aredefault_time_to_liveandcomment. As a best practice, omit unsupported DDL properties, such as compaction strategy andgc_grace_seconds, when creating tables in Astra. -
Astra 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.
-
Test the connection to the target cluster
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. For example, if you use a Cassandra driver, see the driver documentation to learn how to connect to Astra databases.
Additionally, DataStax recommends running performance tests and measuring benchmarks in a test environment where your client application is connected directly to your target cluster. ZDM Proxy inherently impacts latency, so it is important that you understand how your application workloads will perform on the new cluster without ZDM Proxy.
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 steps
After preparing the infrastructure for ZDM Proxy and your target cluster, begin Phase 1 of the migration by setting up ZDM Proxy Automation with ZDM Utility.
