diff --git a/antora.yml b/antora.yml index 4c98e152..9cea5ad0 100644 --- a/antora.yml +++ b/antora.yml @@ -19,9 +19,7 @@ asciidoc: dse-short: 'DSE' hcd: 'Hyper-Converged Database (HCD)' hcd-short: 'HCD' - mc: 'Mission Control (MC)' - mc-short: 'MC' - mc-brief: 'Mission Control' + mc: 'Mission Control' #Astra DB attributes astra-db: 'Astra DB' astra: 'Astra' diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index cd6396d0..4c2c4fcf 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,19 +1,10 @@ .Get started * xref:ROOT:components.adoc[] * xref:ROOT:zdm-proxy-migration-paths.adoc[] -* Product-specific migration paths -** xref:ROOT:astra-migration-paths.adoc[] -** {dse-short} 6.9 -*** xref:6.9@dse:tooling:migration-path-dse.adoc[{dse-short} 6.9 migration tools] -*** xref:6.9@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.9] -** {dse-short} 6.8 -*** xref:6.8@dse:tooling:migration-path-dse.adoc[{dse-short} 6.8 migration tools] -*** xref:6.8@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.8] -** {dse-short} 5.1 -*** xref:5.1@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 5.1] -** {mc-brief} migrations -*** xref:mission-control:migrate:oss-cass-to-mission-control.adoc[Migrate {cass-short} clusters to {mc-short}] -*** xref:mission-control:migrate:dse-to-mission-control.adoc[Migrate {dse-short} clusters to {mc-short}] +* xref:ROOT:astra-migration-paths.adoc[] +* xref:ROOT:dse-migration-paths.adoc[] +//* xref:ROOT:hcd-migration-paths.adoc[] +* xref:ROOT:mc-migration-paths.adoc[] .{product} * xref:ROOT:introduction.adoc[] diff --git a/modules/ROOT/pages/astra-migration-paths.adoc b/modules/ROOT/pages/astra-migration-paths.adoc index 329d4e75..4d19ad53 100644 --- a/modules/ROOT/pages/astra-migration-paths.adoc +++ b/modules/ROOT/pages/astra-migration-paths.adoc @@ -1,7 +1,7 @@ -= {astra} Migration Toolkit -:description: Learn which migration tools are compatible with your origin cluster. += {astra} migration toolkit +:description: Learn which migration tools you can use to migrate data to {astra}. -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}. +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}. == Migration tool compatibility @@ -12,94 +12,94 @@ Use the following table to learn which tools are compatible with your current da |Origin |{sstable-sideloader} |{cass-migrator} |{product-proxy} |{dsbulk-migrator}/{dsbulk-loader} |Aiven for {cass-short} -|✅ -|✅ -|✅ -|✅ +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |Amazon Keyspaces -|❌ -|✅ -|✅ -|✅ +|icon:ban[role="text-tertiary",alt="Not supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |{cass-reg} OSS 3.11 or later -|✅ -|✅ -|✅ -|✅ +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |{cass-reg} OSS 3.10 or earlier -|❌ -|✅ -|✅ -|✅ +|icon:ban[role="text-tertiary",alt="Not supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |Azure Cosmos DB ({cass-short} API) -|❌ -|✅ -|✅ -|✅ +|icon:ban[role="text-tertiary",alt="Not supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |Azure Managed Instance for {cass} -|✅ -|✅ -|✅ -|✅ +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |{dse-short} 5.1 or later -|✅ -|✅ -|✅ -|✅ +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |{dse-short} 5.0 or earlier -|❌ -|✅ -|✅ -|✅ +|icon:ban[role="text-tertiary",alt="Not supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |Instaclustr Managed {cass-short} -|✅ -|✅ -|✅ -|✅ +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |K8ssandra (self-managed) -|✅ -|✅ -|✅ -|✅ +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |Scylla Cloud -|❌ -|✅ -|✅ -|✅ +|icon:ban[role="text-tertiary",alt="Not supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |Scylla OSS or Enterprise -|❌ -|✅ -|✅ -|✅ +|icon:ban[role="text-tertiary",alt="Not supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |Yugabyte Aeon (YCQL) -|❌ -|✅ -|✅ -|✅ +|icon:ban[role="text-tertiary",alt="Not supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |Yugabyte OSS or Anywhere -|❌ -|✅ -|✅ -|✅ +|icon:ban[role="text-tertiary",alt="Not supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] +|icon:check[role="text-success",alt="Supported"] |=== == Get support for your migration -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]. +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]. == See also diff --git a/modules/ROOT/pages/connect-clients-to-proxy.adoc b/modules/ROOT/pages/connect-clients-to-proxy.adoc index 809d9166..4a16a77d 100644 --- a/modules/ROOT/pages/connect-clients-to-proxy.adoc +++ b/modules/ROOT/pages/connect-clients-to-proxy.adoc @@ -196,34 +196,34 @@ For more information, see the https://github.com/absurdfarce/themis/blob/main/RE 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. 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. -== Connect the CQL shell to {product-proxy} +== Connect cqlsh to {product-proxy} -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. +`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. -You can use your database's included version of CQL shell, or you can download and run the standalone CQL shell. +You can use your database's included version of `cqlsh`, or you can download and run a standalone `cqlsh`. Your origin and target clusters must have a common `cql_version` between them. -If there is no CQL version that is compatible with both clusters, CQL shell won't be able to connect to {product-proxy}. +If there is no CQL version that is compatible with both clusters, `cqlsh` won't be able to connect to {product-proxy}. -To connect CQL shell to a {product-proxy} instance, do the following: +To connect `cqlsh` to a {product-proxy} instance, do the following: -. On a machine that can connect to your {product-proxy} instance, https://downloads.datastax.com/#cqlsh[download CQL shell]. +. On a machine that can connect to your {product-proxy} instance, https://downloads.datastax.com/#cqlsh[download `cqlsh`]. + -Any version of CQL shell can connect to {product-proxy}, but some clusters require a specific CQL shell version. +Any version of `cqlsh` can connect to {product-proxy}, but some clusters require a specific `cqlsh` version. -. Install CQL shell by extracting the downloaded archive: +. Install `cqlsh` by extracting the downloaded archive: + [source,shell,subs="+quotes"] ---- tar -xvf **CQLSH_ARCHIVE** ---- + -Replace `**CQLSH_ARCHIVE**` with the file name of the downloaded CQL shell archive, such as `cqlsh-astra-20210304-bin.tar.gz`. +Replace `**CQLSH_ARCHIVE**` with the file name of the downloaded `cqlsh` archive, such as `cqlsh-astra-20210304-bin.tar.gz`. -. Change to the `bin` directory in your CQL shell installation directory. -For example, if you installed CQL shell for {astra-db}, you would run `cd cqlsh-astra/bin`. +. Change to the `bin` directory in your `cqlsh` installation directory. +For example, if you installed `cqlsh` for {astra-db}, you would run `cd cqlsh-astra/bin`. -. Launch CQL shell: +. Launch `cqlsh`: + [source,shell,subs="+quotes"] ---- @@ -245,8 +245,8 @@ If you are using the default port, 9042, you can omit this argument. + [IMPORTANT] ==== -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}. +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}. Instead, use the token-based authentication option explained in <>. -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}. +If you include the {scb-short}, `cqlsh` ignores all other connection arguments and connects exclusively to your {astra-db} database instead of {product-proxy}. ==== \ No newline at end of file diff --git a/modules/ROOT/pages/connect-clients-to-target.adoc b/modules/ROOT/pages/connect-clients-to-target.adoc index bfee8d7f..0e94f7eb 100644 --- a/modules/ROOT/pages/connect-clients-to-target.adoc +++ b/modules/ROOT/pages/connect-clients-to-target.adoc @@ -2,6 +2,8 @@ :navtitle: Phase 5: Connect client applications directly to the target :page-tag: migration,zdm,zero-downtime,zdm-proxy,connect-apps,target +//TODO: Add HCD (driver or data API) and Astra (Data API) options + At this point in our migration phases, we've completed: * 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. diff --git a/modules/ROOT/pages/create-target.adoc b/modules/ROOT/pages/create-target.adoc index 2abad900..0af5d8d5 100644 --- a/modules/ROOT/pages/create-target.adoc +++ b/modules/ROOT/pages/create-target.adoc @@ -82,8 +82,8 @@ For more information, see xref:astra-db-serverless:cql:develop-with-cql.adoc[CQL 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}]. However, this tool doesn't automatically convert MVs or indexes. -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. -For more information, see xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[CQL for {astra-db}: CQL shell]. +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`). +For more information, see xref:astra-db-serverless:cql:develop-with-cql.adoc#connect-to-the-cql-shell[CQL for {astra-db}]. == Using a generic CQL cluster as the target diff --git a/modules/ROOT/pages/dse-migration-paths.adoc b/modules/ROOT/pages/dse-migration-paths.adoc new file mode 100644 index 00000000..6cd757fb --- /dev/null +++ b/modules/ROOT/pages/dse-migration-paths.adoc @@ -0,0 +1,69 @@ += {dse-short} migration toolkit +:description: Learn which migration tools you can use to migrate data to and from {dse-short}. + +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}. + +This documentation doesn't describe _all_ possible migration paths; it focuses on migrations using {company} migration tools like {product-proxy}. + +== Migrate your data + +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. + +[TIP] +==== +For information about clusters that are eligible for {product} to or from {dse-short}, see xref:ROOT:zdm-proxy-migration-paths.adoc[]. +==== + +[tabs] +====== +Migrate data to {dse-short}:: ++ +-- +The following information provides guidance on migrations _to_ {dse-short}. + +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. + +//TODO: Resolve duplication and replace these at the source with one summary page that points to here. + +* {dse-short} 6.9 ++ +** xref:6.9@dse:tooling:migration-path-dse.adoc[{dse-short} 6.9 migration tools] +** xref:6.9@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.9] + +* {dse-short} 6.8 ++ +** xref:6.8@dse:tooling:migration-path-dse.adoc[{dse-short} 6.8 migration tools] +** xref:6.8@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 6.8] + +* {dse-short} 5.1 ++ +** xref:5.1@dse:managing:operations/migrate-data.adoc[Migrate data to {dse-short} 5.1] +-- + +Migrate data from {dse-short}:: ++ +-- +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. +For example, for {astra-db}, see xref:ROOT:astra-migration-paths.adoc[]. + +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. +-- +====== + +== Migrate your code + +After migrating your data, your applications can connect exclusively to your new databases. + +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. +For some migrations, changing the connection string might be the only change you need to make to your code. +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. + +For database-specific connection information, see the documentation for your target database and version. + +== Get support for your migration + +If you have questions about your {dse-short} migration, contact your {company} account representative or {support-url}[{company} Support]. + +== See also + +* xref:ROOT:mc-migration-paths.adoc[] \ No newline at end of file diff --git a/modules/ROOT/pages/mc-migration-paths.adoc b/modules/ROOT/pages/mc-migration-paths.adoc new file mode 100644 index 00000000..656a1555 --- /dev/null +++ b/modules/ROOT/pages/mc-migration-paths.adoc @@ -0,0 +1,19 @@ += {mc} migration toolkit +:description: Learn about migrating your {cass-reg}-based clusters to {mc}. + +{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. + +{mc} isn't required, but it can be helpful depending on your preferences for infrastructure management. +Additionally, {mc} isn't applicable to {astra-db}, which has its own interface for database management and administration. + +== Migrate clusters to {mc} + +Cluster migration moves your entire cluster from one infrastructure to another, including its data. +**It is meant as an infrastructure migration only, not a database software migration.** + +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}. + +For information about migrating your infrastructure to {mc}, see the following: + +* xref:mission-control:migrate:oss-cass-to-mission-control.adoc[Migrate {cass-short} clusters to {mc}] +* xref:mission-control:migrate:dse-to-mission-control.adoc[Migrate {dse-short} and other {cass-short}-based clusters to {mc}] \ No newline at end of file diff --git a/modules/ROOT/pages/troubleshooting-tips.adoc b/modules/ROOT/pages/troubleshooting-tips.adoc index eabd0665..0c0a18ef 100644 --- a/modules/ROOT/pages/troubleshooting-tips.adoc +++ b/modules/ROOT/pages/troubleshooting-tips.adoc @@ -149,7 +149,7 @@ This flag will prevent you from accessing the logs when {product-proxy} stops or Querying `system.peers` and `system.local` can help you investigate {product-proxy} configuration issues: -. xref:ROOT:connect-clients-to-proxy.adoc#connect-the-cql-shell-to-zdm-proxy[Connect CQL shell to a {product-proxy} instance.] +. xref:ROOT:connect-clients-to-proxy.adoc#connect-the-cql-shell-to-zdm-proxy[Connect CQL shell (`cqlsh`) to a {product-proxy} instance.] . Query `system.peers`: + diff --git a/modules/sideloader/partials/sideloader-partials.adoc b/modules/sideloader/partials/sideloader-partials.adoc index 9fdfcdaa..4e583961 100644 --- a/modules/sideloader/partials/sideloader-partials.adoc +++ b/modules/sideloader/partials/sideloader-partials.adoc @@ -23,7 +23,7 @@ It is important to use the specific node name to ensure that each node has a uni // end::command-placeholders-common[] // tag::validate[] -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}]. +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}]. You can xref:ROOT:cassandra-data-migrator.adoc#cdm-validation-steps[run {cass-migrator} ({cass-migrator-short}) in validation mode] for more thorough validation. {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 // tag::no-return[] You can abort a migration up until the point at which {sstable-sideloader} starts importing SSTable metadata. -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. +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. // end::no-return[] // tag::sideloader-zdm[]