joao-r-reis commented on code in PR #1901: URL: https://github.com/apache/cassandra-gocql-driver/pull/1901#discussion_r2382749610
########## UPGRADE_GUIDE.md: ########## @@ -0,0 +1,748 @@ +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +# GoCQL Major Version Upgrade Guide + +This guide helps you migrate between major versions of the GoCQL driver. Each major version introduces significant changes that may require code modifications. + + + +## Available Upgrade Paths + +- [v1.x → v2.x](#upgrading-from-v1x-to-v2x) +- [Future version upgrades will be documented here as they become available] + +--- + +## Upgrading from v1.x to v2.x + +Version 2.0.0 represents a major overhaul of the GoCQL driver with significant API changes, new features, and improvements. This migration requires careful planning and testing. + +**Important Prerequisites:** +- **Minimum Go version**: Go 1.19+ +- **Minimum Cassandra version**: 2.1+ (recommended 4.1+ for full feature support) +- **Supported protocol versions**: 3, 4, 5 (Cassandra 2.1+, versions 1 and 2 are no longer supported) + +### Table of Contents + +- [Protocol Version / Cassandra Version Support](#protocol-version--cassandra-version-support) +- [Breaking Changes](#breaking-changes) + - [Module and Import Changes](#module-and-import-changes) + - [Removed Global Functions](#removed-global-functions) + - [Session Setter Methods Removed](#session-setter-methods-removed) + - [Methods Moved from Query/Batch to Iter](#methods-moved-from-querybatch-to-iter) + - [Logging System Overhaul](#logging-system-overhaul) + - [TimeoutLimit Variable Removal](#timeoutlimit-variable-removal) + - [Advanced API Changes](#advanced-api-changes) + - [HostInfo Method Visibility Changes](#hostinfo-method-visibility-changes) + - [HostSelectionPolicy Interface Changes](#hostselectionpolicy-interface-changes) + - [ExecutableQuery Interface Deprecated](#executablequery-interface-deprecated) +- [Changes that might lead to runtime errors](#changes-that-might-lead-to-runtime-errors) + - [PasswordAuthenticator Behavior Change](#passwordauthenticator-behavior-change) + - [CQL to Go type mapping for inet columns changed in MapScan/SliceMap](#cql-to-go-type-mapping-for-inet-columns-changed-in-mapscanslicemap) + - [NULL Collections Now Return nil Instead of Empty Collections in MapScan/SliceMap](#null-collections-now-return-nil-instead-of-empty-collections-in-mapscanslicemap) +- [Deprecation Notices](#deprecation-notices) + - [Example Migrations](#example-migrations) + +--- + +### Protocol Version / Cassandra Version Support + +**Protocol versions 1 and 2 removed:** + +gocql v2.x dropped support for old protocol versions. Here's the mapping of protocol versions to Cassandra versions: + +| Protocol Version | Cassandra Versions | Status in v2.x | +|------------------|-------------------|----------------| +| 1 | 1.2 - 2.0 | ❌ **REMOVED** | +| 2 | 2.0 - 2.2 | ❌ **REMOVED** | +| 3 | 2.1+ | ✅ **Minimum supported** | +| 4 | 2.2+ | ✅ | +| 5 | 4.0+ | ✅ **Latest** | + +```go +// OLD (v1.x) - NO LONGER SUPPORTED +cluster.ProtoVersion = 1 // ❌ Runtime error during connection +cluster.ProtoVersion = 2 // ❌ Runtime error during connection + +// NEW (v2.x) - Minimum version 3 +cluster.ProtoVersion = 3 // ✅ Minimum supported (Cassandra 2.1+) +cluster.ProtoVersion = 4 // ✅ (Cassandra 2.2+) +cluster.ProtoVersion = 5 // ✅ Latest (Cassandra 4.0+) +// OR omit for auto-negotiation (recommended) +``` + +**Runtime error you'll see:** +```bash +gocql: unsupported protocol response version: 1 +# OR +gocql: unsupported protocol response version: 2 +``` + +**Migration:** Update your cluster configuration to use protocol version 3 or higher, or remove the explicit ProtoVersion setting to use auto-negotiation: +```go +// Option 1: Explicit version (minimum 3) +cluster.ProtoVersion = 3 // For Cassandra 2.1+ + +// Option 2: Auto-negotiation (recommended) +cluster := gocql.NewCluster("127.0.0.1") +// ProtoVersion will be auto-negotiated to the highest supported version +// This is recommended as it works with any Cassandra 2.1+ version +``` + +**Note:** Since gocql v2.x requires Cassandra 2.1+ anyway, most users should use auto-negotiation for the best compatibility unless you have a cluster with nodes that have different Cassandra versions. + +--- + +### Breaking Changes Review Comment: done -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
