Skip to content

Commit 4b93197

Browse files
aimurphyaimurphy
authored
DOC-5248, DOC-5249 prep - Replace emojis, restructure product-specific migration guidance (#206)
* cqlsh * prepare dse, mc pages for next stage * replace emojis * fix attribute
1 parent ad26964 commit 4b93197

10 files changed

+174
-95
lines changed

‎antora.yml

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,7 @@ asciidoc:
1919
dse-short: 'DSE'
2020
hcd: 'Hyper-Converged Database (HCD)'
2121
hcd-short: 'HCD'
22-
mc: 'Mission Control (MC)'
23-
mc-short: 'MC'
24-
mc-brief: 'Mission Control'
22+
mc: 'Mission Control'
2523
#Astra DB attributes
2624
astra-db: 'Astra DB'
2725
astra: 'Astra'

‎modules/ROOT/nav.adoc

Lines changed: 4 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,10 @@
11
.Get started
22
* xref:ROOT:components.adoc[]
33
* xref:ROOT:zdm-proxy-migration-paths.adoc[]
4-
* Product-specific migration paths
5-
** xref:ROOT:astra-migration-paths.adoc[]
6-
** {dse-short} 6.9
7-
*** xref:6.9@dse:tooling:migration-path-dse.adoc[{dse-short} 6.9 migration tools]
8-
*** xref:6.9@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.9]
9-
** {dse-short} 6.8
10-
*** xref:6.8@dse:tooling:migration-path-dse.adoc[{dse-short} 6.8 migration tools]
11-
*** xref:6.8@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.8]
12-
** {dse-short} 5.1
13-
*** xref:5.1@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 5.1]
14-
** {mc-brief} migrations
15-
*** xref:mission-control:migrate:oss-cass-to-mission-control.adoc[Migrate {cass-short} clusters to {mc-short}]
16-
*** xref:mission-control:migrate:dse-to-mission-control.adoc[Migrate {dse-short} clusters to {mc-short}]
4+
* xref:ROOT:astra-migration-paths.adoc[]
5+
* xref:ROOT:dse-migration-paths.adoc[]
6+
//* xref:ROOT:hcd-migration-paths.adoc[]
7+
* xref:ROOT:mc-migration-paths.adoc[]
178
189
.{product}
1910
* xref:ROOT:introduction.adoc[]

‎modules/ROOT/pages/astra-migration-paths.adoc

Lines changed: 60 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
= {astra} Migration Toolkit
2-
:description: Learn which migration tools are compatible with your origin cluster.
1+
= {astra} migration toolkit
2+
:description: Learn which migration tools you can use to migrate data to {astra}.
33

4-
The {astra} Migration Toolkit includes all xref:ROOT:components.adoc[{company} migration tools] that are designed to help you migrate your data to {astra-db}.
4+
The {astra} migration toolkit includes all xref:ROOT:components.adoc[{company} migration tools] that are designed to help you migrate your data to {astra-db}.
55

66
== Migration tool compatibility
77

@@ -12,94 +12,94 @@ Use the following table to learn which tools are compatible with your current da
1212
|Origin |{sstable-sideloader} |{cass-migrator} |{product-proxy} |{dsbulk-migrator}/{dsbulk-loader}
1313

1414
|Aiven for {cass-short}
15-
|✅
16-
|✅
17-
|✅
18-
|✅
15+
|icon:check[role="text-success",alt="Supported"]
16+
|icon:check[role="text-success",alt="Supported"]
17+
|icon:check[role="text-success",alt="Supported"]
18+
|icon:check[role="text-success",alt="Supported"]
1919

2020
|Amazon Keyspaces
21-
|❌
22-
|✅
23-
|✅
24-
|✅
21+
|icon:ban[role="text-tertiary",alt="Not supported"]
22+
|icon:check[role="text-success",alt="Supported"]
23+
|icon:check[role="text-success",alt="Supported"]
24+
|icon:check[role="text-success",alt="Supported"]
2525

2626
|{cass-reg} OSS 3.11 or later
27-
|✅
28-
|✅
29-
|✅
30-
|✅
27+
|icon:check[role="text-success",alt="Supported"]
28+
|icon:check[role="text-success",alt="Supported"]
29+
|icon:check[role="text-success",alt="Supported"]
30+
|icon:check[role="text-success",alt="Supported"]
3131

