Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions modules/ROOT/pages/connect-clients-to-proxy.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,19 @@ It also explains how to connect the {cql-shell} (`cqlsh`) to {product-proxy}, wh

A common way to connect client applications to {cass-short} clusters is with {cass-short} drivers.
These drivers can connect to {cass-short}-based clusters, execute queries, iterate through results, access metadata about the clusters, and perform other related activities.
For available drivers and driver documentation, see xref:datastax-drivers:compatibility:driver-matrix.adoc[].
For available drivers and driver documentation, see the following:

* xref:1.2@hyper-converged-database:drivers:cassandra-drivers-overview.adoc[Get started with {cass-short} drivers for {hcd-short}]
* xref:6.9@dse:drivers:cassandra-drivers-overview.adoc[Get started with {cass-short} drivers for {dse-short}]
* xref:astra-db-serverless:drivers:cassandra-drivers-overview.adoc[Get started with {cass-short} drivers for {astra-db} {db-serverless-short}]
* xref:astra-db-classic:drivers:cassandra-drivers-overview.adoc[Get started with {cass-short} drivers for {db-classic}]
* https://cassandra.apache.org/doc/latest/cassandra/getting-started/drivers.html[All {cass} drivers]

The following pseudocode provides simplified examples of the way a {cass-short} driver interacts with {cass-short} clusters.
Specifically, these examples are for {astra-db} and self-managed {dse-short}, {hcd-short}, and open-source {cass-short} clusters.

This pseudocode is for illustration purposes only; the exact syntax depends on your driver language and version.
For specific instructions and examples, see xref:datastax-drivers:connecting:connect-cloud.adoc[].
For specific instructions and examples, see the documentation for your driver.

