Merge #155864

155864: hints: add builtin for inserting "hint-injection" statement hints r=michae2 a=DrewKimball

#### hints: separate out hint protobuf into separate package

This commit adds a new package `hintpb` for the protobuf structs used
to store hints in the `system.statement_hints` table. This will avoid
dependency cycles in future commits.

Epic: None

Release note: None

#### hints: add injection hint and refactor usage of hint union

This commit adds the protobuf struct for injecting "internal" hints
like (index or join hints) into a statement's AST. This can be serialized
and inserted into the `system.statement_hints` table. This commit also
refactors the way hints are represented in memory.

Informs #153633

Release note: None

#### sql/hints: extract hints system table interfacing logic

This commit extracts helper functions used by the `hints` package to
interface with the `system.statement_hints` table and adds tests for
the helpers.

Epic: None

Release note: None

#### sql,hints: add builtin function to add statement hint for hint "injection"

This commit adds a new builtin function for inserting "hint injection" hints
into the `system.statement_hints` table. Currently, the provided hinted SQL
is serialized as-is into the hint. A future PR will add validation to ensure
that the hinted SQL matches the fingerprint, and that the hints can be
transferred.

Informs #153633

Release note: None

Co-authored-by: Drew Kimball <[email protected]>

Author: craig[bot]

pkg/BUILD.bazel

