stats: make table statistics cache size configurable

Replace the hardcoded table statistics cache size (previously passed
through server config plumbing as `defaultSQLTableStatCacheSize = 256`)
with a cluster setting `sql.stats.table_statistics_cache.capacity`. The
`ShouldEvict` callback now reads the setting dynamically, so the cache
resizes on the next insertion after the setting is changed.

This removes the `cacheSize int` parameter from `NewTableStatisticsCache`
along with the `SQLConfig.TableStatCacheSize` field and associated
plumbing through `server_controller_new_server.go`.

Informs: #54030

Release note (sql change): The new cluster setting
`sql.stats.table_statistics_cache.capacity` controls the maximum number
of tables whose statistics are retained in the in-memory LRU cache
(default: 256).

Co-Authored-By: roachdev-claude <roachdev-claude-bot@cockroachlabs.com>

Author: DrewKimball

docs/generated/settings/settings-for-tenants.txt

@@ -378,6 +378,7 @@ sql.stats.response.max	integer	20000	the maximum number of statements and transa
 sql.stats.response.show_internal.enabled	boolean	false	controls if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pages	application
 sql.stats.system_tables.enabled	boolean	true	when true, enables use of statistics on system tables by the query optimizer	application
 sql.stats.system_tables_autostats.enabled	boolean	true	when true, enables automatic collection of statistics on system tables	application
+sql.stats.table_statistics_cache.capacity	integer	256	the maximum number of table statistics entries stored in the LRU cache	application
 sql.stats.virtual_computed_columns.enabled	boolean	true	set to true to collect table statistics on virtual computed columns	application
 sql.telemetry.query_sampling.enabled	boolean	false	when set to true, executed queries will emit an event on the telemetry logging channel	application
 sql.telemetry.query_sampling.internal.enabled	boolean	false	when set to true, internal queries will be sampled in telemetry logging	application

docs/generated/settings/settings.html

@@ -333,6 +333,7 @@
 <tr><td><div id="setting-sql-stats-response-show-internal-enabled" class="anchored"><code>sql.stats.response.show_internal.enabled</code></div></td><td>boolean</td><td><code>false</code></td><td>controls if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pages</td><td>Serverless/Dedicated/Self-Hosted</td></tr>
 <tr><td><div id="setting-sql-stats-system-tables-enabled" class="anchored"><code>sql.stats.system_tables.enabled</code></div></td><td>boolean</td><td><code>true</code></td><td>when true, enables use of statistics on system tables by the query optimizer</td><td>Serverless/Dedicated/Self-Hosted</td></tr>
 <tr><td><div id="setting-sql-stats-system-tables-autostats-enabled" class="anchored"><code>sql.stats.system_tables_autostats.enabled</code></div></td><td>boolean</td><td><code>true</code></td><td>when true, enables automatic collection of statistics on system tables</td><td>Serverless/Dedicated/Self-Hosted</td></tr>
+<tr><td><div id="setting-sql-stats-table-statistics-cache-capacity" class="anchored"><code>sql.stats.table_statistics_cache.capacity</code></div></td><td>integer</td><td><code>256</code></td><td>the maximum number of table statistics entries stored in the LRU cache</td><td>Serverless/Dedicated/Self-Hosted</td></tr>
 <tr><td><div id="setting-sql-stats-virtual-computed-columns-enabled" class="anchored"><code>sql.stats.virtual_computed_columns.enabled</code></div></td><td>boolean</td><td><code>true</code></td><td>set to true to collect table statistics on virtual computed columns</td><td>Serverless/Dedicated/Self-Hosted</td></tr>
 <tr><td><div id="setting-sql-telemetry-query-sampling-enabled" class="anchored"><code>sql.telemetry.query_sampling.enabled</code></div></td><td>boolean</td><td><code>false</code></td><td>when set to true, executed queries will emit an event on the telemetry logging channel</td><td>Serverless/Dedicated/Self-Hosted</td></tr>
 <tr><td><div id="setting-sql-telemetry-query-sampling-internal-enabled" class="anchored"><code>sql.telemetry.query_sampling.internal.enabled</code></div></td><td>boolean</td><td><code>false</code></td><td>when set to true, internal queries will be sampled in telemetry logging</td><td>Serverless/Dedicated/Self-Hosted</td></tr>

