Merge #151502

craig[bot] · dhartunian · craig[bot] · commit adc3de4f98d8 · 2025-09-12T15:21:55.000Z
151502: sql: set fraction stale rows to 4 on sql stats tables r=michae2,alyshanjahani-crl a=dhartunian Previously, stats collection on StatementStatisticsTableSchema and TransactionStatisticsTableSchema were triggered at 20% stale rows which was very low and would trigger often during flushing of SQL statement stats. This commit adds a migration that sets `sql_stats_automatic_collection_fraction_stale_rows` at 4 which will reduce stats collection overhead. Since this table is updated very regularly, we expect stats to stay up to date even with the higher threshold. As recommended, we also set `sql_stats_automatic_partial_collection_fraction_stale_rows` to 1.0 Michael Erickson contributed helpful insights: See #147443 (comment) for calculations that led to the number selection. There was an additional discussion on this PR regarding setting static stats, that was also rejected since the queries running on these tables are varied and complex. See #151502 (review) Resolves: #147443 Epic: None Release note: None Co-authored-by: David Hartunian <davidh@cockroachlabs.com>
diff --git a/docs/generated/settings/settings-for-tenants.txt b/docs/generated/settings/settings-for-tenants.txt
@@ -421,4 +421,4 @@ trace.zipkin.collector	string		the address of a Zipkin instance to receive trace
 ui.database_locality_metadata.enabled	boolean	true	if enabled shows extended locality data about databases and tables in DB Console which can be expensive to compute	application
 ui.default_timezone	string		the default timezone used to format timestamps in the ui	application
 ui.display_timezone	enumeration	etc/utc	the timezone used to format timestamps in the ui. This setting is deprecatedand will be removed in a future version. Use the 'ui.default_timezone' setting instead. 'ui.default_timezone' takes precedence over this setting. [etc/utc = 0, america/new_york = 1]	application
-version	version	1000025.3-upgrading-to-1000025.4-step-010	set the active cluster version in the format '<major>.<minor>'	application
+version	version	1000025.3-upgrading-to-1000025.4-step-012	set the active cluster version in the format '<major>.<minor>'	application
diff --git a/docs/generated/settings/settings.html b/docs/generated/settings/settings.html
@@ -379,6 +379,6 @@
 <tr><td><div id="setting-ui-database-locality-metadata-enabled" class="anchored"><code>ui.database_locality_metadata.enabled</code></div></td><td>boolean</td><td><code>true</code></td><td>if enabled shows extended locality data about databases and tables in DB Console which can be expensive to compute</td><td>Basic/Standard/Advanced/Self-Hosted</td></tr>
 <tr><td><div id="setting-ui-default-timezone" class="anchored"><code>ui.default_timezone</code></div></td><td>string</td><td><code></code></td><td>the default timezone used to format timestamps in the ui</td><td>Basic/Standard/Advanced/Self-Hosted</td></tr>
 <tr><td><div id="setting-ui-display-timezone" class="anchored"><code>ui.display_timezone</code></div></td><td>enumeration</td><td><code>etc/utc</code></td><td>the timezone used to format timestamps in the ui. This setting is deprecatedand will be removed in a future version. Use the &#39;ui.default_timezone&#39; setting instead. &#39;ui.default_timezone&#39; takes precedence over this setting. [etc/utc = 0, america/new_york = 1]</td><td>Basic/Standard/Advanced/Self-Hosted</td></tr>
-<tr><td><div id="setting-version" class="anchored"><code>version</code></div></td><td>version</td><td><code>1000025.3-upgrading-to-1000025.4-step-010</code></td><td>set the active cluster version in the format &#39;&lt;major&gt;.&lt;minor&gt;&#39;</td><td>Basic/Standard/Advanced/Self-Hosted</td></tr>
+<tr><td><div id="setting-version" class="anchored"><code>version</code></div></td><td>version</td><td><code>1000025.3-upgrading-to-1000025.4-step-012</code></td><td>set the active cluster version in the format &#39;&lt;major&gt;.&lt;minor&gt;&#39;</td><td>Basic/Standard/Advanced/Self-Hosted</td></tr>
 </tbody>
 </table>