@@ -500,6 +500,7 @@ ALL_TESTS = [
     "//pkg/sql/gcjob/gcjobnotifier:gcjobnotifier_test",
     "//pkg/sql/gcjob:gcjob_test",
     "//pkg/sql/gcjob_test:gcjob_test_test",
+    "//pkg/sql/hintpb:hintpb_test",
     "//pkg/sql/hints:hints_test",
     "//pkg/sql/idxrecommendations:idxrecommendations_test",
     "//pkg/sql/idxusage:idxusage_test",
@@ -2054,6 +2055,8 @@ GO_TARGETS = [
     "//pkg/sql/gcjob:gcjob",
     "//pkg/sql/gcjob:gcjob_test",
     "//pkg/sql/gcjob_test:gcjob_test_test",
+    "//pkg/sql/hintpb:hintpb",
+    "//pkg/sql/hintpb:hintpb_test",
     "//pkg/sql/hints:hints",
     "//pkg/sql/hints:hints_test",
     "//pkg/sql/idxrecommendations:idxrecommendations",

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

@@ -63,7 +63,7 @@ PROTOBUF_SRCS = [
     "//pkg/sql/catalog/schematelemetry/schematelemetrycontroller:schematelemetrycontroller_go_proto",
     "//pkg/sql/contentionpb:contentionpb_go_proto",
     "//pkg/sql/execinfrapb:execinfrapb_go_proto",
-    "//pkg/sql/hints:hints_go_proto",
+    "//pkg/sql/hintpb:hintpb_go_proto",
     "//pkg/sql/inverted:inverted_go_proto",
     "//pkg/sql/lex:lex_go_proto",
     "//pkg/sql/pgwire/pgerror:pgerror_go_proto",

pkg/ccl/logictestccl/tests/local-read-committed/generated_test.go

@@ -442,6 +442,7 @@ go_library(
         "//pkg/sql/faketreeeval",
         "//pkg/sql/flowinfra",
         "//pkg/sql/gcjob/gcjobnotifier",
+        "//pkg/sql/hintpb",
         "//pkg/sql/hints",
         "//pkg/sql/idxrecommendations",
         "//pkg/sql/idxusage",

pkg/ccl/logictestccl/tests/local-repeatable-read/generated_test.go

@@ -11,6 +11,7 @@ go_library(
         "//pkg/roachpb",
         "//pkg/security/username",
         "//pkg/sql/catalog/descpb",
+        "//pkg/sql/hintpb",
         "//pkg/sql/pgwire/pgcode",
         "//pkg/sql/pgwire/pgerror",
         "//pkg/sql/pgwire/pgnotice",

pkg/gen/protobuf.bzl

@@ -15,6 +15,7 @@ import (
 	"github.com/cockroachdb/cockroach/pkg/roachpb"
 	"github.com/cockroachdb/cockroach/pkg/security/username"
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/descpb"
+	"github.com/cockroachdb/cockroach/pkg/sql/hintpb"
 	"github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgcode"
 	"github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgerror"
 	"github.com/cockroachdb/cockroach/pkg/sql/pgwire/pgnotice"
@@ -589,6 +590,13 @@ func (ep *DummyEvalPlanner) ProcessVectorIndexFixups(
 	return nil
 }
 
+// InsertStatementHint is part of the eval.Planner interface.
+func (ep *DummyEvalPlanner) InsertStatementHint(
+	ctx context.Context, statementFingerprint string, hint hintpb.StatementHintUnion,
+) (int64, error) {
+	return 0, nil
+}
+
 // DummyPrivilegedAccessor implements the tree.PrivilegedAccessor interface by returning errors.
 type DummyPrivilegedAccessor struct{}
 

pkg/sql/BUILD.bazel

@@ -0,0 +1,39 @@
+load("@rules_proto//proto:defs.bzl", "proto_library")
+load("@io_bazel_rules_go//go:def.bzl", "go_library", "go_test")
+load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library")
+
+proto_library(
+    name = "hintpb_proto",
+    srcs = ["statement_hint.proto"],
+    strip_import_prefix = "/pkg",
+    visibility = ["//visibility:public"],
+    deps = ["@com_github_gogo_protobuf//gogoproto:gogo_proto"],
+)
+
+go_proto_library(
+    name = "hintpb_go_proto",
+    compilers = ["//pkg/cmd/protoc-gen-gogoroach:protoc-gen-gogoroach_compiler"],
+    importpath = "github.com/cockroachdb/cockroach/pkg/sql/hintpb",
+    proto = ":hintpb_proto",
+    visibility = ["//visibility:public"],
+    deps = ["@com_github_gogo_protobuf//gogoproto"],
+)
+
+go_library(
+    name = "hintpb",
+    srcs = ["statement_hint.go"],
+    embed = [":hintpb_go_proto"],
+    importpath = "github.com/cockroachdb/cockroach/pkg/sql/hintpb",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//pkg/util/protoutil",
+        "@com_github_cockroachdb_errors//:errors",
+    ],
+)
+
+go_test(
+    name = "hintpb_test",
+    srcs = ["statement_hint_test.go"],
+    embed = [":hintpb"],
+    deps = ["@com_github_stretchr_testify//require"],
+)

pkg/sql/faketreeeval/BUILD.bazel

@@ -0,0 +1,33 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Use of this software is governed by the CockroachDB Software License
+// included in the /LICENSE file.
+
+package hintpb
+
+import (
+	"github.com/cockroachdb/cockroach/pkg/util/protoutil"
+	"github.com/cockroachdb/errors"
+)
+
+// FromBytes converts the raw bytes from system.statement_hints into a
+// StatementHintUnion object.
+func FromBytes(bytes []byte) (StatementHintUnion, error) {
+	res := StatementHintUnion{}
+	if err := protoutil.Unmarshal(bytes, &res); err != nil {
+		return StatementHintUnion{}, err
+	}
+	if res.GetValue() == nil {
+		return StatementHintUnion{}, errors.New("invalid hint bytes: no value set")
+	}
+	return res, nil
+}
+
+// ToBytes converts the StatementHintUnion to a raw bytes representation that
+// can be inserted into the system.statement_hints table.
+func ToBytes(hint StatementHintUnion) ([]byte, error) {
+	if hint.GetValue() == nil {
+		return nil, errors.New("cannot convert empty hint to bytes")
+	}
+	return protoutil.Marshal(&hint)
+}