scylla,conn,frame: negotiate SCYLLA_USE_METADATA_ID and skip result metadata under it

Prepared-statement result metadata could not be invalidated safely: after an
ALTER the server kept answering with the old column set, so a driver reusing the
metadata it cached at prepare time decoded rows against columns that no longer
described the response (scylladb/scylladb#20860). gocql's answer was to stop
reusing it — f292aaf ("Disable skipping metadata by default") flipped
DisableSkipMetadata to default true — at the cost of carrying result metadata on
every response.

scylladb/scylladb#23292 fixes the underlying problem for SELECT statements. A
server advertising SCYLLA_USE_METADATA_ID hands out a result metadata ID at
prepare time; the driver returns that ID with every EXECUTE, and a stale ID is
answered with the METADATA_CHANGED flag plus fresh metadata and a fresh ID. That
is native protocol v5's mechanism made available on v4, which is what Scylla
negotiates. Implement the driver half.

Negotiation and plumbing.

scyllaUseMetadataIDExt implements cqlProtocolExtension and is registered in
parseCQLProtocolExtensions, so it is sent in STARTUP whenever SUPPORTED lists the
key. The v5 metadata-ID gates in frame.go widen from `proto > protoVersion4` to
`proto > protoVersion4 || scyllaUseMetadataID`: the read in parseResultPrepared,
the read in parseResultMetadata behind METADATA_CHANGED, and the write in
writeExecuteFrame. A v4 connection that negotiated the extension therefore drives
the same primitives the v5 port already built, rather than a second
implementation of them.

Detection is consolidated onto the extension. parseSupported already keyed
isMetadataIDSupported — and through it the isScylla heuristic and the
IsMetadataIDSupported() getter — off a function-local SCYLLA_USE_METADATA_ID
const. That const moves to package scope and both the detector and the extension
read it, leaving one spelling and one detector for the capability.

One source of truth for the negotiated flag.

Two independently derived booleans governing the two halves of one wire contract
is a bug waiting to happen: a Conn that believed the extension was on while its
framers did not would ask the server to skip result metadata while writing no ID
for it to compare against, and the driver would then decode rows against whatever
metadata it had cached. So the negotiated state lives in framerConfig, populated
by connFramers.initCache during connection setup before any query can run, and
Conn reads it through the usesMetadataID() and tracksResultMetadataID()
accessors. There is no Conn-level copy to diverge from it.

newFramerWithExts derived the same flags a second time and is deleted. It had no
non-test callers — production framers come from the per-Conn pool — so keeping it
meant every future extension had to be handled in two places, with only a comment
to say so. Its call sites in scylla_test.go now go through initFramerCache and
getWriteFramer, i.e. the path production uses, which is what makes the claim above
true rather than aspirational.

One framer is still not built from framerConfig: framerPool.get falls back to
newFramer when the pool is disabled, which yields scyllaUseMetadataID false whatever
was negotiated. That is correct during the handshake, and unreachable from the
request path afterwards, because execInternal takes its framer before addCall
rejects a closed connection — so a framer taken after the pool closed belongs to a
call that never writes a frame. The accessor's doc comment says so rather than
claiming an invariant that holds by call ordering rather than by construction; scylladb#982
tracks the fix, which also covers flagLWT and tabletsRoutingV1.

Skipping result metadata.

shouldSkipResultMetadata replaces the inline skipMeta expression in
executeQueryWithMetrics, and metadataIDTracked gates it on both halves of the
mechanism: the connection exchanges result metadata IDs *and* the prepared
statement carries a non-empty one. Where both hold, the session-level
DisableSkipMetadata is ignored, including when it was set to true explicitly — the
flag is a workaround for the bug this mechanism fixes, so once the server reports
metadata changes there is nothing left to work around. Upstream gocql skips by
default on every protocol version, and there is deliberately no session-level knob
to force metadata back on; the java-driver's
skip-cql4-metadata-resolve-method has no equivalent here.

The ID exchange is active on native protocol v5, where the field is mandatory, as
well as on v4 with the extension, and Conn.tracksResultMetadataID reports either.
Scoping the override to the extension alone would leave gocql with opposite
defaults for two encodings of one mechanism, and the losing one would be the one
where the ID is guaranteed by the protocol rather than negotiated: a v5 connection
would carry full result metadata on every response for no reason.
scylladb/scylla-drivers#81 states the rule as "if SCYLLA_USE_METADATA_ID was
negotiated or CQL v5 is used", and the java-driver reaches it from the other
direction — DefaultPreparedStatement.resolveSkipMetadata returns true for any
non-empty result metadata ID, which v5 always supplies. The python-driver
implements the extension half only.

The second condition, a non-empty ID, is reachable and matters. The prepared cache
is keyed (hostID, keyspace, statement) and is evicted only on prepare failure or
UNPREPARED, never on connection close, so a statement prepared before the
extension was negotiated survives a reconnect onto a now-extension-enabled
connection. Without the gate the driver would request skip_metadata while sending
an empty ID. With it, such a statement asks for metadata for one more round trip,
acquires an ID from the resulting METADATA_CHANGED response, and skips from then
on — leaving no window in which the driver skips metadata it cannot recover. Both
sibling drivers gate on the same condition (scylladb/python-driver#770,
scylladb/java-driver#599 and follow-ups).

The remaining gate, a non-empty cached column set, is not an optimization either.
A statement whose RESULT/Prepared carries no result metadata is handed an ID
hashed from empty metadata; current Scylla compares the returned ID against that
same empty-metadata ID, always matches, and so never sets METADATA_CHANGED,
leaving a driver that asked to skip with a response it has no columns to decode.
LIST ROLES OF is the motivating case. The server-side fixes,
scylladb/scylladb#29233 and scylladb/scylladb#29275, are both closed unmerged, so
this gate is what keeps such statements working; document and test it as such.

Query.NoSkipMetadata wins in every case, and is now the only way to force metadata
where the ID exchange is active. Conditional statements are the case to keep in
mind, since their response column set depends on whether the condition applied —
something a result metadata ID cannot express, as it describes the statement and
not the outcome. In practice the column-set gate already covers them, because a
prepared conditional statement's result metadata is empty, and ScanCAS and
MapScanCAS set NoSkipMetadata internally regardless.

A RESULT/Rows that sets METADATA_CHANGED while also setting NO_METADATA is
rejected. The combination is malformed — METADATA_CHANGED obliges the server to
include the new metadata — and both ways of continuing are unrecoverable. Adopting
the ID while keeping the old columns lets the server match it from then on and stop
sending metadata, leaving the driver decoding against stale columns indefinitely;
the python-driver guards that identically. But returning the response's own rows is
the same misdecode one execute earlier: the server has just declared those columns
stale, and the skip-metadata path below would decode against them anyway. So do
neither, and fail the query with the old ID left in the cache — a retry resends it
and the server gets another chance to answer with the metadata it owes.

Record and replay.

The record/replay dialers hash EXECUTE frames at fixed offsets, and skipped the
resultMetadataID field only for protocol v5+. Under this extension that field also
appears on v4 EXECUTE frames, which the frame bytes alone cannot reveal, so the
negotiated state is plumbed through instead: StartupNegotiatesMetadataID detects
the opt-in on both the record and the replay path, the recorder latches it and
stamps each Record with UseMetadataID, and GetFrameHash takes it as an argument.

Documentation.

The DisableSkipMetadata comment said the driver "may still" send skip_metadata
under the extension, which understates it: the flag defaults to true, so the
override is the normal case rather than an exception, and "Default: true" is
misleading on its own. It now says plainly that the flag is ignored — explicit
values included — which connections that applies to, and why that is safe. The
Validate() warning fires on !DisableSkipMetadata, so after the override the
population that actually gets skipping is unwarned while those who opted in
explicitly still are. The protocol version is negotiated per connection, and the
extension long after Validate runs, so the trigger cannot be narrowed; the message
instead names the case that is still risky — a connection that exchanges no result
metadata ID at all.

Tests.

Unit coverage for the extension's negotiation, registration and serialization
(scylla_test.go); for initFramerCache and usesMetadataID against the framer
config, with a negative counterpart for the not-negotiated case; for
tracksResultMetadataID over both mechanisms and both protocol versions, including
that it masks the request/response direction bit, and that usesMetadataID stays
narrower so a v5 connection cannot pass for a negotiated extension; for
shouldSkipResultMetadata composed with metadataIDTracked the way the EXECUTE path
composes them, over the nil and zero-length ID cases, an ID without an ID
exchange, an explicit opt-in, and the empty-column-set gate; and for the
v4-plus-extension GetFrameHash skip. A regression test pins that a truncated
resultMetadataID in a RESULT/Prepared frame is reported as an error through
parseFrame's recover rather than panicking the serve goroutine — the extension
makes that short-bytes read live on protocol v4.

TestPrepareExecuteMetadataChangedFlag becomes table-driven over both ways the ID
exchange can be active, rather than growing a second near-verbatim copy of its
~150-line flow for the extension. It also drops and recreates its table instead of
CREATE IF NOT EXISTS, because the flow ALTERs that table and one left over from an
earlier run already has the added column; and it asserts the no-change case by
pointer identity on the cache entry, since comparing the entry's fields compares it
with itself and can never fail. The extension case stops skipping unconditionally:
it skips only when the server does not advertise the capability, and fails when the
server advertises it but negotiation did not happen, since it is the only
end-to-end coverage of the feature and a negotiation regression must not be able to
turn it green. The v5 case does not run at the suite's default protocol, since
TEST_CQL_PROTOCOL is pinned to 4; the tests commit later in this series gives it an
explicit run against Cassandra 5.

One occurrence of the Id spelling is deliberate, in frame_test.go's transcription
of Cassandra's ResultSet$ResultMetadata$Codec.encode — a verbatim quote of Java
source, which keeps its original naming.

Fixes: https://scylladb.atlassian.net/browse/DRIVER-152
Fixes: scylladb#527
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: nikagra

cassandra_test.go

@@ -3657,30 +3657,119 @@ func TestQueryCompressionNotWorthIt(t *testing.T) {
 	require.Equal(t, str, result)
 }
 
-// This test ensures that the whole Metadata_changed flow
-// is handled properly.
+// This test ensures that the whole Metadata_changed flow is handled properly.
 //
-// To trigger C* to return Metadata_changed we should do:
+// To trigger the server to return Metadata_changed we should do:
 //  1. Create a table
 //  2. Prepare stmt which uses the created table
 //  3. Change the table schema in order to affect prepared stmt (e.g. add a column)
-//  4. Execute prepared stmt. As a result C* should return RESULT/ROWS response with
-//     Metadata_changed flag, new metadata id and updated metadata resultset.
+//  4. Execute prepared stmt. As a result the server should return RESULT/ROWS
+//     response with Metadata_changed flag, new metadata id and updated metadata
+//     resultset.
 //
 // The driver should handle this by updating its prepared statement inside the cache
-// when it receives RESULT/ROWS with Metadata_changed flag
+// when it receives RESULT/ROWS with Metadata_changed flag.
+//
+// It runs for both ways the result-metadata-ID exchange can be active on a
+// connection: native protocol v5, where the field is mandatory, and protocol v4
+// with Scylla's SCYLLA_USE_METADATA_ID extension, which backports it. The two share
+// the whole read and cache-update path (framer.parseResultMetadata and the
+// RESULT/Rows case in Conn.executeQueryWithMetrics), so they are driven through one
+// flow rather than two copies of it.
+//
+// Exactly one case runs per invocation, because the protocol version is fixed for
+// the whole suite by the -proto flag. Note that the v5 case never runs in CI:
+// TEST_CQL_PROTOCOL is pinned to 4 in the Makefile and no workflow overrides it, so
+// reaching it takes an explicit `TEST_CQL_PROTOCOL=5 make test-integration-cassandra`.
 func TestPrepareExecuteMetadataChangedFlag(t *testing.T) {
-	session := createSession(t)
-	defer session.Close()
+	for _, tc := range []struct {
+		name  string
+		table string
+		// gate returns a reason to skip, or "" to run. It may also fail outright, for
+		// a state that must not be allowed to pass as a skip.
+		gate func(t *testing.T, session *Session, conn *Conn) string
+	}{
+		{
+			name:  "native protocol v5",
+			table: "metadata_changed",
+			gate: func(t *testing.T, session *Session, conn *Conn) string {
+				if session.cfg.ProtoVersion < protoVersion5 {
+					return "Metadata_changed mechanism is only available in proto > 4"
+				}
+				if *flagDistribution == "scylla" && flagCassVersion.Before(2025, 3, 0) {
+					return "ScyllaDB before 2025.3 does not exchange result metadata ids"
+				}
+				return ""
+			},
+		},
+		{
+			name:  "protocol v4 with SCYLLA_USE_METADATA_ID",
+			table: "scylla_metadata_changed",
+			gate: func(t *testing.T, session *Session, conn *Conn) string {
+				// Skip only for a server that cannot do this at all. If the server
+				// advertised SCYLLA_USE_METADATA_ID and the driver still failed to
+				// negotiate it, that is a regression — and since this is the only
+				// end-to-end coverage of the extension, skipping would turn that
+				// regression green. Fail instead.
+				if !conn.scyllaSupported.IsMetadataIDSupported() {
+					return "server does not advertise SCYLLA_USE_METADATA_ID"
+				}
+				if !conn.usesMetadataID() {
+					t.Fatal("server advertises SCYLLA_USE_METADATA_ID but the driver did not negotiate it")
+				}
+				return ""
+			},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			session := createSession(t)
+			defer session.Close()
 
-	if session.cfg.ProtoVersion < protoVersion5 || (*flagDistribution == "scylla" && flagCassVersion.Before(2025, 3, 0)) {
-		t.Skip("Metadata_changed mechanism is only available in proto > 4")
+			// We have to specify conn for all queries to ensure that
+			// all queries are running on the same node
+			conn := session.getConn()
+			if conn == nil {
+				t.Skip("no connection available")
+			}
+			if reason := tc.gate(t, session, conn); reason != "" {
+				t.Skip(reason)
+			}
+
+			runMetadataChangedFlow(t, session, conn, tc.table)
+		})
 	}
+}
+
+// runMetadataChangedFlow drives the METADATA_CHANGED flow against
+// gocql_test.<table>, with every statement pinned to conn so they all land on the
+// node whose prepared-statement cache entry is being inspected.
+func runMetadataChangedFlow(t *testing.T, session *Session, conn *Conn, table string) {
+	t.Helper()
+
+	qualified := "gocql_test." + table
 
-	if err := createTable(session, "CREATE TABLE IF NOT EXISTS gocql_test.metadata_changed(id int, PRIMARY KEY (id))"); err != nil {
+	// Drop rather than CREATE IF NOT EXISTS: the flow ALTERs the table, so a table
+	// left behind by an earlier run already has new_col and the ALTER below would
+	// fail before anything is exercised.
+	if err := createTable(session, "DROP TABLE IF EXISTS "+qualified); err != nil {
+		t.Fatal(err)
+	}
+	if err := createTable(session, "CREATE TABLE "+qualified+"(id int, PRIMARY KEY (id))"); err != nil {
 		t.Fatal(err)
 	}
 
+	// Bound every query, not only the ones after the schema change: the first
+	// response after it is the one that actually exercises METADATA_CHANGED, so it is
+	// the most likely to hang and the least useful to leave to the package timeout.
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
+	defer cancel()
+
+	pinned := func(stmt string, values ...any) *Query {
+		q := session.Query(stmt, values...).WithContext(ctx)
+		q.conn = conn
+		return q
+	}
+
 	type record struct {
 		id     int
 		newCol int
@@ -3689,21 +3778,14 @@ func TestPrepareExecuteMetadataChangedFlag(t *testing.T) {
 	firstRecord := record{
 		id: 1,
 	}
-	err := session.Query("INSERT INTO gocql_test.metadata_changed (id) VALUES (?)", firstRecord.id).Exec()
-	if err != nil {
+	if err := pinned("INSERT INTO "+qualified+" (id) VALUES (?)", firstRecord.id).Exec(); err != nil {
 		t.Fatal(err)
 	}
 
-	// We have to specify conn for all queries to ensure that
-	// all queries are running on the same node
-	conn := session.getConn()
-
-	const selectStmt = "SELECT * FROM gocql_test.metadata_changed"
-	queryBeforeTableAltering := session.Query(selectStmt)
-	queryBeforeTableAltering.conn = conn
+	selectStmt := "SELECT * FROM " + qualified
+	queryBeforeTableAltering := pinned(selectStmt)
 	row := make(map[string]interface{})
-	err = queryBeforeTableAltering.MapScan(row)
-	if err != nil {
+	if err := queryBeforeTableAltering.MapScan(row); err != nil {
 		t.Fatal(err)
 	}
 
@@ -3714,34 +3796,28 @@ func TestPrepareExecuteMetadataChangedFlag(t *testing.T) {
 	inflight, _ := session.stmtsLRU.get(stmtCacheKey)
 	preparedStatementBeforeTableAltering := inflight.preparedStatment
 
-	// Changing table schema in order to cause C* to return RESULT/ROWS Metadata_changed
-	alteringTableQuery := session.Query("ALTER TABLE gocql_test.metadata_changed ADD new_col int")
-	alteringTableQuery.conn = conn
-	err = alteringTableQuery.Exec()
-	if err != nil {
+	// Change the table schema so the server returns RESULT/Rows with METADATA_CHANGED.
+	if err := pinned("ALTER TABLE " + qualified + " ADD new_col int").Exec(); err != nil {
 		t.Fatal(err)
 	}
 
 	secondRecord := record{
 		id:     2,
 		newCol: 10,
 	}
-	err = session.Query("INSERT INTO gocql_test.metadata_changed (id, new_col) VALUES (?, ?)", secondRecord.id, secondRecord.newCol).
-		Exec()
-	if err != nil {
+	if err := pinned("INSERT INTO "+qualified+" (id, new_col) VALUES (?, ?)", secondRecord.id, secondRecord.newCol).Exec(); err != nil {
 		t.Fatal(err)
 	}
 
-	// Handles result from iter and ensures integrity of the result,
-	// closes iter and handles error
+	// handleRows scans all rows from the iterator and verifies the values.
 	handleRows := func(iter *Iter) {
 		t.Helper()
 
 		var scannedID int
-		var scannedNewCol *int // to perform null values
+		var scannedNewCol *int // to capture null values
 
-		// when the driver handling null values during unmarshalling
-		// it sets to dest type its zero value, which is (*int)(nil) for this case
+		// When the driver handles null values during unmarshalling it sets the
+		// destination to its zero value, which is (*int)(nil) for this case.
 		var nilIntPtr *int
 
 		// Collect all rows into a map to avoid order-dependent assertions.
@@ -3759,26 +3835,24 @@ func TestPrepareExecuteMetadataChangedFlag(t *testing.T) {
 		err := iter.Close()
 		if err != nil {
 			if errors.Is(err, context.DeadlineExceeded) {
-				t.Fatal("It is likely failed due deadlock")
+				t.Fatal("It is likely failed due to a deadlock")
 			}
 			t.Fatal(err)
 		}
 	}
 
-	// Expecting C* will return RESULT/ROWS Metadata_changed
-	// and it will be properly handled
-	queryAfterTableAltering := session.Query(selectStmt)
-	queryAfterTableAltering.conn = conn
-	iter := queryAfterTableAltering.Iter()
-	handleRows(iter)
+	// The first query after the schema change should trigger METADATA_CHANGED.
+	handleRows(pinned(selectStmt).Iter())
 
-	// Ensuring if cache contains updated prepared statement
+	// The prepared statement cache must have been updated with the new metadata ID.
 	inflight, _ = session.stmtsLRU.get(stmtCacheKey)
 	preparedStatementAfterTableAltering := inflight.preparedStatment
 	require.NotEqual(t, preparedStatementBeforeTableAltering.resultMetadataID, preparedStatementAfterTableAltering.resultMetadataID)
 	require.NotEqual(t, preparedStatementBeforeTableAltering.response, preparedStatementAfterTableAltering.response)
 
-	// FORCE SEND OLD RESULT METADATA ID (https://issues.apache.org/jira/browse/CASSANDRA-20028)
+	// Force the driver to send the old (stale) result metadata ID, to verify the
+	// server still signals the change when the driver's id is outdated.
+	// (https://issues.apache.org/jira/browse/CASSANDRA-20028)
 	closedCh := make(chan struct{})
 	close(closedCh)
 	session.stmtsLRU.add(stmtCacheKey, &inflightPrepare{
@@ -3787,15 +3861,7 @@ func TestPrepareExecuteMetadataChangedFlag(t *testing.T) {
 		preparedStatment: preparedStatementBeforeTableAltering,
 	})
 
-	// Running query with timeout to ensure there is no deadlocks.
-	// However, it doesn't 100% proves that there is a deadlock...
-	ctx, cancel := context.WithTimeout(context.Background(), time.Second*30)
-	defer cancel()
-
-	queryAfterTableAltering2 := session.Query(selectStmt).WithContext(ctx)
-	queryAfterTableAltering2.conn = conn
-	iter = queryAfterTableAltering2.Iter()
-	handleRows(iter)
+	handleRows(pinned(selectStmt).Iter())
 
 	inflight, _ = session.stmtsLRU.get(stmtCacheKey)
 	preparedStatementAfterTableAltering2 := inflight.preparedStatment
@@ -3806,18 +3872,15 @@ func TestPrepareExecuteMetadataChangedFlag(t *testing.T) {
 	require.NotEqual(t, preparedStatementAfterTableAltering.response, preparedStatementAfterTableAltering2.response) // METADATA_CHANGED flag
 	require.True(t, preparedStatementAfterTableAltering2.response.flags&frm.FlagMetaDataChanged != 0)
 
-	// Executing prepared stmt and expecting that C* won't return
-	// Metadata_changed because the table is not being changed.
-	queryAfterTableAltering3 := session.Query(selectStmt).WithContext(ctx)
-	queryAfterTableAltering3.conn = conn
-	iter = queryAfterTableAltering3.Iter()
-	handleRows(iter)
+	// A subsequent query carrying the correct (updated) metadata ID must not trigger
+	// METADATA_CHANGED, which means the cache entry must not be replaced at all.
+	// Assert that by pointer identity: comparing the entry's fields would compare it
+	// with itself, so such an assertion could never fail.
+	handleRows(pinned(selectStmt).Iter())
 
-	// Ensuring metadata of prepared stmt is not changed
 	inflight, _ = session.stmtsLRU.get(stmtCacheKey)
-	preparedStatementAfterTableAltering3 := inflight.preparedStatment
-	require.Equal(t, preparedStatementAfterTableAltering2.resultMetadataID, preparedStatementAfterTableAltering3.resultMetadataID)
-	require.Equal(t, preparedStatementAfterTableAltering2.response, preparedStatementAfterTableAltering3.response)
+	require.Same(t, preparedStatementAfterTableAltering2, inflight.preparedStatment,
+		"the cached prepared statement should not have been replaced")
 }
 
 func TestStmtCacheUsesOverriddenKeyspace(t *testing.T) {

cluster.go

@@ -270,10 +270,36 @@ type ClusterConfig struct {
 	// the metadata to parse the rows and will not reuse the metadata from the prepared
 	// statement.
 	//
+	// This flag exists because prepared-statement result metadata could not be
+	// invalidated safely: after an ALTER the server kept answering with the old
+	// column set, so reusing the cached metadata could misdecode rows. It defaults
+	// to true for that reason.
+	//
+	// This flag is IGNORED — including when it was set to true explicitly — once the
+	// connection exchanges result metadata IDs and the driver holds one for the
+	// statement. That is the case on native protocol v5, and on protocol v4 once the
+	// SCYLLA_USE_METADATA_ID extension is negotiated. Either way the underlying
+	// problem is fixed: the server hands out a result metadata ID at prepare time,
+	// the driver returns it with every execute, and the server answers a stale ID
+	// with METADATA_CHANGED plus fresh metadata. Skipping is then safe, so the driver
+	// skips and this workaround no longer applies.
+	//
+	// This matches scylladb/scylla-drivers#81, which specifies skipping as the safe
+	// default "if SCYLLA_USE_METADATA_ID was negotiated or CQL v5 is used", and the
+	// Scylla java-driver, which skips for any non-empty result metadata ID. The
+	// Scylla python-driver implements the extension half only.
+	//
+	// There is deliberately no knob to force metadata for a whole session once an ID
+	// is in play (the java-driver's skip-cql4-metadata-resolve-method has no
+	// equivalent here). Use Query.NoSkipMetadata for a specific query; ScanCAS and
+	// MapScanCAS already do so internally.
+	//
 	// See https://issues.apache.org/jira/browse/CASSANDRA-10786
 	// See https://github.com/scylladb/scylladb/issues/20860
+	// See https://github.com/scylladb/scylladb/pull/23292
 	//
-	// Default: true
+	// Default: true, and has no effect on a connection that exchanges result
+	// metadata IDs.
 	DisableSkipMetadata bool
 	// DisableShardAwarePort will prevent the driver from connecting to Scylla's shard-aware port,
 	// even if there are nodes in the cluster that support it.
@@ -654,7 +680,14 @@ func (cfg *ClusterConfig) Validate() error {
 	}
 
 	if !cfg.DisableSkipMetadata {
-		cfg.Logger.Println("warning: enabling skipping metadata can lead to unpredictable results when executing query and altering columns involved in the query.")
+		// The hazard this warns about is confined to connections that exchange no
+		// result metadata ID: protocol v4 or lower against a server that does not
+		// advertise SCYLLA_USE_METADATA_ID. Everywhere else the server reports
+		// metadata changes via METADATA_CHANGED, DisableSkipMetadata is ignored, and
+		// skipping is both safe and the default — so say which case is actually risky.
+		// The protocol version is negotiated per connection, long after Validate runs,
+		// so this cannot be narrowed down here.
+		cfg.Logger.Println("warning: skipping result metadata can lead to unpredictable results if columns involved in a prepared query are altered, on connections that exchange no result metadata ID (protocol v4 or lower without the SCYLLA_USE_METADATA_ID extension).")
 	}
 
 	if cfg.SerialConsistency > 0 && !cfg.SerialConsistency.IsSerial() {