3232
|{cass-reg} OSS 3.10 or earlier
33-
|❌
34-
|✅
35-
|✅
36-
|✅
33+
|icon:ban[role="text-tertiary",alt="Not supported"]
34+
|icon:check[role="text-success",alt="Supported"]
35+
|icon:check[role="text-success",alt="Supported"]
36+
|icon:check[role="text-success",alt="Supported"]
3737

3838
|Azure Cosmos DB ({cass-short} API)
39-
|❌
40-
|✅
41-
|✅
42-
|✅
39+
|icon:ban[role="text-tertiary",alt="Not supported"]
40+
|icon:check[role="text-success",alt="Supported"]
41+
|icon:check[role="text-success",alt="Supported"]
42+
|icon:check[role="text-success",alt="Supported"]
4343

4444
|Azure Managed Instance for {cass}
45-
|✅
46-
|✅
47-
|✅
48-
|✅
45+
|icon:check[role="text-success",alt="Supported"]
46+
|icon:check[role="text-success",alt="Supported"]
47+
|icon:check[role="text-success",alt="Supported"]
48+
|icon:check[role="text-success",alt="Supported"]
4949

5050
|{dse-short} 5.1 or later
51-
|✅
52-
|✅
53-
|✅
54-
|✅
51+
|icon:check[role="text-success",alt="Supported"]
52+
|icon:check[role="text-success",alt="Supported"]
53+
|icon:check[role="text-success",alt="Supported"]
54+
|icon:check[role="text-success",alt="Supported"]
5555

5656
|{dse-short} 5.0 or earlier
57-
|❌
58-
|✅
59-
|✅
60-
|✅
57+
|icon:ban[role="text-tertiary",alt="Not supported"]
58+
|icon:check[role="text-success",alt="Supported"]
59+
|icon:check[role="text-success",alt="Supported"]
60+
|icon:check[role="text-success",alt="Supported"]
6161

6262
|Instaclustr Managed {cass-short}
63-
|✅
64-
|✅
65-
|✅
66-
|✅
63+
|icon:check[role="text-success",alt="Supported"]
64+
|icon:check[role="text-success",alt="Supported"]
65+
|icon:check[role="text-success",alt="Supported"]
66+
|icon:check[role="text-success",alt="Supported"]
6767

6868
|K8ssandra (self-managed)
69-
|✅
70-
|✅
71-
|✅
72-
|✅
69+
|icon:check[role="text-success",alt="Supported"]
70+
|icon:check[role="text-success",alt="Supported"]
71+
|icon:check[role="text-success",alt="Supported"]
72+
|icon:check[role="text-success",alt="Supported"]
7373

7474
|Scylla Cloud
75-
|❌
76-
|✅
77-
|✅
78-
|✅
75+
|icon:ban[role="text-tertiary",alt="Not supported"]
76+
|icon:check[role="text-success",alt="Supported"]
77+
|icon:check[role="text-success",alt="Supported"]
78+
|icon:check[role="text-success",alt="Supported"]
7979

8080
|Scylla OSS or Enterprise
81-
|❌
82-
|✅
83-
|✅
84-
|✅
81+
|icon:ban[role="text-tertiary",alt="Not supported"]
82+
|icon:check[role="text-success",alt="Supported"]
83+
|icon:check[role="text-success",alt="Supported"]
84+
|icon:check[role="text-success",alt="Supported"]
8585

8686
|Yugabyte Aeon (YCQL)
87-
|❌
88-
|✅
89-
|✅
90-
|✅
87+
|icon:ban[role="text-tertiary",alt="Not supported"]
88+
|icon:check[role="text-success",alt="Supported"]
89+
|icon:check[role="text-success",alt="Supported"]
90+
|icon:check[role="text-success",alt="Supported"]
9191

9292
|Yugabyte OSS or Anywhere
93-
|❌
94-
|✅
95-
|✅
96-
|✅
93+
|icon:ban[role="text-tertiary",alt="Not supported"]
94+
|icon:check[role="text-success",alt="Supported"]
95+
|icon:check[role="text-success",alt="Supported"]
96+
|icon:check[role="text-success",alt="Supported"]
9797

9898
|===
9999

100100
== Get support for your migration
101101