.Self-managed {cass-short} clusters
[source,pseudocode]
Expand Down
20 changes: 14 additions & 6 deletions modules/ROOT/pages/connect-clients-to-target.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,18 @@ From this point onward, the clusters will diverge, and the target cluster become
Be sure that you have thoroughly xref:ROOT:migrate-and-validate-data.adoc[validated your data (Phase 2)], xref:ROOT:enable-async-dual-reads.adoc[tested your target cluster's performance (Phase 3)], and xref:ROOT:change-read-routing.adoc[routed all reads to the target (Phase 4)] before permanently switching the connection.
====

[#supported-drivers]
== Supported drivers

Your target cluster might not be compatible with your current driver version or language.
For information about supported drivers for your target cluster, see the following:

* xref:1.2@hyper-converged-database:drivers:cassandra-drivers-overview.adoc[Get started with {cass-short} drivers for {hcd-short}]
* xref:6.9@dse:drivers:cassandra-drivers-overview.adoc[Get started with {cass-short} drivers for {dse-short}]
* xref:astra-db-serverless:drivers:cassandra-drivers-overview.adoc[Get started with {cass-short} drivers for {astra-db} {db-serverless-short}]
* xref:astra-db-classic:drivers:cassandra-drivers-overview.adoc[Get started with {cass-short} drivers for {db-classic}]
* https://cassandra.apache.org/doc/latest/cassandra/getting-started/drivers.html[All {cass} drivers]

== Connect a driver to a self-managed {cass-short} cluster

If your origin and target clusters are both self-managed {cass-short} clusters, such as {cass-short}, {dse-short}, or {hcd-short}, then the driver connection strings can be extremely similar.
Expand All @@ -27,16 +39,12 @@ It's possible that your code requires only minor changes to connect to the targe
+
You might need to make additional configuration changes depending on your target cluster's setup, such as authentication and encryption.
For example, if you have execution profiles with unique datacenter-aware load balancing policies, you must update the profiles to use the target datacenters.
+
For information about driver connections for different {cass-short}-compatible clusters, see xref:datastax-drivers:connecting:connect-cloud.adoc[].

. Verify that your driver version is compatible with your target cluster and supports the features that you want to use on your new cluster.
For example, if you want to use the vector data type on an {hcd-short} cluster, you must use a driver version that supports both {hcd-short} and the vector type.
+
When upgrading from an earlier driver version, you might need to make additional code changes to account for enhancements, deprecations, removals, and differences in platform features.
Depending on your application's requirements, you might need to make these changes immediately, or you might make them after switching the connection.
+
For more information on supported drivers, see xref:datastax-drivers:compatibility:driver-matrix.adoc[].

== Connect a driver to {astra-db}

Expand Down Expand Up @@ -193,14 +201,14 @@ print(release_version)
Modifications to driver connection strings depend on driver compatibility with {astra-db}.

Make sure your driver version is compatible with {astra-db} and the features that you want to use in {astra-db}, such as vector data.
For more information, see xref:datastax-drivers:compatibility:driver-matrix.adoc[].
For more information, see <<supported-drivers>>.

Driver versions that are fully compatible with {astra-db} have built-in support for the {scb-short}.
In this case the changes required to connect your application to {astra-db} are minimal.
However, you might need to make <<other-code-changes-for-astra-db,other code changes>>.

The following example demonstrates how the {cass-short} Python driver connects to {astra-db} using an application token and {scb-short}.
For more information and examples of {astra-db} connections, see <<compare-connection-parameters>> and xref:datastax-drivers:connecting:connect-cloud.adoc[].
For more information and examples of {astra-db} connections, see <<compare-connection-parameters>> and the documentation for your driver.

[source,python]
----
Expand Down
2 changes: 1 addition & 1 deletion modules/ROOT/pages/dse-migration-paths.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ If your target database isn't directly compatible with a migration from {dse-sho

In the case of a platform migration where you want to shift your applications to use your new databases, migrate your data first, and then update your client applications to connect exclusively to the 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.
If you are already using a xref:6.9@dse:drivers:cassandra-drivers-overview.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.

Expand Down
6 changes: 3 additions & 3 deletions modules/ROOT/pages/feasibility-checklists.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ This feature is disabled by default because it has a noticeable impact on perfor

If the performance impact is unacceptable for your application, or you are using functions other than `now()`, then you must change your client application to use values calculated locally at the client-level before the statement is sent to the database.
Most drivers have utility methods that help you compute these values locally.
For more information, see your driver's documentation and xref:datastax-drivers:developing:query-timestamps.adoc[Query timestamps in {cass-short} drivers].
For more information, see your driver's documentation and xref:6.9@dse:drivers:timestamps.adoc[Query timestamps in {cass-short} drivers].

[#driver-retry-policy-and-query-idempotence]
== Driver retry policy and query idempotence
Expand All @@ -238,7 +238,7 @@ If your applications already tolerate rolling restarts of your origin cluster, t
To ensure that your client application retries requests that fail due to connection errors caused by the rolling restart process, check your driver's retry policies and whether your requests are marked as idempotent.
Most drivers treat all statements as non-idempotent by default, and they don't automatically retry them.
This means that you must explicitly mark statements as idempotent to trigger retries after connection errors.
For more information, see xref:datastax-drivers:developing:query-idempotence.adoc[] and xref:datastax-drivers:connecting:retry-policies.adoc[].
For more information, see xref:6.9@dse:drivers:idempotence.adoc[] and xref:6.9@dse:drivers:retry-policies.adoc[].

[#client-compression]
== Client compression
Expand Down Expand Up @@ -299,7 +299,7 @@ They _cannot_ be used with the earlier Graph engine in {dse-short} versions prio

{dse-short} Search::
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 {product-proxy} as long as you are using xref:datastax-drivers:compatibility:driver-matrix.adoc[{company}-compatible drivers] to submit these queries.
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 {product-proxy} as long as you are using xref:6.9@dse:drivers:cassandra-drivers-overview.adoc[{dse-short}-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 must move those applications directly from the origin to the target when the migration is complete, if that is acceptable for your use case.
Expand Down
2 changes: 1 addition & 1 deletion modules/ROOT/pages/hcd-migration-paths.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Your {cass-short} driver version must be compatible with {hcd-short}.

If you are using an early driver version or a {dse-short}-only driver, you must upgrade to a driver version that is compatible with {hcd-short}.

For more information, see xref:datastax-drivers:compatibility:driver-matrix.adoc[].
For more information, see xref:1.2@hyper-converged-database:drivers:cassandra-drivers-overview.adoc[].
====

For some migrations, changing the connection string might be the only change you need to make to your code.
Expand Down
5 changes: 3 additions & 2 deletions modules/ROOT/pages/manage-proxy-instances.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -192,9 +192,10 @@ Set the maximum pool size of available stream IDs managed by {product-proxy} per
Use the same value as your driver's maximum stream IDs configuration.
+
In the CQL protocol, every request has a unique stream ID.
However, if there are a lot of requests in a given amount of time, errors can occur due to xref:datastax-drivers:developing:speculative-retry.adoc#stream-id-exhaustion[stream ID exhaustion].
However, if there are a lot of requests in a given amount of time, errors can occur due to xref:6.9@dse:drivers:speculative-execution.adoc#stream-id-exhaustion[stream ID exhaustion].
+
In the client application, the stream IDs are managed internally by the driver, and, in most drivers, the max number is 2048, which is the same default value used by {product-proxy}.
In the client application, the stream IDs are managed internally by the driver.
For most drivers, the maximum is 2048, which is the same default value used by {product-proxy}.
If you have a custom driver configuration with a higher value, make sure `zdm_proxy_max_stream_ids` matches your driver's maximum stream IDs.
+
Default: `2048`
Expand Down