server: extend SQL error messages by regex config

Author: zeminzhou

pkg/config/BUILD.bazel

@@ -42,7 +42,7 @@ go_test(
     data = glob(["**"]),
     embed = [":config"],
     flaky = True,
-    shard_count = 32,
+    shard_count = 34,
     deps = [
         "//pkg/config/deploymode",
         "//pkg/config/kerneltype",

pkg/config/config.go

@@ -24,6 +24,7 @@ import (
 	"os"
 	"os/user"
 	"path/filepath"
+	"regexp"
 	"sort"
 	"strings"
 	"sync"
@@ -261,6 +262,8 @@ type Config struct {
 	// 2. 'zone' is a special key that indicates the DC location of this tidb-server. If it is set, the value for this
 	// key will be the default value of the session variable `txn_scope` for this tidb-server.
 	Labels map[string]string `toml:"labels" json:"labels"`
+	// ExtendedErrorMsgs maps error message regexps to configured suffixes for selected user-facing errors.
+	ExtendedErrorMsgs map[string]string `toml:"extended-error-msgs" json:"extended-error-msgs"`
 
 	// EnableGlobalIndex is deprecated.
 	EnableGlobalIndex bool `toml:"enable-global-index" json:"enable-global-index"`
@@ -1175,6 +1178,7 @@ var defaultConf = Config{
 	EnableCollectExecutionInfo: true,
 	EnableTelemetry:            false,
 	Labels:                     make(map[string]string),
+	ExtendedErrorMsgs:          make(map[string]string),
 	EnableGlobalIndex:          false,
 	Security: Security{
 		SpilledFileEncryptionMethod: SpilledFileEncryptionMethodPlaintext,
@@ -1214,9 +1218,21 @@ var (
 // NewConfig creates a new config instance with default value.
 func NewConfig() *Config {
 	conf := defaultConf
+	conf.ExtendedErrorMsgs = cloneStringMap(defaultConf.ExtendedErrorMsgs)
 	return &conf
 }
 
+func cloneStringMap(src map[string]string) map[string]string {
+	if src == nil {
+		return nil
+	}
+	dst := make(map[string]string, len(src))
+	for k, v := range src {
+		dst[k] = v
+	}
+	return dst
+}
+
 // GetGlobalConfig returns the global configuration for this server.
 // It should store configuration from command line and configuration file.
 // Other parts of the system can read the global configuration use this function.
@@ -1464,6 +1480,11 @@ func (c *Config) Valid() error {
 	if c.Security.SkipGrantTable && !hasRootPrivilege() {
 		return fmt.Errorf("TiDB run with skip-grant-table need root privilege")
 	}
+	for pattern := range c.ExtendedErrorMsgs {
+		if _, err := regexp.Compile(pattern); err != nil {
+			return fmt.Errorf("invalid extended-error-msgs regexp %q: %w", pattern, err)
+		}
+	}
 	if !c.Store.Valid() {
 		return fmt.Errorf("invalid store=%s, valid storages=%v", c.Store, StoreTypeList())
 	}
@@ -1633,6 +1654,7 @@ func init() {
 
 func initByLDFlags(edition, checkBeforeDropLDFlag string) {
 	conf := defaultConf
+	conf.ExtendedErrorMsgs = cloneStringMap(defaultConf.ExtendedErrorMsgs)
 	if intest.InTest && kerneltype.IsNextGen() {
 		// In test mode, without reading a config file, we still assume the `GetGlobalConfig()` returns
 		// a valid config file. However, the "valid" nextgen config file should always have a keyspace name.

pkg/config/config.toml.example

@@ -480,6 +480,11 @@ tikv-raftstore-store-write-trigger-wb-bytes = 0.00006100
 tikv-storage-processed-keys-batch-get = 0.00266791
 tikv-storage-processed-keys-get = 0.01416829
 
+# extended-error-msgs appends configured messages to SQL errors matching regexps. When multiple
+# regexps match the same error, TiDB uses the longest regexp pattern first.
+# Example: "^Feature '.+' is not supported$" = "see the feature limitations for more details"
+[extended-error-msgs]
+
 # instance scope variables
 # These options are also available as a system variable for online configuration
 # changes to the system variable do not persist to the cluster. You must make changes

pkg/config/config.toml.nextgen.example

@@ -446,6 +446,11 @@ allow-expression-index = false
 # engines means allow the tidb server read data from which types of engines. options: "tikv", "tiflash", "tidb".
 engines = ["tikv", "tiflash", "tidb"]
 
+# extended-error-msgs appends configured messages to SQL errors matching regexps. When multiple
+# regexps match the same error, TiDB uses the longest regexp pattern first.
+# Example: "^Feature '.+' is not supported$" = "see the feature limitations for more details"
+[extended-error-msgs]
+
 # instance scope variables
 # These options are also available as a system variable for online configuration
 # changes to the system variable do not persist to the cluster. You must make changes

pkg/config/config_test.go

@@ -170,6 +170,41 @@ disable-error-stack = false
 `, nbFalse, nbUnset, nbUnset, nbUnset, false, true)
 }
 
+func TestExtendedErrorMsgsConfig(t *testing.T) {
+	configFile := filepath.Join(t.TempDir(), "config.toml")
+	require.NoError(t, os.WriteFile(configFile, []byte(`
+[extended-error-msgs]
+"^Access denied for user '.+'@'.+' \\(using password: (YES|NO)\\)$" = "see https://docs.pingcap.com/tidbcloud/select-cluster-tier#user-name-prefix for more details"
+"^require_secure_transport can not be set to ON with SEM\\(security enhanced mode\\) enabled$" = "see https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-tier-clusters for more details"
+"^sleep\\(\\) argument is greater than [0-9]+$" = "see https://docs.pingcap.com/tidbcloud/serverless-tier-limitations#sql for more details"
+"^[A-Z ]+ command denied to user '.+'@'.+' for table '.+'$" = "see https://docs.pingcap.com/tidbcloud/limited-sql-features#system-tables for more details"
+"^Access denied; you need \\(at least one of\\) the RESTRICTED_VARIABLES_ADMIN privilege\\(s\\) for this operation$" = "see https://docs.pingcap.com/tidbcloud/limited-sql-features#system-variables for more details"
+"^Feature '.+' is not supported when security enhanced mode is enabled$" = "see https://docs.pingcap.com/tidbcloud/limited-sql-features#statements for more details"
+`), 0644))
+
+	conf := NewConfig()
+	require.NoError(t, conf.Load(configFile))
+	require.NoError(t, conf.Valid())
+	require.Equal(t, map[string]string{
+		`^Access denied for user '.+'@'.+' \(using password: (YES|NO)\)$`:                                                "see https://docs.pingcap.com/tidbcloud/select-cluster-tier#user-name-prefix for more details",
+		`^require_secure_transport can not be set to ON with SEM\(security enhanced mode\) enabled$`:                     "see https://docs.pingcap.com/tidbcloud/secure-connections-to-serverless-tier-clusters for more details",
+		`^sleep\(\) argument is greater than [0-9]+$`:                                                                    "see https://docs.pingcap.com/tidbcloud/serverless-tier-limitations#sql for more details",
+		`^[A-Z ]+ command denied to user '.+'@'.+' for table '.+'$`:                                                      "see https://docs.pingcap.com/tidbcloud/limited-sql-features#system-tables for more details",
+		`^Access denied; you need \(at least one of\) the RESTRICTED_VARIABLES_ADMIN privilege\(s\) for this operation$`: "see https://docs.pingcap.com/tidbcloud/limited-sql-features#system-variables for more details",
+		`^Feature '.+' is not supported when security enhanced mode is enabled$`:                                         "see https://docs.pingcap.com/tidbcloud/limited-sql-features#statements for more details",
+	}, conf.ExtendedErrorMsgs)
+
+	require.Empty(t, NewConfig().ExtendedErrorMsgs)
+}
+
+func TestExtendedErrorMsgsInvalidRegexp(t *testing.T) {
+	conf := NewConfig()
+	conf.ExtendedErrorMsgs = map[string]string{
+		"[": "invalid regexp",
+	}
+	require.ErrorContains(t, conf.Valid(), "invalid extended-error-msgs regexp")
+}
+
 func TestRemovedVariableCheck(t *testing.T) {
 	configTest := []struct {
 		options string

pkg/server/BUILD.bazel

@@ -93,6 +93,7 @@ go_library(
         "//pkg/util/cpuprofile",
         "//pkg/util/dbterror",
         "//pkg/util/dbterror/exeerrors",
+        "//pkg/util/errmsg",
         "//pkg/util/execdetails",
         "//pkg/util/fastrand",
         "//pkg/util/hack",

pkg/server/conn.go

@@ -103,6 +103,7 @@ import (
 	"github.com/pingcap/tidb/pkg/util/chunk"
 	contextutil "github.com/pingcap/tidb/pkg/util/context"
 	"github.com/pingcap/tidb/pkg/util/dbterror/exeerrors"
+	"github.com/pingcap/tidb/pkg/util/errmsg"
 	"github.com/pingcap/tidb/pkg/util/execdetails"
 	"github.com/pingcap/tidb/pkg/util/hack"
 	"github.com/pingcap/tidb/pkg/util/intest"
@@ -1637,6 +1638,7 @@ func (cc *clientConn) writeError(ctx context.Context, e error) error {
 			m = mysql.NewErrf(mysql.ErrUnknown, "%s", nil, e.Error())
 		}
 	}
+	errmsg.ExtendErrorMessage(m)
 
 	cc.lastCode = m.Code
 	defer errno.IncrementError(m.Code, cc.user, cc.peerHost)

pkg/util/errmsg/BUILD.bazel

@@ -0,0 +1,25 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "errmsg",
+    srcs = ["errmsg.go"],
+    importpath = "github.com/pingcap/tidb/pkg/util/errmsg",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//pkg/config",
+        "//pkg/parser/mysql",
+    ],
+)
+
+go_test(
+    name = "errmsg_test",
+    timeout = "short",
+    srcs = ["errmsg_test.go"],
+    embed = [":errmsg"],
+    flaky = True,
+    deps = [
+        "//pkg/config",
+        "//pkg/parser/mysql",
+        "@com_github_stretchr_testify//require",
+    ],
+)

pkg/util/errmsg/errmsg.go

@@ -0,0 +1,84 @@
+// Copyright 2026 PingCAP, Inc.
+//
+// Licensed 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.
+
+package errmsg
+
+import (
+	"fmt"
+	"regexp"
+	"sort"
+	"strings"
+	"sync"
+
+	"github.com/pingcap/tidb/pkg/config"
+	"github.com/pingcap/tidb/pkg/parser/mysql"
+)
+
+var regexpCache sync.Map
+
+// ExtendErrorMessage appends a configured message suffix to selected SQL errors.
+func ExtendErrorMessage(m *mysql.SQLError) {
+	if m == nil {
+		return
+	}
+
+	extendedMsgs := config.GetGlobalConfig().ExtendedErrorMsgs
+	if len(extendedMsgs) == 0 {
+		return
+	}
+
+	patterns := make([]string, 0, len(extendedMsgs))
+	for pattern := range extendedMsgs {
+		patterns = append(patterns, pattern)
+	}
+	sort.Slice(patterns, func(i, j int) bool {
+		if len(patterns[i]) != len(patterns[j]) {
+			return len(patterns[i]) > len(patterns[j])
+		}
+		return patterns[i] < patterns[j]
+	})
+
+	for _, pattern := range patterns {
+		extendedMsg := extendedMsgs[pattern]
+		if extendedMsg == "" {
+			continue
+		}
+		re, err := compileRegexp(pattern)
+		if err != nil {
+			continue
+		}
+		if re.MatchString(m.Message) {
+			extendErrorMessage(m, extendedMsg)
+			return
+		}
+	}
+}
+
+func compileRegexp(pattern string) (*regexp.Regexp, error) {
+	cachedRegexp, ok := regexpCache.Load(pattern)
+	if ok {
+		return cachedRegexp.(*regexp.Regexp), nil
+	}
+
+	compiledRegexp, err := regexp.Compile(pattern)
+	if err != nil {
+		return nil, err
+	}
+	actual, _ := regexpCache.LoadOrStore(pattern, compiledRegexp)
+	return actual.(*regexp.Regexp), nil
+}
+
+func extendErrorMessage(m *mysql.SQLError, msg string) {
+	m.Message = fmt.Sprintf("%s, %s.", strings.TrimSuffix(m.Message, "."), strings.TrimSuffix(msg, "."))
+}