102-
If you have questions about migrating from a specific source to {astra-db}, contact your {company} account representative, {support-url}[{company} Support], or an https://www.datastax.com/products/datastax-astra/migration-toolkit[{astra} Migration Toolkit expert].
102+
If you have questions about migrating from a specific source to {astra-db}, contact your {company} account representative, {support-url}[{company} Support], or an https://www.datastax.com/products/datastax-astra/migration-toolkit[{astra} migration toolkit expert].
103103

104104
== See also
105105

‎modules/ROOT/pages/connect-clients-to-proxy.adoc

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -196,34 +196,34 @@ For more information, see the https://github.com/absurdfarce/themis/blob/main/RE
196196
In addition to any utility as a validation tool, Themis also serves as an example of a larger client application which uses the Java driver to connect to a {product-proxy} -- as well as directly to {cass-short} clusters or {astra-db} -- and perform operations.
197197
The configuration logic as well as the cluster and session management code have been cleanly separated into distinct packages to make them easy to understand.
198198

199-
== Connect the CQL shell to {product-proxy}
199+
== Connect cqlsh to {product-proxy}
200200

201-
CQL shell (`cqlsh`) is a command-line tool that you can use to send {cass-short} Query Language (CQL) statements to your {cass-short}-based clusters, including {astra-db}, {dse-short}, {hcd-short}, and {cass} databases.
201+
`cqlsh` is a command-line tool that you can use to send {cass-short} Query Language (CQL) statements to your {cass-short}-based clusters, including {astra-db}, {dse-short}, {hcd-short}, and {cass} databases.
202202

203-
You can use your database's included version of CQL shell, or you can download and run the standalone CQL shell.
203+
You can use your database's included version of `cqlsh`, or you can download and run a standalone `cqlsh`.
204204

205205
Your origin and target clusters must have a common `cql_version` between them.
206-
If there is no CQL version that is compatible with both clusters, CQL shell won't be able to connect to {product-proxy}.
206+
If there is no CQL version that is compatible with both clusters, `cqlsh` won't be able to connect to {product-proxy}.
207207

208-
To connect CQL shell to a {product-proxy} instance, do the following:
208+
To connect `cqlsh` to a {product-proxy} instance, do the following:
209209

210-
. On a machine that can connect to your {product-proxy} instance, https://downloads.datastax.com/#cqlsh[download CQL shell].
210+
. On a machine that can connect to your {product-proxy} instance, https://downloads.datastax.com/#cqlsh[download `cqlsh`].
211211
+
212-
Any version of CQL shell can connect to {product-proxy}, but some clusters require a specific CQL shell version.
212+
Any version of `cqlsh` can connect to {product-proxy}, but some clusters require a specific `cqlsh` version.
213213

214-
. Install CQL shell by extracting the downloaded archive:
214+
. Install `cqlsh` by extracting the downloaded archive:
215215
+
216216
[source,shell,subs="+quotes"]
217217
----
218218
tar -xvf **CQLSH_ARCHIVE**
219219
----
220220
+
221-
Replace `**CQLSH_ARCHIVE**` with the file name of the downloaded CQL shell archive, such as `cqlsh-astra-20210304-bin.tar.gz`.
221+
Replace `**CQLSH_ARCHIVE**` with the file name of the downloaded `cqlsh` archive, such as `cqlsh-astra-20210304-bin.tar.gz`.
222222

223-
. Change to the `bin` directory in your CQL shell installation directory.
224-
For example, if you installed CQL shell for {astra-db}, you would run `cd cqlsh-astra/bin`.
223+
. Change to the `bin` directory in your `cqlsh` installation directory.
224+
For example, if you installed `cqlsh` for {astra-db}, you would run `cd cqlsh-astra/bin`.
225225

226-
. Launch CQL shell:
226+
. Launch `cqlsh`:
227227
+
228228
[source,shell,subs="+quotes"]
229229
----
@@ -245,8 +245,8 @@ If you are using the default port, 9042, you can omit this argument.
245245
+
246246
[IMPORTANT]
247247
====
248-
If you need to provide credentials for an {astra-db} database, don't use the {scb-short} when attempting to connect CQL shell to {product-proxy}.
248+
If you need to provide credentials for an {astra-db} database, don't use the {scb-short} when attempting to connect `cqlsh` to {product-proxy}.
249249
Instead, use the token-based authentication option explained in <<expected-authentication-credentials-for-astra-db>>.
250250
251-
If you include the {scb-short}, CQL shell ignores all other connection arguments and connects exclusively to your {astra-db} database instead of {product-proxy}.
251+
If you include the {scb-short}, `cqlsh` ignores all other connection arguments and connects exclusively to your {astra-db} database instead of {product-proxy}.
252252
====

