What you will learn
Use DSBulk with Cassandra-compatible source and target clusters. The worked example copies a small, non-expiring tutorial.events table. Production TTLs, counters, collections, timestamps, and concurrent changes require separate mapping and correctness tests.
Before you begin
Install a DSBulk release compatible with both clusters and its required Java runtime. Prepare protected source.conf and target.conf files using that release’s connection, authentication, TLS, and local-datacenter options. Do not embed passwords in commands. Create /srv/migration/events as a new export directory with enough space. The target table must already exist.
1. Define this migration’s boundary
Reload into an empty comparison table first. A load is an upsert, not a replacement: rows that exist only in the target remain there. Do not use a blind truncate as preparation for a production reload.
2. Prepare a reproducible sample
CREATE TABLE tutorial.events (tenant_id text, event_id int, message text, PRIMARY KEY (tenant_id,event_id));
INSERT INTO tutorial.events (tenant_id,event_id,message) VALUES ('demo',1,'ready');
Create the table in both clusters after creating an appropriately replicated keyspace. Insert the sample only in the source. For an existing table, capture its DDL instead of issuing CREATE again; compare partition and clustering keys before loading.
3. Export with a named mapping
dsbulk unload -f source.conf -k tutorial -t events \
-m "tenant_id,event_id,message" -url /srv/migration/events
Keep the command’s exit status and operation log. Confirm successful record counts and inspect rejected records. Keep the CSV header, delimiter, quoting, encoding, and mapping together as part of the migration artifact.
4. Import and compare
dsbulk load -f target.conf -k tutorial -t events \
-m "tenant_id,event_id,message" -url /srv/migration/events
dsbulk count -f source.conf -k tutorial -t events
dsbulk count -f target.conf -k tutorial -t events
Use counts on the small quiesced lab dataset; large counts scan data and should be scheduled. Compare selected full partitions and application queries as well. Equal counts can still hide different keys or values.
5. Handle the write boundary
For the offline procedure, stop writers before the final export and keep them stopped through reconciliation. Switch the application only after target acceptance. A live export alone neither captures later writes nor removes deleted source rows from the destination. Explicitly design any online delta path rather than assuming the bulk loader supplies it.
Example output
The following is an illustrative, normalized lab result, not output captured from a live customer system. Your versions, addresses, timings, and row counts will differ.
Condensed load summary for the one-row lab:
total | failed
1 | 0
Source count: 1
Target count: 1
Target partition:
tenant_id | event_id | message
demo | 1 | ready
The summary is shortened for readability; retain the full DSBulk operation log in a real run. Zero failed records and equal counts are useful checks, but compare keys and values too. A target count of 2 in this one-row exercise can indicate stale target data, not an export failure.
Verify the result
The loader reports no unreviewed failures, the sample partition matches, and the application can connect and perform its required reads/writes. Check null values, non-ASCII text, and edge-size records. For expiring data, test remaining TTL and write-time behavior; the default lab copy does not preserve these semantics automatically.
Troubleshooting
A mapping error usually indicates mismatched headers, column names, or types. Authentication errors require checking the protected connection files. Timeouts under load call for lower throughput and storage/compaction review. Review failed-record logs before retrying a batch; retries may alter timestamps or expirations.
Recovery and next steps
Before target writes begin, keep or restore the source as the service endpoint. Once the target accepts writes, switching back requires reconciliation of those writes; it is no longer a configuration-only rollback. Retain the export, logs, schema, and acceptance record until the migration is closed.