diff --git a/pkg/clusterversion/cockroach_versions.go b/pkg/clusterversion/cockroach_versions.go
@@ -222,6 +222,11 @@ const (
 	// system.statement_diagnostics to support transaction-level diagnostic bundle collection.
 	V25_4_TransactionDiagnosticsSupport
 
+	// V25_4_SystemStatsTablesAutostatsFraction sets the autostats fraction for
+	// system.statement_statistics and system.transaction_statistics to 0.9
+	// to reduce frequent automatic statistics collection.
+	V25_4_SystemStatsTablesAutostatsFraction
+
 	// *************************************************
 	// Step (1) Add new versions above this comment.
 	// Do not add new versions to a patch release.
@@ -281,6 +286,8 @@ var versionTable = [numKeys]roachpb.Version{
 
 	V25_4_TransactionDiagnosticsSupport: {Major: 25, Minor: 3, Internal: 10},
 
+	V25_4_SystemStatsTablesAutostatsFraction: {Major: 25, Minor: 3, Internal: 12},
+
 	// *************************************************
 	// Step (2): Add new versions above this comment.
 	// Do not add new versions to a patch release.
diff --git a/pkg/sql/catalog/bootstrap/testdata/testdata b/pkg/sql/catalog/bootstrap/testdata/testdata
diff --git a/pkg/sql/catalog/systemschema/system.go b/pkg/sql/catalog/systemschema/system.go
@@ -702,7 +702,7 @@ CREATE TABLE system.statement_statistics (
 			total_estimated_execution_time,
 			p99_latency
 		)
-)
+) WITH (sql_stats_automatic_collection_fraction_stale_rows = 4, sql_stats_automatic_partial_collection_fraction_stale_rows = 1);
 `
 
 	TransactionStatisticsTableSchema = `
@@ -751,7 +751,7 @@ CREATE TABLE system.transaction_statistics (
 			total_estimated_execution_time,
 			p99_latency
 		)
-);
+) WITH (sql_stats_automatic_collection_fraction_stale_rows = 4, sql_stats_automatic_partial_collection_fraction_stale_rows = 1);
 `
 
 	StatementActivityTableSchema = `
@@ -1421,7 +1421,7 @@ const SystemDatabaseName = catconstants.SystemDatabaseName
 // release version).
 //
 // NB: Don't set this to clusterversion.Latest; use a specific version instead.
-var SystemDatabaseSchemaBootstrapVersion = clusterversion.V25_4_TransactionDiagnosticsSupport.Version()
+var SystemDatabaseSchemaBootstrapVersion = clusterversion.V25_4_SystemStatsTablesAutostatsFraction.Version()
 
 // MakeSystemDatabaseDesc constructs a copy of the system database
 // descriptor.
@@ -3380,6 +3380,10 @@ var (
 				ConstraintID:          tbl.NextConstraintID,
 			}}
 			tbl.NextConstraintID++
+			tbl.AutoStatsSettings = &catpb.AutoStatsSettings{
+				FractionStaleRows:        &[]float64{4.0}[0],
+				PartialFractionStaleRows: &[]float64{1.0}[0],
+			}
 		},
 	)
 
@@ -3604,6 +3608,10 @@ var (
 				ConstraintID:          tbl.NextConstraintID,
 			}}
 			tbl.NextConstraintID++
+			tbl.AutoStatsSettings = &catpb.AutoStatsSettings{
+				FractionStaleRows:        &[]float64{4.0}[0],
+				PartialFractionStaleRows: &[]float64{1.0}[0],
+			}
 		},
 	)
 
diff --git a/pkg/sql/catalog/systemschema_test/testdata/bootstrap_system b/pkg/sql/catalog/systemschema_test/testdata/bootstrap_system
diff --git a/pkg/sql/catalog/systemschema_test/testdata/bootstrap_tenant b/pkg/sql/catalog/systemschema_test/testdata/bootstrap_tenant
diff --git a/pkg/sql/logictest/testdata/logic_test/crdb_internal_catalog b/pkg/sql/logictest/testdata/logic_test/crdb_internal_catalog
@@ -133,7 +133,7 @@ skipif config schema-locked-disabled local-mixed-25.3
 query IT
 SELECT id, strip_volatile(descriptor) FROM crdb_internal.kv_catalog_descriptor WHERE id IN (1, 2, 3, 29, 4294966962) OR (id > 100 and id < 200) ORDER BY id
 ----
