DOC-5089 driver prefix/redundancy stuff (#200)

* driver prefix/redundancy stuff

* Apply suggestions from code review

Co-authored-by: brian-f <[email protected]>

---------

Co-authored-by: brian-f <[email protected]>

Author: aimurphy

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

@@ -75,12 +75,6 @@ The following links provide some good starting points for learning about the int
 * The https://docs.datastax.com/en/developer/cpp-driver/latest/topics/[getting started section] of the C/C++ driver documentation.
 * The https://docs.datastax.com/en/developer/nodejs-driver/latest/#basic-usage[basic usage section] of the Node.js driver documentation.
 
-[TIP]
-====
-The links above lead to the documentation for the most recent version of each driver.
-You can find the documentation for earlier versions by selecting the appropriate version number from the drop-down menu in the upper right.
-====
-
 == Connect drivers to {product-proxy}
 
 We mentioned above that connecting to a {product-proxy} should be almost indistinguishable from connecting directly to your {cass-short} cluster.
@@ -143,8 +137,15 @@ As an alternative to providing the {scb-short} directly, you can xref:astra-db-s
 
 == Sample client applications
 
-The documentation for the {company} drivers provides information about how to connect these drivers to your {cass-short} cluster or {product-proxy} and how to use them to issue queries, update data and perform other actions.
-In addition to the smaller code samples provided in the documentation, we also provide a few sample client applications which demonstrate the use of the {company} Java driver to interact with {product-proxy} as well as the origin and target for that proxy.
+[IMPORTANT]
+====
+These sample applications are for demonstration purposes only.
+They are not intended for production use.
+====
+
+The following sample client applications demonstrate how to use the Java driver with {product-proxy} and the origin and target for that proxy.
+
+See your driver's documentation for code samples that are specific to your chosen driver, including cluster connection examples and statement execution examples.
 
 === {product-demo}
 

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

@@ -22,7 +22,10 @@ image::migration-phase5ra.png[In Phase 5, your apps no longer using the proxy an
 == Configuring your driver to connect to a generic CQL cluster
 
 If your target cluster is a generic CQL cluster, such as {cass-short} or {dse-short}, then you can connect your client application to it in a similar way as you previously connected it to the origin cluster, but with the appropriate contact points and any additional configuration that your target cluster may require.
-For further information, see the documentation for your driver language and version.
+For connection details, see the documentation for your driver language and version.
+
+Make sure that your driver version is compatible with your target cluster.
+For more information, see xref:datastax-drivers:compatibility:driver-matrix.adoc[].
 
 == Configuring your driver to connect to {astra-db}
 
@@ -39,7 +42,7 @@ As before, you can use either of the following sets of credentials to connect to
 +
 The {scb-short} is a zip file that contains TLS encryption certificates and other metadata required to connect to your database.
 Databases can have one or more {scb-short}s.
-For more information, see xref:astra-db-serverless:drivers:secure-connect-bundle.adoc[].
+For more information, see xref:astra-db-serverless:databases:secure-connect-bundle.adoc[].
 +
 [IMPORTANT]
 ====
@@ -53,20 +56,6 @@ For more information, see xref:datastax-drivers:compatibility:driver-matrix.adoc
 If your client application uses an old version of a driver without built-in {scb-short} support, {company} strongly recommends upgrading to a compatible driver to simplify configuration and get the latest features and bug fixes.
 However, you can still connect to {astra-db} for this migration by using https://github.com/datastax/cql-proxy[CQL Proxy] or extracting the {scb-short} archive and using the individual files to enable mTLS in your driver's configuration.
 
-// The {scb-short} support was made available beginning the following versions in the drivers:
-//
-// * https://docs.datastax.com/en/developer/cpp-driver/latest/changelog/#2-14-0[Beginning `2.14.0` of {company} C++ Driver].
-//
-// * https://docs.datastax.com/en/developer/csharp-driver/latest/changelog/\#3-12-0[Beginning `3.12.0` of {company} C# Driver]
-//
-// * https://docs.datastax.com/en/developer/java-driver/latest/changelog/#3-8-0[Beginning `3.8.0` & `4.3.0` of {company} Java Driver].
-//
-// * https://github.com/datastax/nodejs-driver/blob/master/CHANGELOG.md#440[Beginning `4.4.0` of {company} Nodejs Driver].
-//
-// * https://docs.datastax.com/en/developer/python-dse-driver/latest/CHANGELOG/#id24[Beginning `2.11.0` & `3.20.0` of {company} Python Driver].
-//
-// Based on this, follow the instructions in the relevant section below.
-
 If your driver has built-in support for the {astra-db} {scb-short}, the changes to enable your application to connect to {astra-db} are minimal.
 
 //Recalling the xref:connect-clients-to-proxy.adoc#_connecting_company_drivers_to_cassandra[pseudocode to enable your client application to connect to the proxy], here it is how your code needs to change to connect directly to {astra-db}:

modules/ROOT/pages/create-target.adoc

@@ -40,7 +40,7 @@ Save the generate token and credentials (Client ID, Client Secret, and Token) in
 
 === Get the {scb-brief} and upload to client instances
 
-xref:astra-db-serverless:drivers:secure-connect-bundle.adoc[Download your {astra-db} database's {scb}].
+xref:astra-db-serverless:databases:secure-connect-bundle.adoc[Download your {astra-db} database's {scb}].
 The {scb-short} is a zip file that contains TLS encryption certificates and other metadata required to connect to your database.
 
 [IMPORTANT]

modules/ROOT/pages/feasibility-checklists.adoc

@@ -164,21 +164,23 @@ See <<non-idempotent-operations,this section>> for more information about non-id
 
 === Search
 
-Read-only Search workloads can be moved directly from the origin to the target without {product-proxy} being involved.
-If your client application uses Search and also issues writes, or if you need the read routing capabilities from {product-proxy}, then you can connect your search workloads to it as long as you are using the {company} drivers to submit these queries.
+Read-only {dse-short} Search workloads can be moved directly from the origin to the target without {product-proxy} being involved.
+If your client application uses Search and also issues writes, or if you need the read routing capabilities from {product-proxy}, then you can connect your Search workloads to it as long as you are using xref:datastax-drivers:compatibility:driver-matrix.adoc[{company}-compatible drivers] to submit these queries.
 This approach means the queries are regular CQL `SELECT` statements, so {product-proxy} handles them as regular read requests.
 
 If you use the HTTP API then you can either modify your applications to use the CQL API instead or you will have to move those applications directly from the origin to the target when the migration is complete if that is acceptable.
 
 == Client compression
 
-The binary protocol used by {cass-short}, {dse-short}, and {astra-db} supports optional compression of transport-level requests and responses that reduces network traffic at the cost of CPU overhead.
+The binary protocol used by {cass-short}, {dse-short}, {hcd-short}, and {astra-db} supports optional compression of transport-level requests and responses that reduces network traffic at the cost of CPU overhead.
 
-{product-proxy} doesn't support protocol compression at this time.
-This kind of compression is disabled by default on all of our {company} drivers so if you enabled it on your client application then you will need to disable it before starting the migration process.
+{product-proxy} doesn't support protocol compression.
 
-This is *NOT* related to storage compression which you can configure on a table by table basis with the `compression` table property.
-Storage/table compression does not affect the client application or {product-proxy} in any way.
+This compression type is disabled by default in {company}-compatible drivers.
+If it is enabled in your client application, you must disable it before starting the migration process.
+
+This isn't related to storage compression, which you can configure on specific tables with the `compression` table property.
+Storage/table compression doesn't affect the client application or {product-proxy} in any way.
 
 == Authenticator and Authorizer configuration
 
@@ -233,34 +235,13 @@ If your application already tolerates rolling restarts of your current cluster t
 
 To ensure that your client application retries requests when a database connection is closed you should check the section of your driver's documentation related to retry policies.
 
-Most {company} drivers require a statement to be marked as `idempotent` in order to retry it in case of a connection error (such as the termination of a database connection).
-This means that these drivers treat statements as *non-idempotent* by default and will *not* retry them in the case of a connection error unless action is taken.
-Whether you need to take action or not depends on what driver you are using.
-In this section we outline the default behavior of some of these drivers and provide links to the relevant documentation sections.
-
-=== {company} Java Driver 4.x
-
-The default retry policy takes idempotence in consideration and the query builder tries to infer idempotence automatically. See this Java 4.x https://docs.datastax.com/en/developer/java-driver/latest/manual/core/idempotence/[query idempotence documentation section].
-
-=== {company} Java Driver 3.x
-
-The default retry policy takes idempotence in consideration and the query builder tries to infer idempotence automatically. See this Java 3.x https://docs.datastax.com/en/developer/java-driver/3.11/manual/idempotence/[query idempotence documentation section].
-
-This behavior was introduced in version 3.1.0 so prior to this version the default retry policy retried all requests regardless of idempotence.
-
-=== {company} Nodejs Driver 4.x
-
-The default retry policy takes idempotence in consideration. See this Nodejs 4.x https://docs.datastax.com/en/developer/nodejs-driver/latest/features/speculative-executions/#query-idempotence[query idempotence documentation section].
-
-=== {company} C# Driver 3.x and {company} Python Driver 3.x
-
-The default retry policy retries all requests in case of a connection error *regardless of idempotence*. There are retry policies that are idempotency aware but these are not the default policies. Keep in mind that the plan is to make the default retry policy idempotency aware in a future release.
-
-=== {company} C++ Driver 2.x
+Most {company}-compatible drivers require a statement to be marked as `idempotent` in order to retry it in case of a connection error (such as the termination of a database connection).
+This means that, by default, these drivers treat statements as non-idempotent, and the drivers don't automatically retry them in the event of a connection error.
 
-Prior to version 2.5.0, this driver did *NOT* retry any requests after they have been written to the socket, it was up to the client application to handle these and retry them if they are suitable for a retry.
+For more information, see the following driver documentation:
 
-With the release of 2.5.0, the driver retries requests that are set as `idempotent`. See this C++ 2.x https://docs.datastax.com/en/developer/cpp-driver/2.16/topics/configuration/#query-idempotence[query idempotence documentation section].
+* xref:datastax-drivers:developing:query-idempotence.adoc[]
+* xref:datastax-drivers:connecting:retry-policies.adoc[]
 
 == Next steps
 

modules/ROOT/pages/troubleshooting-scenarios.adoc

@@ -33,7 +33,7 @@ This doesn't happen in a rolling fashion: the existing {product-proxy} instances
 
 === Symptoms
 
-In the Java 4.x driver logs, the following issues can manifest during session initialization, or after initialization.
+In the logs for the Java driver 4.x series, the following issues can manifest during session initialization, or after initialization.
 
 [source,log]
 ----
@@ -59,8 +59,10 @@ If you are using spring boot and/or spring-data-cassandra then an upgrade of the
 Alternatively, you can force the protocol version on the driver to the max supported version by both clusters.
 V4 is a good recommendation that usually fits all but if the user is migrating from {dse-short} to {dse-short} then DSE_V1 should be used for {dse-short} 5.x and DSE_V2 should be used for {dse-short} 6.x.
 
-To force the protocol version on the Java driver, check this section of the https://docs.datastax.com/en/developer/java-driver/3.11/manual/native_protocol/#controlling-the-protocol-version[driver manual].
-We don't believe this issue affects Java driver 3.x, but here are the https://docs.datastax.com/en/developer/java-driver/3.11/manual/native_protocol/#controlling-the-protocol-version[instructions] on how to force the version on 3.x, if necessary.
+To force the protocol version on the Java driver, see the documentation for your version of the Java driver:
+
+* https://github.com/apache/cassandra-java-driver/tree/4.x/manual/core/native_protocol[{cass-reg} Java driver 4.18 and later: Controlling the protocol version]
+* https://docs.datastax.com/en/developer/java-driver/latest/manual/core/native_protocol/index.html#controlling-the-protocol-version[{company} Java driver 4.17 and earlier: Controlling the protocol version]
 
 == Protocol errors in the proxy logs but clients can connect successfully
 
@@ -230,15 +232,13 @@ at input 'CALL' ([CALL]...))\"\n","stream":"stderr","time":"2022-07-20T13:10:47.
 The log message indicates that the server doesn't recognize the word “CALL” in the query string which most likely means that it is an RPC (remote procedure call).
 From the proxy logs alone, it is not possible to see what method is being called by the query but it's very likely the RPC that the drivers use to send {dse-short} Insights data to the server.
 
-Most {company} drivers have {dse-short} Insights reporting enabled by default when they detect a server version that supports it (regardless of whether the feature is enabled on the server side or not).
+Most {company}-compatible drivers have {dse-short} Insights reporting enabled by default when they detect a server version that supports it (regardless of whether the feature is enabled on the server side or not).
 The driver might also have it enabled for {astra-db} depending on what server version {astra-db} is returning for queries involving the `system.local` and `system.peers` tables.
 
 === Solution or Workaround
 
-These log messages are harmless but if your need to get rid of them, you can disable the {dse-short} Insights driver feature through the driver configuration.
-Refer to https://github.com/apache/cassandra-java-driver/blob/65d2c19c401175dcc6c370560dd5f783d05b05b9/core/src/main/resources/reference.conf#L1328[this property] for Java driver 4.x.
-
-
+These log messages are harmless, but if you need to remove them, you can disable {dse-short} Insights in the driver configuration.
+For example, in the Java driver, you can set `https://github.com/apache/cassandra-java-driver/blob/4.x/core/src/main/resources/reference.conf#L1365[advanced.monitor-reporting]` to `false`.
 
 == Default Grafana credentials don't work