Merge #59551

59551: sql: add link to deprecation docs for cross db references in the error r=otan a=arulajmani Closes #57782 Release note (sql change): error messages for cross-database links now include a hint directing to the user to the deprecation docs. An example message looks like: ``` ERROR: the view cannot refer to other databases; (see the 'sql.cross_db_views.enabled' cluster setting) SQLSTATE: 0A000 HINT: Note that cross database references will be removed in future releases. See: https://www.cockroachlabs.com/docs/releases/v21.1.0.html#deprecations ``` Co-authored-by: arulajmani <[email protected]>
cockroachdb · Jan 31, 2021 · 8bd46b9 · 8bd46b9
2 parents b8c47c8 + 03798d0
commit 8bd46b9
Show file tree

Hide file tree

Showing 4 changed files with 36 additions and 10 deletions.
diff --git a/pkg/docs/docs.go b/pkg/docs/docs.go
@@ -10,12 +10,25 @@
 
 package docs
 
-import "github.com/cockroachdb/cockroach/pkg/build"
+import (
+	"fmt"
+
+	"github.com/cockroachdb/cockroach/pkg/build"
+)
 
 // URLBase is the root URL for the version of the docs associated with this
 // binary.
 var URLBase = "https://www.cockroachlabs.com/docs/" + build.VersionPrefix()
 
+// URLReleaseNotesBase is the root URL for the release notes for the .0 patch
+// release associated with this binary.
+var URLReleaseNotesBase = fmt.Sprintf("https://www.cockroachlabs.com/docs/releases/%s.0.html",
+	build.VersionPrefix())
+
 // URL generates the URL to pageName in the version of the docs associated
 // with this binary.
 func URL(pageName string) string { return URLBase + "/" + pageName }
+
+// ReleaseNotesURL generates the URL to pageName in the .0 patch release notes
+// docs associated with this binary.
+func ReleaseNotesURL(pageName string) string { return URLReleaseNotesBase + pageName }
diff --git a/pkg/sql/create_table.go b/pkg/sql/create_table.go
@@ -825,9 +825,11 @@ func ResolveFK(
 	}
 	if target.ParentID != tbl.ParentID {
 		if !allowCrossDatabaseFKs.Get(&evalCtx.Settings.SV) {
-			return pgerror.Newf(pgcode.InvalidForeignKey,
-				"foreign references between databases are not allowed (see the '%s' cluster setting)",
-				allowCrossDatabaseFKsSetting,
+			return errors.WithHintf(
+				pgerror.Newf(pgcode.InvalidForeignKey,
+					"foreign references between databases are not allowed (see the '%s' cluster setting)",
+					allowCrossDatabaseFKsSetting),
+				crossDBReferenceDeprecationHint(),
 			)
 		}
 	}

diff --git a/pkg/sql/create_view.go b/pkg/sql/create_view.go
@@ -15,6 +15,7 @@ import (
 	"fmt"
 
 	"github.com/cockroachdb/cockroach/pkg/clusterversion"
+	"github.com/cockroachdb/cockroach/pkg/docs"
 	"github.com/cockroachdb/cockroach/pkg/keys"
 	"github.com/cockroachdb/cockroach/pkg/server/telemetry"
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/catalogkv"
@@ -32,6 +33,7 @@ import (
 	"github.com/cockroachdb/cockroach/pkg/util/hlc"
 	"github.com/cockroachdb/cockroach/pkg/util/log"
 	"github.com/cockroachdb/cockroach/pkg/util/log/eventpb"
+	"github.com/cockroachdb/errors"
 )
 
 // createViewNode represents a CREATE VIEW statement.
@@ -77,9 +79,11 @@ func (n *createViewNode) startExec(params runParams) error {
 	if !allowCrossDatabaseViews.Get(&params.p.execCfg.Settings.SV) {
 		for _, dep := range n.planDeps {
 			if dbID := dep.desc.ParentID; dbID != n.dbDesc.ID && dbID != keys.SystemDatabaseID {
-				return pgerror.Newf(pgcode.FeatureNotSupported,
-					"the view cannot refer to other databases; (see the '%s' cluster setting)",
-					allowCrossDatabaseViewsSetting,
+				return errors.WithHintf(
+					pgerror.Newf(pgcode.FeatureNotSupported,
+						"the view cannot refer to other databases; (see the '%s' cluster setting)",
+						allowCrossDatabaseViewsSetting),
+					crossDBReferenceDeprecationHint(),
 				)
 			}
 		}
@@ -465,3 +469,8 @@ func overrideColumnNames(cols colinfo.ResultColumns, newNames tree.NameList) col
 	}
 	return res
 }
+
+func crossDBReferenceDeprecationHint() string {
+	return fmt.Sprintf("Note that cross-database references will be removed in future releases. See: %s",
+		docs.ReleaseNotesURL(`#deprecations`))
+}
diff --git a/pkg/sql/sequence.go b/pkg/sql/sequence.go
@@ -328,9 +328,11 @@ func assignSequenceOptions(
 				}
 				if tableDesc.ParentID != sequenceParentID &&
 					!allowCrossDatabaseSeqOwner.Get(&params.p.execCfg.Settings.SV) {
-					return pgerror.Newf(pgcode.FeatureNotSupported,
-						"OWNED BY cannot refer to other databases; (see the '%s' cluster setting)",
-						allowCrossDatabaseSeqOwnerSetting,
+					return errors.WithHintf(
+						pgerror.Newf(pgcode.FeatureNotSupported,
+							"OWNED BY cannot refer to other databases; (see the '%s' cluster setting)",
+							allowCrossDatabaseSeqOwnerSetting),
+						crossDBReferenceDeprecationHint(),
 					)
 				}
 				// We only want to trigger schema changes if the owner is not what we