sql: introduce canary stats settings

pkg/cli/testdata/doctor/test_recreate_zipdir

@@ -14,5 +14,5 @@ SELECT crdb_internal.unsafe_upsert_namespace_entry(100, 0, 'public', 101, true);
 SELECT crdb_internal.unsafe_upsert_descriptor(102, decode('125a0a08706f73746772657310661a300a0b0a0561646d696e100218020a0d0a067075626c696310801018000a0a0a04726f6f74100218021204726f6f741803220028013a0c0a067075626c69631202086740004a005a0210007000', 'hex'), true);
 SELECT crdb_internal.unsafe_upsert_namespace_entry(0, 0, 'postgres', 102, true);
 SELECT crdb_internal.unsafe_upsert_descriptor(103, decode('2249086612067075626c6963186722310a0b0a0561646d696e100218020a0d0a067075626c696310840418000a0a0a04726f6f7410021802120561646d696e18032a00300140004a007000', 'hex'), true);
-SELECT crdb_internal.unsafe_upsert_descriptor(104, decode('0a8d030a01741868206428013a0042280a016910011a0e0801104018002a0030005014600020013000680070007800800100880100980100423c0a05726f77696410021a0e0801104018002a0030005014600020002a0e756e697175655f726f77696428293001680070007800800100880100980100480352780a06745f706b6579100118012205726f7769642a0169300240004a10080010001a00200028003000380040005a0070017a0408002000800100880100900104980101a20106080012001800a80100b20100ba0100c00100c801d88aed86ddb7c5e517d00101e00100e9010000000000000000f20100f8010060026a210a0b0a0561646d696e100218020a0a0a04726f6f74100218021204726f6f741803800101880103980100b2011b0a077072696d61727910001a01691a05726f776964200120022801b80101c20100e80100f2010408001200f801008002009202009a0200b20200b80200c00265c80200e00200800300880302a80300b00300d00300d80300e00300f80300880400980400a00400a80400b00400', 'hex'), true);
+SELECT crdb_internal.unsafe_upsert_descriptor(104, decode('0a90030a01741868206428013a0042280a016910011a0e0801104018002a0030005014600020013000680070007800800100880100980100423c0a05726f77696410021a0e0801104018002a0030005014600020002a0e756e697175655f726f77696428293001680070007800800100880100980100480352780a06745f706b6579100118012205726f7769642a0169300240004a10080010001a00200028003000380040005a0070017a0408002000800100880100900104980101a20106080012001800a80100b20100ba0100c00100c801d88aed86ddb7c5e517d00101e00100e9010000000000000000f20100f8010060026a210a0b0a0561646d696e100218020a0a0a04726f6f74100218021204726f6f741803800101880103980100b2011b0a077072696d61727910001a01691a05726f776964200120022801b80101c20100e80100f2010408001200f801008002009202009a0200b20200b80200c00265c80200e00200800300880302a80300b00300d00300d80300e00300f80300880400980400a00400a80400b00400b80400', 'hex'), true);
 COMMIT;

pkg/sql/catalog/descpb/structured.proto

@@ -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/sql/catalog/tabledesc/structured.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/sql/catalog/tabledesc/ttl.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/sql/catalog/tabledesc/validate_test.go

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

pkg/sql/logictest/testdata/logic_test/canary_stats

@@ -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')

pkg/sql/opt/BUILD.bazel

@@ -29,6 +29,7 @@ go_library(
         "//pkg/clusterversion",
         "//pkg/security/username",
         "//pkg/server/telemetry",
+        "//pkg/settings",
         "//pkg/sql/catalog",
         "//pkg/sql/catalog/catpb",
         "//pkg/sql/catalog/colinfo",