-1           {"database": {"id": 1, "name": "system", "privileges": {"ownerProto": "node", "users": [{"privileges": "2048", "userProto": "admin", "withGrantOption": "2048"}, {"privileges": "2048", "userProto": "root", "withGrantOption": "2048"}], "version": 3}, "systemDatabaseSchemaVersion": {"internal": 10, "majorVal": 1000025, "minorVal": 3}, "version": "1"}}
+1           {"database": {"id": 1, "name": "system", "privileges": {"ownerProto": "node", "users": [{"privileges": "2048", "userProto": "admin", "withGrantOption": "2048"}, {"privileges": "2048", "userProto": "root", "withGrantOption": "2048"}], "version": 3}, "systemDatabaseSchemaVersion": {"internal": 12, "majorVal": 1000025, "minorVal": 3}, "version": "1"}}
 3           {"table": {"columns": [{"id": 1, "name": "id", "type": {"family": "IntFamily", "oid": 20, "width": 64}}, {"id": 2, "name": "descriptor", "nullable": true, "type": {"family": "BytesFamily", "oid": 17}}], "formatVersion": 3, "id": 3, "name": "descriptor", "nextColumnId": 3, "nextConstraintId": 2, "nextIndexId": 2, "nextMutationId": 1, "parentId": 1, "primaryIndex": {"constraintId": 1, "encodingType": 1, "foreignKey": {}, "geoConfig": {}, "id": 1, "interleave": {}, "keyColumnDirections": ["ASC"], "keyColumnIds": [1], "keyColumnNames": ["id"], "name": "primary", "partitioning": {}, "sharded": {}, "storeColumnIds": [2], "storeColumnNames": ["descriptor"], "unique": true, "vecConfig": {}, "version": 4}, "privileges": {"ownerProto": "node", "users": [{"privileges": "32", "userProto": "admin", "withGrantOption": "32"}, {"privileges": "32", "userProto": "root", "withGrantOption": "32"}], "version": 3}, "replacementOf": {"time": {}}, "unexposedParentSchemaId": 29, "version": "1"}}
 29          {"schema": {"defaultPrivileges": {"type": "SCHEMA"}, "id": 29, "name": "public", "privileges": {"ownerProto": "node", "users": [{"privileges": "2", "userProto": "admin", "withGrantOption": "2"}, {"privileges": "516", "userProto": "public"}, {"privileges": "2", "userProto": "root", "withGrantOption": "2"}], "version": 3}, "version": "1"}}
 101         {"schema": {"id": 101, "name": "public", "parentId": 100, "privileges": {"ownerProto": "root", "users": [{"privileges": "2", "userProto": "admin", "withGrantOption": "2"}, {"privileges": "516", "userProto": "public"}, {"privileges": "2", "userProto": "root", "withGrantOption": "2"}], "version": 3}, "version": "1"}}
diff --git a/pkg/upgrade/upgrades/BUILD.bazel b/pkg/upgrade/upgrades/BUILD.bazel
@@ -20,6 +20,7 @@ go_library(
         "v25_3_add_hot_range_logger_job.go",
         "v25_3_add_users_last_login_time_column.go",
         "v25_4_inspect_errors_table.go",
+        "v25_4_system_stats_tables_autostats_fraction.go",
         "v25_4_transaction_diagnostics_tables.go",
     ],
     importpath = "github.com/cockroachdb/cockroach/pkg/upgrade/upgrades",
@@ -87,6 +88,7 @@ go_test(
         "v25_3_add_hot_range_logger_job_test.go",
         "v25_3_add_users_last_login_time_column_test.go",
         "v25_4_inspect_errors_table_test.go",
+        "v25_4_system_stats_tables_autostats_fraction_test.go",
         "v25_4_transaction_diagnostics_tables_test.go",
         "version_starvation_test.go",
     ],
diff --git a/pkg/upgrade/upgrades/upgrades.go b/pkg/upgrade/upgrades/upgrades.go
@@ -103,6 +103,14 @@ var upgrades = []upgradebase.Upgrade{
 		upgrade.RestoreActionNotRequired("cluster restore does not restore these tables"),
 	),
 