‎modules/ROOT/pages/connect-clients-to-target.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
:navtitle: Phase 5: Connect client applications directly to the target
33
:page-tag: migration,zdm,zero-downtime,zdm-proxy,connect-apps,target
44

5+
//TODO: Add HCD (driver or data API) and Astra (Data API) options
6+
57
At this point in our migration phases, we've completed:
68

79
* Phase 1: Connected client applications to {product-proxy}, which included setting up Ansible playbooks with {product-utility} and using {product-automation} to deploy the {product-proxy} instances with the Docker container.

‎modules/ROOT/pages/create-target.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,8 +82,8 @@ For more information, see xref:astra-db-serverless:cql:develop-with-cql.adoc[CQL
8282
To help you prepare the schema from the DDL in your origin cluster, consider using the `generate-ddl` functionality in the {dsbulk-migrator-repo}[{dsbulk-migrator}].
8383
However, this tool doesn't automatically convert MVs or indexes.
8484

85-
CQL statements, such as those used to reproduce the schema on the target database, can be executed in {astra-db} using the built-in CQL shell or the standalone CQL shell.
86-
For more information, see xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[CQL for {astra-db}: CQL shell].
85+
CQL statements, such as those used to reproduce the schema on the target database, can be executed in {astra-db} using the built-in or standalone CQL shell (`cqlsh`).
86+
For more information, see xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[CQL for {astra-db}].
8787

8888
== Using a generic CQL cluster as the target
8989

‎modules/ROOT/pages/dse-migration-paths.adoc

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
= {dse-short} migration toolkit
2+
:description: Learn which migration tools you can use to migrate data to and from {dse-short}.
3+
4+
The {dse} migration toolkit includes the xref:ROOT:components.adoc[{company} migration tools] that you can use to migrate your data across {dse-short} and another {cass-reg}-based database, such as {astra-db} or {hcd-short}.
5+
6+
This documentation doesn't describe _all_ possible migration paths; it focuses on migrations using {company} migration tools like {product-proxy}.
7+
8+
== Migrate your data
9+
10+
The tools and process for data migration to or from {dse-short} depends on your {dse-short} version and the other database's platform or version.
11+
12+
[TIP]
13+
====
14+
For information about clusters that are eligible for {product} to or from {dse-short}, see xref:ROOT:zdm-proxy-migration-paths.adoc[].
15+
====
16+
17+
[tabs]
18+
======
19+
Migrate data to {dse-short}::
20+
+
21+
--
22+
The following information provides guidance on migrations _to_ {dse-short}.
23+
24+
Generally, {company} recommends migrating to the latest version of {dse-short}, unless you have a compatibility issue that requires an interim migration to an earlier version before upgrading.
25+
26+
//TODO: Resolve duplication and replace these at the source with one summary page that points to here.
27+
28+
* {dse-short} 6.9
29+
+
30+
** xref:6.9@dse:tooling:migration-path-dse.adoc[{dse-short} 6.9 migration tools]
31+
** xref:6.9@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.9]
32+
33+
* {dse-short} 6.8
34+
+
35+
** xref:6.8@dse:tooling:migration-path-dse.adoc[{dse-short} 6.8 migration tools]
36+
** xref:6.8@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.8]
37+
38+
* {dse-short} 5.1
39+
+
40+
** xref:5.1@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 5.1]
41+
--
42+
43+
Migrate data from {dse-short}::
44+
+
45+
--
46+
When migrating _from_ {dse-short} to another {cass-short}-based database, follow the migration guidance for your target database to determine cluster compatibility, migration options, and recommendations.
47+
For example, for {astra-db}, see xref:ROOT:astra-migration-paths.adoc[].
48+
49+
If your target database isn't directly compatible with a migration from {dse-short}, you might need to take interim steps to prepare your data for migration, such as upgrading your {dse-short} version or modifying the data in your existing database to be compatible with the target database.
50+
--
51+
======
52+
53+
== Migrate your code
54+
55+
After migrating your data, your applications can connect exclusively to your new databases.
56+
57+
If you are already using a xref:datastax-drivers:compatibility:driver-matrix.adoc[compatible {cass-short} driver], you can modify the driver connection string to connect to the new databases.
58+
For some migrations, changing the connection string might be the only change you need to make to your code.
59+
However, you might want to update your code to take advantage of features and improvements available in your new database platform or a newer driver version.
60+
61+
For database-specific connection information, see the documentation for your target database and version.
62+
63+
== Get support for your migration
64+
65+
If you have questions about your {dse-short} migration, contact your {company} account representative or {support-url}[{company} Support].
66+
67+
== See also
68+
69+
* xref:ROOT:mc-migration-paths.adoc[]

