sql: introduce canary_window storage parameter

This commit introduces a new table-level storage parameter
`canary_window` that can be specified in CREATE TABLE or ALTER TABLE
statements. The canary window specifies how long newly collected
statistics will remain in "canary" state before being promoted to
stable, enabling gradual rollout of new statistics to mitigate
performance regressions.

When set to a non-zero duration, this parameter enables canary
statistics rollout for the table. During the canary window, the cluster
setting sql.stats.canary_fraction (introduced in the next commit)
determines what percentage of queries use the new canary statistics
versus the previous stable statistics, providing a buffer period for
observation and intervention.

The window is capped by 48 hours to avoid an outrageously long canary
window.

Note that this commit adds only syntax support and storage for the
parameter. The actual canary statistics selection logic will be
implemented in subsequent commits.

Release note (sql change): A new table storage parameter `canary_window`
has been introduced to enable gradual rollout of newly collected table
statistics. It takes a duration string as the value, with maximum
allowed duration 48 hours. When set with a non-negative duration, the
new statistics remain in a "canary" state for the specified duration
before being promoted to stable. This allows for controlled exposure
and intervention opportunities before statistics are fully deployed
across all queries.

Author: ZhouXing19

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

@@ -1378,7 +1378,15 @@ message TableDescriptor {
   optional uint32 rbr_using_constraint = 70 [(gogoproto.nullable) = false,
     (gogoproto.customname) = "RBRUsingConstraint", (gogoproto.casttype) = "ConstraintID"];
 
-  // Next ID: 71
+  // CanaryWindowSize specifies the duration for which newly collected statistics
+  // remain in "canary" state before being promoted to stable. During this
+  // window, the cluster setting sql.stats.canary_fraction determines what
+  // percentage of queries use the new canary statistics vs. the previous stable
+  // statistics. This provides a buffer period for observation and intervention
+  // before new statistics are fully deployed to all queries throughout the
+  // cluster.
+  optional int64 canary_window_size = 71 [(gogoproto.nullable) = false, (gogoproto.casttype)="time.Duration"];
+  // Next ID: 72
 }
 
 // ExternalRowData indicates that the row data for this object is stored outside

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

@@ -2604,6 +2604,9 @@ func (desc *wrapper) GetStorageParams(spaceBetweenEqual bool) ([]string, error)
 	if desc.IsSchemaLocked() {
 		appendStorageParam(`schema_locked`, `true`)
 	}
+	if desc.CanaryWindowSize != 0 {
+		appendStorageParam(`canary_window`, fmt.Sprintf(`'%s'`, desc.CanaryWindowSize.String()))
+	}
 	if usingFK := desc.GetRegionalByRowUsingConstraint(); usingFK != descpb.ConstraintID(0) {
 		// NOTE: when validating the descriptor, we check that the referenced
 		// constraint exists, so this should never fail.

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

@@ -55,7 +55,7 @@ func ValidateRowLevelTTL(ttl *catpb.RowLevelTTL) error {
 		}
 	}
 	if ttl.RowStatsPollInterval != 0 {
-		if err := ValidateTTLRowStatsPollInterval("ttl_row_stats_poll_interval", ttl.RowStatsPollInterval); err != nil {
+		if err := ValidateNotNegativeInterval("ttl_row_stats_poll_interval", ttl.RowStatsPollInterval); err != nil {
 			return err
 		}
 	}
@@ -154,9 +154,8 @@ func ValidateTTLCronExpr(key string, str string) error {
 	return nil
 }
 
-// ValidateTTLRowStatsPollInterval validates the automatic statistics field
-// of TTL.
-func ValidateTTLRowStatsPollInterval(key string, val time.Duration) error {
+// ValidateNotNegativeInterval validates the provided interval is not negative.
+func ValidateNotNegativeInterval(key string, val time.Duration) error {
 	if val < 0 {
 		return pgerror.Newf(
 			pgcode.InvalidParameterValue,

pkg/cli/testdata/doctor/test_recreate_zipdir-json

@@ -148,6 +148,7 @@ var validationMap = []struct {
 			"RowLevelSecurityEnabled": {status: thisFieldReferencesNoObjects},
 			"RowLevelSecurityForced":  {status: thisFieldReferencesNoObjects},
 			"RBRUsingConstraint":      {status: iSolemnlySwearThisFieldIsValidated},
+			"CanaryWindowSize":        {status: thisFieldReferencesNoObjects},
 		},
 	},
 	{

pkg/sql/catalog/descpb/structured.proto

@@ -0,0 +1,51 @@
+# LogicTest: !local-prepared
+
+statement ok
+DROP TABLE IF EXISTS canary_table;
+
+# To avoid test flake.
+statement ok
+SET create_table_with_schema_locked=false
+
+statement ok
+CREATE TABLE canary_table (x int primary key, y int, FAMILY (x, y)) WITH (canary_window = '20s');
+
+query TT
+SHOW CREATE TABLE canary_table
+----
+canary_table  CREATE TABLE public.canary_table (
+                x INT8 NOT NULL,
+                y INT8 NULL,
+                CONSTRAINT canary_table_pkey PRIMARY KEY (x ASC),
+                FAMILY fam_0_x_y (x, y)
+              ) WITH (canary_window = '20s');
+
+let $table_creation_ts
+SELECT now()
+
+statement ok
+ALTER TABLE canary_table SET (canary_window = '30s');
+
+# Test the gating with a value that exceeds the maximum allowed canary window.
+statement error canary window size 72h0m0s exceeds maximum allowed value of 48 hours
+ALTER TABLE canary_table SET (canary_window = '259200s');
+
+query TT
+SHOW CREATE TABLE canary_table
+----
+canary_table  CREATE TABLE public.canary_table (
+                x INT8 NOT NULL,
+                y INT8 NULL,
+                CONSTRAINT canary_table_pkey PRIMARY KEY (x ASC),
+                FAMILY fam_0_x_y (x, y)
+              ) WITH (canary_window = '30s');
+
+query T
+SELECT create_statement FROM crdb_internal.create_statements AS OF SYSTEM TIME '$table_creation_ts' WHERE descriptor_name = 'canary_table';
+----
+CREATE TABLE public.canary_table (
+  x INT8 NOT NULL,
+  y INT8 NULL,
+  CONSTRAINT canary_table_pkey PRIMARY KEY (x ASC),
+  FAMILY fam_0_x_y (x, y)
+) WITH (canary_window = '20s')