+	upgrade.NewTenantUpgrade(
+		"set autostats fraction for system stats tables",
+		clusterversion.V25_4_SystemStatsTablesAutostatsFraction.Version(),
+		upgrade.NoPrecondition,
+		systemStatsTablesAutostatsFractionMigration,
+		upgrade.RestoreActionNotRequired("cluster restore does not restore table storage parameters"),
+	),
+
 	// Note: when starting a new release version, the first upgrade (for
 	// Vxy_zStart) must be a newFirstUpgrade. Keep this comment at the bottom.
 }
diff --git a/pkg/upgrade/upgrades/v25_4_system_stats_tables_autostats_fraction.go b/pkg/upgrade/upgrades/v25_4_system_stats_tables_autostats_fraction.go
@@ -0,0 +1,48 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Use of this software is governed by the CockroachDB Software License
+// included in the /LICENSE file.
+
+package upgrades
+
+import (
+	"context"
+
+	"github.com/cockroachdb/cockroach/pkg/clusterversion"
+	"github.com/cockroachdb/cockroach/pkg/upgrade"
+)
+
+const (
+	updateStatementStatisticsAutostatsFraction = `
+ALTER TABLE system.statement_statistics
+SET (sql_stats_automatic_collection_fraction_stale_rows = 4, sql_stats_automatic_partial_collection_fraction_stale_rows = 1);
+`
+	updateTransactionStatisticsAutostatsFraction = `
+ALTER TABLE system.transaction_statistics
+SET (sql_stats_automatic_collection_fraction_stale_rows = 4, sql_stats_automatic_partial_collection_fraction_stale_rows = 1);
+`
+)
+
+func systemStatsTablesAutostatsFractionMigration(
+	ctx context.Context, version clusterversion.ClusterVersion, deps upgrade.TenantDeps,
+) error {
+	// Update statement statistics table
+	_, err := deps.InternalExecutor.Exec(
+		ctx, "update-statement-statistics-autostats-fraction",
+		nil, updateStatementStatisticsAutostatsFraction,
+	)
+	if err != nil {
+		return err
+	}
+
+	// Update transaction statistics table
+	_, err = deps.InternalExecutor.Exec(
+		ctx, "update-transaction-statistics-autostats-fraction",
+		nil, updateTransactionStatisticsAutostatsFraction,
+	)
+	if err != nil {
+		return err
+	}
+
+	return nil
+}
diff --git a/pkg/upgrade/upgrades/v25_4_system_stats_tables_autostats_fraction_test.go b/pkg/upgrade/upgrades/v25_4_system_stats_tables_autostats_fraction_test.go
@@ -0,0 +1,114 @@
+// Copyright 2025 The Cockroach Authors.
+//
+// Use of this software is governed by the CockroachDB Software License
+// included in the /LICENSE file.
+
+package upgrades_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/cockroachdb/cockroach/pkg/base"
+	"github.com/cockroachdb/cockroach/pkg/clusterversion"
+	"github.com/cockroachdb/cockroach/pkg/server"
+	"github.com/cockroachdb/cockroach/pkg/sql/catalog/descpb"
+	"github.com/cockroachdb/cockroach/pkg/sql/catalog/systemschema"
+	"github.com/cockroachdb/cockroach/pkg/testutils/testcluster"
+	"github.com/cockroachdb/cockroach/pkg/upgrade/upgrades"
+	"github.com/cockroachdb/cockroach/pkg/util/leaktest"
+	"github.com/cockroachdb/cockroach/pkg/util/log"
+	"github.com/stretchr/testify/require"
+)
+
+func TestStatsTablesAutostatsFunctionMigration(t *testing.T) {
+	defer leaktest.AfterTest(t)()
+	defer log.Scope(t).Close(t)
+
+	clusterversion.SkipWhenMinSupportedVersionIsAtLeast(t, clusterversion.V25_4)
+
+	clusterArgs := base.TestClusterArgs{
+		ServerArgs: base.TestServerArgs{
+			Knobs: base.TestingKnobs{
+				Server: &server.TestingKnobs{
+					DisableAutomaticVersionUpgrade: make(chan struct{}),
+					ClusterVersionOverride:         clusterversion.MinSupported.Version(),
+				},
+			},
+		},
+	}
+
+	var (
+		ctx   = context.Background()
+		tc    = testcluster.StartTestCluster(t, 1, clusterArgs)
+		s     = tc.Server(0)
+		sqlDB = tc.ServerConn(0)
+	)
+	defer tc.Stopper().Stop(ctx)
+
+	// Inject the old copy of the descriptors.
+	// Note: At the time of writing, injecting the legacy table is not
+	// necessary to make this test pass because the `MinSupportedVersion` is
+	// 25.2 and that version doesn't apply the `AutoStatsSettings` anyway.
+	// These are put here more to signal intent, but are not strictly
+	// required.
+	upgrades.InjectLegacyTable(ctx, t, s, systemschema.StatementStatisticsTable,
+		getOldStatementStatisticsTable)
+	upgrades.InjectLegacyTable(ctx, t, s, systemschema.TransactionStatisticsTable,
+		getOldTransactionStatisticsTable)
+
+	var createStatmentStats string
+	if err := sqlDB.QueryRow("SELECT create_statement FROM [SHOW CREATE TABLE system.statement_statistics]").Scan(&createStatmentStats); err != nil {
+		t.Fatal(err)
+	}
+	require.NotContains(t, createStatmentStats,
+		`WITH (sql_stats_automatic_collection_fraction_stale_rows = 4, sql_stats_automatic_partial_collection_fraction_stale_rows = 1);`)
+
+	var createTransactionStats string
+	if err := sqlDB.QueryRow("SELECT create_statement FROM [SHOW CREATE TABLE system.transaction_statistics]").Scan(&createTransactionStats); err != nil {
+		t.Fatal(err)
+	}
+	require.NotContains(t, createTransactionStats,
+		`WITH (sql_stats_automatic_collection_fraction_stale_rows = 4, sql_stats_automatic_partial_collection_fraction_stale_rows = 1);`)
+
+	// Run the upgrade.
+	upgrades.Upgrade(
+		t,
+		sqlDB,
+		clusterversion.V25_4_SystemStatsTablesAutostatsFraction,
+		nil,   /* done */
+		false, /* expectError */
+	)
+
+	var createStatementStatsAfter string
+	if err := sqlDB.QueryRow("SELECT create_statement FROM [SHOW CREATE TABLE system.statement_statistics]").Scan(&createStatementStatsAfter); err != nil {
+		t.Fatal(err)
+	}
+	require.Contains(t, createStatementStatsAfter,
+		`WITH (sql_stats_automatic_collection_fraction_stale_rows = 4, sql_stats_automatic_partial_collection_fraction_stale_rows = 1);`)
+
+	var createTransactionStatsAfter string
+	if err := sqlDB.QueryRow("SELECT create_statement FROM [SHOW CREATE TABLE system.transaction_statistics]").Scan(&createTransactionStatsAfter); err != nil {
+		t.Fatal(err)
+	}
+	require.Contains(t, createTransactionStatsAfter,
+		`WITH (sql_stats_automatic_collection_fraction_stale_rows = 4, sql_stats_automatic_partial_collection_fraction_stale_rows = 1);`)
+}
+
+func getOldTransactionStatisticsTable() *descpb.TableDescriptor {
+	// Copy the TransactionStatisticsTable definition from system.go but without AutoStatsSettings
+	tableDesc := *systemschema.TransactionStatisticsTable.TableDesc()
+	// Set version to 1 for injection and remove the AutoStatsSettings that were added in the v25.4 migration
+	tableDesc.Version = 1
+	tableDesc.AutoStatsSettings = nil
+	return &tableDesc
+}
+
+func getOldStatementStatisticsTable() *descpb.TableDescriptor {
+	// Copy the StatementStatisticsTable definition from system.go but without AutoStatsSettings
+	tableDesc := *systemschema.StatementStatisticsTable.TableDesc()
+	// Set version to 1 for injection and remove the AutoStatsSettings that were added in the v25.4 migration
+	tableDesc.Version = 1
+	tableDesc.AutoStatsSettings = nil
+	return &tableDesc
+}
