sql: add hints package

This commit adds a new `sql/hints` package along with a `StatementHints`
protobuf struct and some utility functions for working with it.

Epic: None

Release note: None

Author: DrewKimball

pkg/BUILD.bazel

@@ -2061,6 +2061,7 @@ GO_TARGETS = [
     "//pkg/sql/gcjob:gcjob",
     "//pkg/sql/gcjob:gcjob_test",
     "//pkg/sql/gcjob_test:gcjob_test_test",
+    "//pkg/sql/hints:hints",
     "//pkg/sql/idxrecommendations:idxrecommendations",
     "//pkg/sql/idxrecommendations:idxrecommendations_test",
     "//pkg/sql/idxusage:idxusage",

pkg/gen/protobuf.bzl

@@ -63,6 +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/inverted:inverted_go_proto",
     "//pkg/sql/lex:lex_go_proto",
     "//pkg/sql/pgwire/pgerror:pgerror_go_proto",

pkg/sql/hints/BUILD.bazel

@@ -0,0 +1,29 @@
+load("@rules_proto//proto:defs.bzl", "proto_library")
+load("@io_bazel_rules_go//proto:def.bzl", "go_proto_library")
+load("@io_bazel_rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "hints",
+    srcs = ["statement_hint.go"],
+    embed = [":hints_go_proto"],
+    importpath = "github.com/cockroachdb/cockroach/pkg/sql/hints",
+    visibility = ["//visibility:public"],
+    deps = ["//pkg/util/protoutil"],
+)
+
+go_proto_library(
+    name = "hints_go_proto",
+    compilers = ["//pkg/cmd/protoc-gen-gogoroach:protoc-gen-gogoroach_compiler"],
+    importpath = "github.com/cockroachdb/cockroach/pkg/sql/hints",
+    proto = ":hints_proto",
+    visibility = ["//visibility:public"],
+    deps = ["@com_github_gogo_protobuf//gogoproto"],
+)
+
+proto_library(
+    name = "hints_proto",
+    srcs = ["statement_hint.proto"],
+    strip_import_prefix = "/pkg",
+    visibility = ["//visibility:public"],
+    deps = ["@com_github_gogo_protobuf//gogoproto:gogo_proto"],
+)

pkg/sql/hints/statement_hint.go

@@ -0,0 +1,24 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Use of this software is governed by the CockroachDB Software License
+// included in the /LICENSE file.
+
+package hints
+
+import "github.com/cockroachdb/cockroach/pkg/util/protoutil"
+
+// NewStatementHints converts the raw bytes from system.statement_hints into a
+// StatementHints object.
+func NewStatementHints(bytes []byte) (*StatementHints, error) {
+	res := &StatementHints{}
+	if err := protoutil.Unmarshal(bytes, res); err != nil {
+		return nil, err
+	}
+	return res, nil
+}
+
+// ToBytes converts the StatementHints to a raw bytes representation that can be
+// inserted into the system.statement_hints table.
+func (hints *StatementHints) ToBytes() ([]byte, error) {
+	return protoutil.Marshal(hints)
+}

pkg/sql/hints/statement_hint.proto

@@ -0,0 +1,15 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Use of this software is governed by the CockroachDB Software License
+// included in the /LICENSE file.
+
+syntax = "proto3";
+package hints;
+
+import "gogoproto/gogo.proto";
+
+// StatementHints consolidates the "external" hints that can be applied to
+// statements with a given fingerprint using the system.statement_hints table.
+message StatementHints {
+  // TODO: add a field for each type of statement hint.
+}