‎modules/ROOT/pages/mc-migration-paths.adoc

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
= {mc} migration toolkit
2+
:description: Learn about migrating your {cass-reg}-based clusters to {mc}.
3+
4+
{mc} is an infrastructure management platform that you can use to manage your {cass-reg}-based clusters, including {cass-short}, {dse-short}, and {hcd-short} clusters.
5+
6+
{mc} isn't required, but it can be helpful depending on your preferences for infrastructure management.
7+
Additionally, {mc} isn't applicable to {astra-db}, which has its own interface for database management and administration.
8+
9+
== Migrate clusters to {mc}
10+
11+
Cluster migration moves your entire cluster from one infrastructure to another, including its data.
12+
**It is meant as an infrastructure migration only, not a database software migration.**
13+
14+
If you are migrating both your infrastructure _and_ your database software, create your new cluster in {mc}, and then migrate your data from your old cluster directly to the new cluster on {mc}.
15+
16+
For information about migrating your infrastructure to {mc}, see the following:
17+
18+
* xref:mission-control:migrate:oss-cass-to-mission-control.adoc[Migrate {cass-short} clusters to {mc}]
19+
* xref:mission-control:migrate:dse-to-mission-control.adoc[Migrate {dse-short} and other {cass-short}-based clusters to {mc}]

‎modules/ROOT/pages/troubleshooting-tips.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@ This flag will prevent you from accessing the logs when {product-proxy} stops or
149149

150150
Querying `system.peers` and `system.local` can help you investigate {product-proxy} configuration issues:
151151

152-
. xref:ROOT:connect-clients-to-proxy.adoc#connect-the-cql-shell-to-zdm-proxy[Connect CQL shell to a {product-proxy} instance.]
152+
. xref:ROOT:connect-clients-to-proxy.adoc#connect-the-cql-shell-to-zdm-proxy[Connect CQL shell (`cqlsh`) to a {product-proxy} instance.]
153153

154154
. Query `system.peers`:
155155
+

‎modules/sideloader/partials/sideloader-partials.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ It is important to use the specific node name to ensure that each node has a uni
2323
// end::command-placeholders-common[]
2424
2525
// tag::validate[]
26-
After the migration is complete, you can query the migrated data using the xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[CQL shell] or xref:astra-db-serverless:api-reference:row-methods/find-many.adoc[{data-api}].
26+
After the migration is complete, you can query the migrated data using the xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[CQL shell] (`cqlsh`) or xref:astra-db-serverless:api-reference:row-methods/find-many.adoc[{data-api}].
2727

2828
You can xref:ROOT:cassandra-data-migrator.adoc#cdm-validation-steps[run {cass-migrator} ({cass-migrator-short}) in validation mode] for more thorough validation.
2929
{cass-migrator-short} also offers an AutoCorrect mode to reconcile any differences that it detects.
@@ -96,7 +96,7 @@ If all steps finish successfully, the migration is complete and you can access t
9696

9797
// tag::no-return[]
9898
You can abort a migration up until the point at which {sstable-sideloader} starts importing SSTable metadata.
99-
After this point, you must wait for the migration to finish, and then you can use the CQL shell to drop the keyspace/table in your target database before repeating the entire migration procedure.
99+
After this point, you must wait for the migration to finish, and then you can use `cqlsh` to drop the keyspace/table in your target database before repeating the entire migration procedure.
100100
// end::no-return[]
101101

102102
// tag::sideloader-zdm[]

0 commit comments

Comments
 (0)