Merge #149252

149252: sql: improve error message for schema_locked r=rafiss a=rafiss

This also unskips a logictest that was accidentally skipped.

Epic: CRDB-41681
Release note: None

Co-authored-by: Rafi Shamim <[email protected]>

Author: craig[bot]

pkg/ccl/logictestccl/tests/3node-tenant/generated_test.go

@@ -1,4 +1,4 @@
-# LogicTest: !weak-iso-level-configs schema-locked-disabled
+# LogicTest: !weak-iso-level-configs
 # This test is skipped under READ COMMITTED and REPEATABLE READ, since it
 # asserts on the NOTICE output, and weak isolation level schema changes always
 # send out extra notices.

pkg/sql/logictest/testdata/logic_test/create_statements

@@ -87,43 +87,43 @@ statement ok
 INSERT INTO t SELECT i, i+1 FROM generate_series(1,10) AS tmp(i);
 
 onlyif config local-mixed-25.1 local-legacy-schema-changer
-statement error pgcode 57000 schema changes are disallowed on table "t" because it is locked
+statement error pgcode 57000 this schema change is disallowed because table "t" is locked and this operation cannot automatically unlock the table
 ALTER TABLE t ADD COLUMN k INT DEFAULT 30;
 
 onlyif config local-mixed-25.1 local-legacy-schema-changer
-statement error pgcode 57000 schema changes are disallowed on table "t" because it is locked
+statement error pgcode 57000 this schema change is disallowed because table "t" is locked and this operation cannot automatically unlock the table
 ALTER TABLE t DROP COLUMN j;
 
 onlyif config local-mixed-25.1
-statement error pgcode 57000 schema changes are disallowed on table "t" because it is locked
+statement error pgcode 57000 this schema change is disallowed because table "t" is locked and this operation cannot automatically unlock the table
 ALTER TABLE t RENAME TO t2;
 
 onlyif config local-mixed-25.1
-statement error pgcode 57000 schema changes are disallowed on table "t" because it is locked
+statement error pgcode 57000 this schema change is disallowed because table "t" is locked and this operation cannot automatically unlock the table
 ALTER TABLE t RENAME COLUMN j TO j2;
 
 onlyif config local-mixed-25.1
-statement error pgcode 57000 schema changes are disallowed on table "t" because it is locked
+statement error pgcode 57000 this schema change is disallowed because table "t" is locked and this operation cannot automatically unlock the table
 ALTER INDEX idx RENAME TO idx2;
 
 onlyif config local-mixed-25.1
-statement error pgcode 57000 schema changes are disallowed on table "t" because it is locked
+statement error pgcode 57000 this schema change is disallowed because table "t" is locked and this operation cannot automatically unlock the table
 ALTER INDEX idx INVISIBLE;
 
 onlyif config local-mixed-25.1 local-legacy-schema-changer
-statement error pgcode 57000 schema changes are disallowed on table "t" because it is locked
+statement error pgcode 57000 this schema change is disallowed because table "t" is locked and this operation cannot automatically unlock the table
 DROP INDEX idx;
 
 onlyif config local-mixed-25.1 local-legacy-schema-changer
-statement error pgcode 57000 schema changes are disallowed on table "t" because it is locked
+statement error pgcode 57000 this schema change is disallowed because table "t" is locked and this operation cannot automatically unlock the table
 CREATE INDEX idx2 ON t(j);
 
 statement ok
 CREATE TABLE ref (a INT PRIMARY KEY, b INT)
 
 # Locked tables cannot be referenced by foreign keys.
 onlyif config local-mixed-25.1 local-legacy-schema-changer
-statement error pgcode 57000 schema changes are disallowed on table "t" because it is locked
+statement error pgcode 57000 this schema change is disallowed because table "t" is locked and this operation cannot automatically unlock the table
 ALTER TABLE ref ADD CONSTRAINT fk FOREIGN KEY (b) REFERENCES t(j);
 
 # GRANT statements are allowed on the table, as they only affect the

pkg/sql/logictest/testdata/logic_test/schema_locked

@@ -44,11 +44,21 @@ const EnforceHomeRegionFurtherInfo = "For more information, see https://www.cock
 // NewSchemaChangeOnLockedTableErr creates an error signaling schema
 // change statement is attempted on a table with locked schema.
 func NewSchemaChangeOnLockedTableErr(tableName string) error {
-	return errors.WithHintf(pgerror.Newf(pgcode.OperatorIntervention,
-		`schema changes are disallowed on table %q because it is locked`, tableName),
-		"To unlock the table, try \"ALTER TABLE %v SET (schema_locked = false);\" "+
-			"\nAfter schema change completes, we recommend setting it back to true with "+
-			"\"ALTER TABLE %v SET (schema_locked = true);\"", tableName, tableName)
+	return errors.WithHintf(
+		errors.WithDetailf(
+			pgerror.Newf(
+				pgcode.OperatorIntervention,
+				`this schema change is disallowed because table %q is locked and this operation cannot automatically unlock the table`,
+				tableName,
+			),
+			"To unlock the table, execute `ALTER TABLE %v SET (schema_locked = false);`"+
+				"\nAfter the schema change completes, we recommend setting it back to true with "+
+				"`ALTER TABLE %v SET (schema_locked = true);`.",
+			tableName, tableName,
+		),
+		"Locking the table improves changefeed performance; see %s",
+		docs.URL("changefeed-best-practices.html#lock-the-schema-on-changefeed-watched-tables"),
+	)
 }
 
 // NewDisallowedSchemaChangeOnLDRTableErr creates an error that indicates that