pkg/server/config.go

@@ -87,8 +87,6 @@ const (
 	minimumNetworkFileDescriptors     = 256
 	recommendedNetworkFileDescriptors = 5000
 
-	defaultSQLTableStatCacheSize = 256
-
 	// This comes out to 1024 cache entries.
 	defaultSQLQueryCacheSize = 8 * 1024 * 1024
 )
@@ -500,10 +498,6 @@ type SQLConfig struct {
 	// used by SQL clients to store row data in server RAM.
 	MemoryPoolSize int64
 
-	// TableStatCacheSize is the size (number of tables) of the table
-	// statistics cache.
-	TableStatCacheSize int
-
 	// QueryCacheSize is the memory size (in bytes) of the query plan cache.
 	QueryCacheSize int64
 
@@ -570,7 +564,6 @@ func (sqlCfg *SQLConfig) SetDefaults(tempStorageCfg base.TempStorageConfig) {
 	tenName := sqlCfg.TenantName
 	*sqlCfg = SQLConfig{TenantID: tenID, TenantName: tenName}
 	sqlCfg.MemoryPoolSize = defaultSQLMemoryPoolSize
-	sqlCfg.TableStatCacheSize = defaultSQLTableStatCacheSize
 	sqlCfg.QueryCacheSize = defaultSQLQueryCacheSize
 	sqlCfg.TempStorageConfig = tempStorageCfg
 	sqlCfg.LicenseEnforcer = license.NewEnforcer(nil)

pkg/server/server_controller_new_server.go

@@ -354,7 +354,6 @@ func makeSharedProcessTenantServerConfig(
 	// of them will be mostly idle.
 	// We might want to reconsider this if we use more than 1 in-memory tenant at a time.
 	sqlCfg.MemoryPoolSize = kvServerCfg.SQLConfig.MemoryPoolSize
-	sqlCfg.TableStatCacheSize = kvServerCfg.SQLConfig.TableStatCacheSize
 	sqlCfg.QueryCacheSize = kvServerCfg.SQLConfig.QueryCacheSize
 
 	// LocalKVServerInfo tells the rpc.Context of the tenant's server

pkg/server/server_sql.go

@@ -1039,7 +1039,6 @@ func newSQLServer(ctx context.Context, cfg sqlServerArgs) (*SQLServer, error) {
 		),
 
 		TableStatsCache: stats.NewTableStatisticsCache(
-			cfg.TableStatCacheSize,
 			cfg.Settings,
 			cfg.internalDB,
 			cfg.stopper,

pkg/sql/logictest/testdata/logic_test/stats

@@ -122,3 +122,32 @@ query II
 SELECT row_count, distinct_count FROM [SHOW STATISTICS FOR TABLE t141448] WHERE column_names = ARRAY['b'];
 ----
 3  1
+
+subtest table_stats_cache_settings
+
+# Verify the table statistics cache capacity setting.
+query I
+SHOW CLUSTER SETTING sql.stats.table_statistics_cache.capacity
+----
+256
+
+statement ok
+SET CLUSTER SETTING sql.stats.table_statistics_cache.capacity = 128
+
+query I
+SHOW CLUSTER SETTING sql.stats.table_statistics_cache.capacity
+----
+128
+
+statement ok
+RESET CLUSTER SETTING sql.stats.table_statistics_cache.capacity
+
+query I
+SHOW CLUSTER SETTING sql.stats.table_statistics_cache.capacity
+----
+256
+
+statement error cannot be set to a negative value
+SET CLUSTER SETTING sql.stats.table_statistics_cache.capacity = -1
+
+subtest end

pkg/sql/stats/automatic_stats_test.go

@@ -67,7 +67,6 @@ func TestMaybeRefreshStats(t *testing.T) {
 	internalDB := s.InternalDB().(descs.DB)
 	descA := desctestutils.TestingGetPublicTableDescriptor(s.DB(), codec, "t", "a")
 	cache := NewTableStatisticsCache(
-		10, /* cacheSize */
 		s.ClusterSettings(),
 		s.InternalDB().(descs.DB),
 		s.AppStopper(),
@@ -229,7 +228,6 @@ func TestEnsureAllTablesQueries(t *testing.T) {
 
 	internalDB := s.InternalDB().(descs.DB)
 	cache := NewTableStatisticsCache(
-		10, /* cacheSize */
 		s.ClusterSettings(),
 		s.InternalDB().(descs.DB),
 		s.AppStopper(),
@@ -332,7 +330,6 @@ func BenchmarkEnsureAllTables(b *testing.B) {
 
 			internalDB := s.InternalDB().(descs.DB)
 			cache := NewTableStatisticsCache(
-				10, /* cacheSize */
 				s.ClusterSettings(),
 				s.InternalDB().(descs.DB),
 				s.AppStopper(),
@@ -406,7 +403,6 @@ func TestAverageRefreshTime(t *testing.T) {
 	internalDB := s.InternalDB().(descs.DB)
 	table := desctestutils.TestingGetPublicTableDescriptor(s.DB(), codec, "t", "a")
 	cache := NewTableStatisticsCache(
-		10, /* cacheSize */
 		s.ClusterSettings(),
 		s.InternalDB().(descs.DB),
 		s.AppStopper(),
@@ -656,7 +652,6 @@ func TestAutoStatsReadOnlyTables(t *testing.T) {
 
 	internalDB := s.InternalDB().(descs.DB)
 	cache := NewTableStatisticsCache(
-		10, /* cacheSize */
 		s.ClusterSettings(),
 		s.InternalDB().(descs.DB),
 		s.AppStopper(),
@@ -712,7 +707,6 @@ func TestAutoStatsOnStartupClusterSettingOff(t *testing.T) {
 
 	internalDB := s.InternalDB().(descs.DB)
 	cache := NewTableStatisticsCache(
-		10, /* cacheSize */
 		s.ClusterSettings(),
 		s.InternalDB().(descs.DB),
 		s.AppStopper(),
@@ -760,7 +754,6 @@ func TestNoRetryOnFailure(t *testing.T) {
 
 	internalDB := s.InternalDB().(descs.DB)
 	cache := NewTableStatisticsCache(
-		10, /* cacheSize */
 		s.ClusterSettings(),
 		s.InternalDB().(descs.DB),
 		s.AppStopper(),
@@ -878,7 +871,6 @@ func TestAnalyzeSystemTables(t *testing.T) {
 	defer evalCtx.Stop(ctx)
 	executor := s.InternalExecutor().(isql.Executor)
 	cache := NewTableStatisticsCache(
-		10, /* cacheSize */
 		s.ClusterSettings(),
 		s.InternalDB().(descs.DB),
 		s.AppStopper(),
@@ -999,7 +991,6 @@ func TestAutoStatsDisabledReadOnlyTenant(t *testing.T) {
 	internalDB := s.InternalDB().(descs.DB)
 	descA := desctestutils.TestingGetPublicTableDescriptor(s.DB(), codec, "t", "a")
 	cache := NewTableStatisticsCache(
-		10, /* cacheSize */
 		s.ClusterSettings(),
 		s.InternalDB().(descs.DB),
 		s.AppStopper(),

pkg/sql/stats/delete_stats_test.go

@@ -40,7 +40,6 @@ func TestDeleteOldStatsForColumns(t *testing.T) {
 	s := srv.ApplicationLayer()
 	db := s.InternalDB().(descs.DB)
 	cache := NewTableStatisticsCache(
-		10, /* cacheSize */
 		s.ClusterSettings(),
 		db,
 		s.AppStopper(),
@@ -341,7 +340,6 @@ func TestDeleteOldStatsForOtherColumns(t *testing.T) {
 	s := srv.ApplicationLayer()
 	db := s.InternalDB().(isql.DB)
 	cache := NewTableStatisticsCache(
-		10, /* cacheSize */
 		s.ClusterSettings(),
 		s.InternalDB().(descs.DB),
 		s.AppStopper(),

pkg/sql/stats/stats_cache.go

@@ -18,6 +18,7 @@ import (
 	"github.com/cockroachdb/cockroach/pkg/kv/kvclient/rangefeed"
 	"github.com/cockroachdb/cockroach/pkg/kv/kvpb"
 	"github.com/cockroachdb/cockroach/pkg/roachpb"
+	"github.com/cockroachdb/cockroach/pkg/settings"
 	"github.com/cockroachdb/cockroach/pkg/settings/cluster"
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog"
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/catenumpb"
@@ -39,6 +40,17 @@ import (
 	"github.com/cockroachdb/errors"
 )
 
+// TableStatsCacheSize controls the maximum number of table statistics entries
+// in the cache.
+var TableStatsCacheSize = settings.RegisterIntSetting(
+	settings.ApplicationLevel,
+	"sql.stats.table_statistics_cache.capacity",
+	"the maximum number of table statistics entries stored in the LRU cache",
+	256,
+	settings.NonNegativeInt,
+	settings.WithPublic,
+)
+
 // A TableStatistic object holds a statistic for a particular column or group
 // of columns.
 type TableStatistic struct {
@@ -113,19 +125,22 @@ type cacheEntry struct {
 	err error
 }
 
-// NewTableStatisticsCache creates a new TableStatisticsCache that can hold
-// statistics for <cacheSize> tables.
+// NewTableStatisticsCache creates a new TableStatisticsCache. The maximum
+// number of entries is controlled by the
+// sql.stats.table_statistics_cache.capacity cluster setting.
 func NewTableStatisticsCache(
-	cacheSize int, settings *cluster.Settings, db descs.DB, stopper *stop.Stopper,
+	settings *cluster.Settings, db descs.DB, stopper *stop.Stopper,
 ) *TableStatisticsCache {
 	tableStatsCache := &TableStatisticsCache{
 		db:       db,
 		settings: settings,
 		stopper:  stopper,
 	}
 	tableStatsCache.mu.cache = cache.NewUnorderedCache(cache.Config{
-		Policy:      cache.CacheLRU,
-		ShouldEvict: func(s int, key, value interface{}) bool { return s > cacheSize },
+		Policy: cache.CacheLRU,
+		ShouldEvict: func(s int, key, value interface{}) bool {
+			return s > int(TableStatsCacheSize.Get(&settings.SV))
+		},
 	})
 	return tableStatsCache
 }

pkg/sql/stats/stats_cache_test.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/cockroachdb/cockroach/pkg/base"
 	"github.com/cockroachdb/cockroach/pkg/kv/kvclient/rangefeed"
+	"github.com/cockroachdb/cockroach/pkg/settings/cluster"
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/descpb"
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/descs"
 	"github.com/cockroachdb/cockroach/pkg/sql/catalog/desctestutils"
@@ -210,6 +211,65 @@ func initTestData(
 	return expectedStats, nil
 }
 
+// addTestEntry adds a cache entry with the given stats directly. The caller
+// must hold sc.mu.
+func addTestEntry(
+	ctx context.Context, sc *TableStatisticsCache, tableID descpb.ID, stats []*TableStatistic,
+) *cacheEntry {
+	e := &cacheEntry{
+		stats:    stats,
+		waitCond: sync.Cond{L: &sc.mu},
+	}
+	sc.mu.cache.Add(tableID, e)
+	return e
+}
+
+func TestCacheCapacitySetting(t *testing.T) {
+	defer leaktest.AfterTest(t)()
+	defer log.Scope(t).Close(t)
+
+	ctx := context.Background()
+	st := cluster.MakeTestingClusterSettings()
+
+	sc := NewTableStatisticsCache(st, nil /* db */, nil /* stopper */)
+
+	sc.mu.Lock()
+	defer sc.mu.Unlock()
+
+	emptyStats := []*TableStatistic{{
+		TableStatisticProto: TableStatisticProto{
+			TableID:     1,
+			StatisticID: 1,
+			ColumnIDs:   []descpb.ColumnID{1},
+		},
+	}}
+
+	// Default capacity is 256; add 5 entries.
+	for i := 1; i <= 5; i++ {
+		addTestEntry(ctx, sc, descpb.ID(i), emptyStats)
+	}
+	require.Equal(t, 5, sc.mu.cache.Len())
+
+	// Lower the capacity to 3. Existing entries remain until new entries
+	// push the cache past the limit.
+	TableStatsCacheSize.Override(ctx, &st.SV, 3)
+
+	// Adding a sixth entry should trigger eviction down to the new limit.
+	addTestEntry(ctx, sc, 6, emptyStats)
+	require.Equal(t, 3, sc.mu.cache.Len())
+
+	// The most recently accessed entries should remain.
+	_, ok := sc.mu.cache.Get(descpb.ID(6))
+	require.True(t, ok, "newest entry should be in cache")
+
+	// Raise the capacity — should allow more entries without eviction.
+	TableStatsCacheSize.Override(ctx, &st.SV, 10)
+	for i := 7; i <= 12; i++ {
+		addTestEntry(ctx, sc, descpb.ID(i), emptyStats)
+	}
+	require.Equal(t, 9, sc.mu.cache.Len())
+}
+
 func TestCacheBasic(t *testing.T) {
 	defer leaktest.AfterTest(t)()
 	defer log.Scope(t).Close(t)
@@ -235,7 +295,8 @@ func TestCacheBasic(t *testing.T) {
 	// Create a cache and iteratively query the cache for each tableID. This
 	// will result in the cache getting populated. When the stats cache size is
 	// exceeded, entries should be evicted according to the LRU policy.
-	sc := NewTableStatisticsCache(2 /* cacheSize */, s.ClusterSettings(), db, s.AppStopper())
+	TableStatsCacheSize.Override(ctx, &s.ClusterSettings().SV, 2)
+	sc := NewTableStatisticsCache(s.ClusterSettings(), db, s.AppStopper())
 	require.NoError(t, sc.Start(ctx, s.Codec(), s.RangeFeedFactory().(*rangefeed.Factory)))
 	for _, tableID := range tableIDs {
 		checkStatsForTable(ctx, t, sc, expectedStats[tableID], tableID)
@@ -337,7 +398,8 @@ func TestCacheUserDefinedTypes(t *testing.T) {
 	insqlDB := s.InternalDB().(descs.DB)
 
 	// Make a stats cache.
-	sc := NewTableStatisticsCache(1, s.ClusterSettings(), insqlDB, s.AppStopper())
+	TableStatsCacheSize.Override(ctx, &s.ClusterSettings().SV, 1)
+	sc := NewTableStatisticsCache(s.ClusterSettings(), insqlDB, s.AppStopper())
 	require.NoError(t, sc.Start(ctx, s.Codec(), s.RangeFeedFactory().(*rangefeed.Factory)))
 	tbl := desctestutils.TestingGetPublicTableDescriptor(kvDB, s.Codec(), "t", "tt")
 	// Get stats for our table. We are ensuring here that the access to the stats
@@ -390,7 +452,8 @@ func TestCacheWait(t *testing.T) {
 		tableIDs = append(tableIDs, tableID)
 	}
 	sort.Sort(tableIDs)
-	sc := NewTableStatisticsCache(len(tableIDs) /* cacheSize */, s.ClusterSettings(), db, s.AppStopper())
+	TableStatsCacheSize.Override(ctx, &s.ClusterSettings().SV, int64(len(tableIDs)))
+	sc := NewTableStatisticsCache(s.ClusterSettings(), db, s.AppStopper())
 	require.NoError(t, sc.Start(ctx, s.Codec(), s.RangeFeedFactory().(*rangefeed.Factory)))
 	for _, tableID := range tableIDs {
 		checkStatsForTable(ctx, t, sc, expectedStats[tableID], tableID)
@@ -438,8 +501,8 @@ func TestCacheAutoRefresh(t *testing.T) {
 	tc := serverutils.StartCluster(t, 3 /* numNodes */, base.TestClusterArgs{})
 	defer tc.Stopper().Stop(ctx)
 	s := tc.ApplicationLayer(0)
+	TableStatsCacheSize.Override(ctx, &s.ClusterSettings().SV, 10)
 	sc := NewTableStatisticsCache(
-		10, /* cacheSize */
 		s.ClusterSettings(),
 		s.InternalDB().(descs.DB),
 		s.AppStopper(),