local_only_session_data.proto

// Copyright 2021 The Cockroach Authors.
//
// Use of this software is governed by the Business Source License
// included in the file licenses/BSL.txt.
//
// As of the Change Date specified in that file, in accordance with
// the Business Source License, use of this software will be governed
// by the Apache License, Version 2.0, included in the file
// licenses/APL.txt.

syntax = "proto3";
package cockroach.sql.sessiondatapb;
option go_package = "github.com/cockroachdb/cockroach/pkg/sql/sessiondatapb";

import "gogoproto/gogo.proto";

// LocalOnlySessionData contains the serializable components of session
// parameters that only influence execution on the gateway nodes.
message LocalOnlySessionData {
  // SaveTablesPrefix indicates that a table should be created with the
  // given prefix for the output of each subexpression in a query. If
  // SaveTablesPrefix is empty, no tables are created.
  string save_tables_prefix = 1;
  // OptimizerFKCascadesLimit is the maximum number of cascading operations that
  // are run for a single query.
  int64 optimizer_fk_cascades_limit = 2 [(gogoproto.customname) = "OptimizerFKCascadesLimit"];
  // StmtTimeout is the duration a query is permitted to run before it is
  // canceled by the session. If set to 0, there is no timeout.
  int64 stmt_timeout = 3 [(gogoproto.casttype) = "time.Duration"];
  // IdleInSessionTimeout is the duration a session is permitted to idle before
  // the session is canceled. If set to 0, there is no timeout.
  int64 idle_in_session_timeout = 4 [(gogoproto.casttype) = "time.Duration"];
  // IdleInTransactionSessionTimeout is the duration a session is permitted to
  // idle in a transaction before the session is canceled.
  // If set to 0, there is no timeout.
  int64 idle_in_transaction_session_timeout = 5 [(gogoproto.casttype) = "time.Duration"];
  // NoticeDisplaySeverity indicates the level of Severity to send notices for the given
  // session. This should ideally be of type pgnotice.DisplaySeverity, but cannot be done
  // due to a circular dependency.
  uint32 notice_display_severity = 6;
  // ReorderJoinsLimit indicates the number of joins at which the optimizer should
  // stop attempting to reorder.
  int64 reorder_joins_limit = 7;
  // DefaultTxnPriority indicates the default priority of newly created
  // transactions.
  // NOTE: we'd prefer to use tree.UserPriority here, but doing so would
  // introduce a package dependency cycle.
  int64 default_txn_priority = 8;
  // DefaultTxnReadOnly indicates the default read-only status of newly
  // created transactions.
  bool default_txn_read_only = 9;
  // DefaultTxnUseFollowerReads indicates whether transactions should be
  // created by default using an AS OF SYSTEM TIME clause far enough in the
  // past to facilitate reads against followers. If true, transactions will
  // also default to being read-only.
  bool default_txn_use_follower_reads = 10;
  // PartiallyDistributedPlansDisabled indicates whether the partially
  // distributed plans produced by distSQLSpecExecFactory are disabled. It
  // should be set to 'true' only in tests that verify that the old and the
  // new factories return exactly the same physical plans.
  // TODO(yuzefovich): remove it when deleting old sql.execFactory.
  bool partially_distributed_plans_disabled = 11;
  // OptimizerUseHistograms indicates whether we should use histograms for
  // cardinality estimation in the optimizer.
  bool optimizer_use_histograms = 12;
  // OptimizerUseMultiColStats indicates whether we should use multi-column
  // statistics for cardinality estimation in the optimizer.
  bool optimizer_use_multi_col_stats = 13;
  // LocalityOptimizedSearch indicates that the optimizer will try to plan scans
  // and lookup joins in which local nodes (i.e., nodes in the gateway region)
  // are searched for matching rows before remote nodes, in the hope that the
  // execution engine can avoid visiting remote nodes.
  bool locality_optimized_search = 14;
  // SafeUpdates causes errors when the client
  // sends syntax that may have unwanted side effects.
  bool safe_updates = 15;
  // PreferLookupJoinsForFKs causes foreign key operations to prefer lookup
  // joins.
  bool prefer_lookup_joins_for_fks = 16 [(gogoproto.customname) = "PreferLookupJoinsForFKs"];
  // ZigzagJoinEnabled indicates whether the optimizer should try and plan a
  // zigzag join.
  bool zigzag_join_enabled = 17;
  // RequireExplicitPrimaryKeys indicates whether CREATE TABLE statements should
  // error out if no primary key is provided.
  bool require_explicit_primary_keys = 18;
  // ForceSavepointRestart overrides the default SAVEPOINT behavior
  // for compatibility with certain ORMs. When this flag is set,
  // the savepoint name will no longer be compared against the magic
  // identifier `cockroach_restart` in order use a restartable
  // transaction.
  bool force_savepoint_restart = 19;
  // AllowPrepareAsOptPlan must be set to allow use of
  //   PREPARE name AS OPT PLAN '...'
  bool allow_prepare_as_opt_plan = 20;
  // TempTablesEnabled indicates whether temporary tables can be created or not.
  bool temp_tables_enabled = 21;
  // ImplicitPartitioningEnabled indicates whether implicit column partitioning
  // can be created.
  bool implicit_column_partitioning_enabled = 22;
  reserved 23;
  // OverrideMultiRegionZoneConfigEnabled indicates whether zone configurations can be
  // modified for multi-region databases and tables/indexes/partitions.
  bool override_multi_region_zone_config_enabled = 24;
  reserved 25;
  // DisallowFullTableScans indicates whether queries that plan full table scans
  // should be rejected.
  bool disallow_full_table_scans = 26;
  // ImplicitSelectForUpdate is true if FOR UPDATE locking may be used during
  // the row-fetch phase of mutation statements.
  bool implicit_select_for_update = 27;
  // InsertFastPath is true if the fast path for insert (with VALUES input) may
  // be used.
  bool insert_fast_path = 28;
  // AlterColumnTypeGeneralEnabled is true if ALTER TABLE ... ALTER COLUMN ...
  // TYPE x may be used for general conversions requiring online schema change/
  bool alter_column_type_general_enabled = 29;
  // SynchronousCommit is a dummy setting for the synchronous_commit var.
  bool synchronous_commit = 30;
  // EnableSeqScan is a dummy setting for the enable_seqscan var.
  bool enable_seq_scan = 31;
  reserved 32;
  // EnableUniqueWithoutIndexConstraints indicates whether creating unique
  // constraints without an index is allowed.
  // TODO(rytaft): remove this once unique without index constraints are fully
  // supported.
  bool enable_unique_without_index_constraints = 33;
  // StubCatalogTablesEnabled allows queries against virtual
  // tables that are not yet implemented.
  bool stub_catalog_tables_enabled = 34;
  // ExperimentalComputedColumnRewrites allows automatic rewriting of computed
  // column expressions in CREATE TABLE and ALTER TABLE statements. See the
  // experimentalComputedColumnRewrites cluster setting for a description of the
  // format.
  string experimental_computed_column_rewrites = 35;
  reserved 36;
  // EnableStreamReplication indicates whether to allow setting up a replication
  // stream.
  bool enable_stream_replication = 37;
  // ResultsBufferSize specifies the size at which the pgwire results buffer
  // will self-flush.
  int64 results_buffer_size = 38;
  // PropagateInputOrdering indicates that when planning a subquery or CTE, the
  // inner ordering should be propagated to the outer scope if the outer scope
  // is unordered. PropagateInputOrdering is currently experimental.
  bool propagate_input_ordering = 39;
  // ExperimentalDistSQLPlanningMode indicates whether the experimental
  // DistSQL planning driven by the optimizer is enabled.
  int64 experimental_distsql_planning_mode = 40 [
    (gogoproto.customname) = "ExperimentalDistSQLPlanningMode",
    (gogoproto.casttype) = "ExperimentalDistSQLPlanningMode"
  ];
  // DistSQLMode indicates whether to run queries using the distributed
  // execution engine.
  int64 dist_sql_mode = 41 [
    (gogoproto.customname) = "DistSQLMode",
    (gogoproto.casttype) = "DistSQLExecMode"
  ];
  // SerialNormalizationMode indicates how to handle the SERIAL pseudo-type.
  int64 serial_normalization_mode = 42 [(gogoproto.casttype) = "SerialNormalizationMode"];
  // NewSchemaChangerMode indicates whether to use the new schema changer.
  int64 new_schema_changer_mode = 43 [(gogoproto.casttype) = "NewSchemaChangerMode"];
  // SequenceCache stores sequence values which have been cached using the
  // CACHE sequence option.
  map<uint32, sessiondatapb.SequenceCacheEntry> sequence_cache = 44 [(gogoproto.casttype) = "SequenceCache"];
  // PlacementEnabled indicates whether PLACEMENT can be used or not.
  bool placement_enabled = 45;
  // SessionUserProto is the name of the user which has performed a SET ROLE
  // command. In other words, it is the name of the user which originally
  // established the connection before SET ROLE was first performed.
  // This is only populated when SET ROLE is used, otherwise the session_user
  // is the same as the UserProto in SessionData.
  // Postgres allows the SessionUser to be changed with SET SESSION AUTHORIZATION
  // but CockroachDB doesn't allow that at the time of this writing.
  string session_user_proto = 46 [(gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/security/username.SQLUsernameProto"];
  // TxnRowsWrittenLog is the threshold for the number of rows written by a SQL
  // transaction which - once exceeded - will trigger a logging event to SQL_PERF
  // (or SQL_INTERNAL_PERF for internal transactions); 0 means disabled.
  int64 txn_rows_written_log = 47;
  // TxnRowsWrittenErr is the limit for the number of rows written by a SQL
  // transaction which - once exceeded - will fail the transaction (or will
  // trigger a logging event to SQL_INTERNAL_PERF for internal transactions); 0
  // means disabled.
  int64 txn_rows_written_err = 48;
  // TxnRowsReadLog is the threshold for the number of rows read by a SQL
  // transaction which - once exceeded - will trigger a logging event to SQL_PERF
  // (or SQL_INTERNAL_PERF for internal transactions); 0 means disabled.
  int64 txn_rows_read_log = 49;
  // TxnRowsReadErr is the limit for the number of rows read by a SQL
  // transaction which - once exceeded - will fail the transaction (or will
  // trigger a logging event to SQL_INTERNAL_PERF for internal transactions); 0
  // means disabled.
  int64 txn_rows_read_err = 50;
  // AutoRehomingEnabled indicates whether or not REGIONAL BY ROW tables should
  // have a rehoming ON UPDATE clause added to them.
  bool auto_rehoming_enabled = 51;
  // IsSuperuser returns whether the user is a "superuser", which is defined
  // to be a user with an admin role.
  bool is_superuser = 52;
  // LargeFullScanRows is the estimated row count at which a full scan is
  // considered large, and worthy of logging and/or disabling depending on other
  // settings.
  double large_full_scan_rows = 53;
  // InjectRetryErrorsEnabled causes statements inside an explicit
  // transaction to return a transaction retry error. It is intended for
  // developers to test their app's retry logic.
  //
  // Note that this session variable is **not** propagated to the internal
  // executors - use InternalExecutorOverride for that.
  bool inject_retry_errors_enabled = 54;
  // NullOrderedLast controls whether NULL is ordered last. We default to
  // NULLS FIRST for ascending order by default, whereas postgres defaults
  // to NULLS LAST.
  bool null_ordered_last = 55;
  // DisablePlanGists indicates whether we should disable automatic gists.
  bool disable_plan_gists = 56;
  // CustomOptions contains a map of all custom session settings.
  // These session variables have at least one period in their name.
  map<string, string> custom_options = 57;
  // IndexRecommendationsEnabled controls whether or not we display index
  // recommendations below the plan in EXPLAIN.
  bool index_recommendations_enabled = 58;
  // AvoidBuffering indicates that the returned data should not be
  // buffered by conn executor.  This is currently used by replication primitives
  // to ensure the data is flushed to the consumer immediately.
  //
  // Does not apply to the InternalExecutor.
  bool avoid_buffering = 59;
  // CheckFunctionBodies indicates whether functions are validated during
  // creation.
  bool check_function_bodies = 60;
  // CostScansWithDefaultColSize is true when the optimizer should cost scans
  // and joins using the same default number of bytes per column instead of
  // column sizes from the AvgSize table statistic.
  bool cost_scans_with_default_col_size = 61;
  // DefaultTxnQualityOfService indicates the default QoSLevel/WorkPriority of
  // newly created transactions.
  int32 default_txn_quality_of_service = 62 [(gogoproto.casttype)="QoSLevel"];
  // OptSplitScanLimit indicates the maximum number of UNION ALL statements a
  // Scan may be split into during query optimization to avoid a sort.
  int32 opt_split_scan_limit = 63;
  // EnableSuperRegions is true when super region functionality is enabled.
  bool enable_super_regions = 64;
  // OverrideAlterPrimaryRegionInSuperRegion is true when the user is allowed
  // to modify a primary region that is part of a super region.
  bool override_alter_primary_region_in_super_region = 65;
  // EnableImplicitTransactionForBatchStatements configures the handling of
  // multiple statements in a single query. If enabled, then an implicit
  // transaction is used when multiple statements are sent in a single query.
  // Setting this to false is a divergence from the pgwire protocol, but
  // matches the behavior of CockroachDB v21.2 and earlier.
  bool enable_implicit_transaction_for_batch_statements = 66;
  // ExpectAndIgnoreNotVisibleColumnsInCopy changes behaviour for COPY t FROM ...
  // (with no column name specifiers) to expect and ignore not visible column
  // fields.
  bool expect_and_ignore_not_visible_columns_in_copy = 67;
  // MultipleModificationsOfTable allows statements containing multiple INSERT
  // ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table,
  // at the risk of data corruption if the same row is modified multiple times.
  bool multiple_modifications_of_table = 68;
  // ShowPrimaryKeyConstraintOnNotVisibleColumns controls whether SHOW
  // CONSTRAINTS and pg_catalog.pg_constraint will include primary key
  // constraints that only include hidden columns.
  bool show_primary_key_constraint_on_not_visible_columns = 69;
  // TestingOptimizerRandomSeed is non-zero when we are testing the optimizer by
  // randomly perturbing costs or disabling rules. This will initialize a rng
  // seeded to the given integer. This should only be used in test scenarios and
  // is very much a non-production setting.
  int64 testing_optimizer_random_seed = 70;
  // UnconstrainedNonCoveringIndexScanEnabled controls whether unconstrained
  // non-covering index scan access paths are explored by the optimizer.
  bool unconstrained_non_covering_index_scan_enabled = 71;
  // TestingOptimizerCostPerturbation is non-zero when the coster should
  // randomly perturb costs to produce a non-optimal query plan. This should
  // only be used in test scenarios and is very much a non-production setting.
  double testing_optimizer_cost_perturbation = 72;
  // TestingOptimizerDisableRuleProbability is non-zero when the optimizer
  // should randomly disable every non-essential transformation rule with the
  // given probability. This should only be used in test scenarios and is very
  // much a non-production setting.
  double testing_optimizer_disable_rule_probability = 73;
  // OptimizerUseNotVisibleIndexes indicates whether the optimizer can still
  // choose to use visible indexes for query plans.
  bool optimizer_use_not_visible_indexes = 74;
  // CopyFastPathEnabled controls whether the optimized copy mode is enabled.
  bool copy_fast_path_enabled = 75;
  // disable_hoist_projection_in_join_limitation disables the restrictions
  // placed on projection hoisting during query planning in the optimizer.
  bool disable_hoist_projection_in_join_limitation = 76;
  // CopyFromAtomicEnabled controls whether implicit txn copy from operations
  // are atomic or segmented.
  bool copy_from_atomic_enabled = 77;
  // EnforceHomeRegion, when true, causes queries which scan rows from multiple
  // regions, or which scan rows from a single home region, but initiated from
  // a gateway region which differs from that home region, to error out.
  bool enforce_home_region = 78;
  // OptimizerUseForecasts indicates whether we should use statistics forecasts
  // for cardinality estimation in the optimizer.
  bool optimizer_use_forecasts = 79;
  // VariableInequalityLookupJoinEnabled indicates whether the optimizer should
  // be allowed to consider lookup joins with inequality conditions, in
  // addition to the other restrictions on when they are planned.
  bool variable_inequality_lookup_join_enabled = 80;
  // TransactionSessionTimeout is the duration a transaction is permitted to
  // run before the transaction is canceled. If set to 0, there is no timeout.
  int64 transaction_timeout = 81 [(gogoproto.casttype) = "time.Duration"];
  // SystemIdentityProto is the original name of the client presented to pgwire
  // before it was mapped to a SQL identifier.
  string system_identity_proto = 82 [(gogoproto.casttype) = "github.com/cockroachdb/cockroach/pkg/security/username.SQLUsernameProto"];
  // DescriptorValidationMode indicates whether to validate the descriptors at
  // read and write time, at read time only, or never.
  int64 descriptor_validation_mode = 83 [(gogoproto.casttype) = "DescriptorValidationMode"];
  // ExperimentalHashGroupJoinEnabled indicates whether the physical planner
  // will attempt to convert a hash join followed by a hash aggregator into a
  // single hash group-join operation. At the moment, there is no optimizer
  // support for this, so some things can be incorrect (e.g. EXPLAIN plans).
  bool experimental_hash_group_join_enabled = 84;
  // AllowOrdinalColumnReferences indicates whether the deprecated ordinal
  // column reference syntax (e.g., `SELECT @1 FROM t`) is allowed.
  bool allow_ordinal_column_references = 85;
  // OptimizerUseImprovedDisjunctionStats, when true, indicates that the
  // optimizer should use improved statistics calculations for disjunctive
  // filters.
  bool optimizer_use_improved_disjunction_stats = 86;
  // OptimizerUseLimitOrderingForStreamingGroupBy enables the exploration rule
  // which optimizes 'SELECT ... GROUP BY ... ORDER BY ... LIMIT n' queries.
  // The rule uses the required ordering in the limit expression to inform an
  // interesting ordering to require from the input to the group-by expression.
  // This can potentially eliminate a top-k operation.
  bool optimizer_use_limit_ordering_for_streaming_group_by = 88;
  // CopyFromRetriesEnabled controls whether retries should be internally
  // attempted for retriable errors.
  bool copy_from_retries_enabled = 89;
  // DeclareCursorStatementTimeoutEnabled controls whether statement timeouts
  // apply during DECLARE CURSOR.
  bool declare_cursor_statement_timeout_enabled = 90;
  // OptimizerUseImprovedSplitDisjunctionForJoins enables the optimizer to split
  // disjunctions (OR expressions) in more cases in join conditions by building a
  // UNION of two join expressions. If this setting is true, all disjunctions in
  // inner, semi, and anti joins will be split. If false, only disjunctions
  // potentially containing an equijoin condition will be split.
  bool optimizer_use_improved_split_disjunction_for_joins = 91;
  // InjectRetryErrorsOnCommitEnabled causes statements inside an explicit
  // transaction to return a transaction retry error just before transcation commit.
  // It is intended for developers to test their app's retry logic.
  bool inject_retry_errors_on_commit_enabled = 92;
  // EnforceHomeRegionFollowerReadsEnabled, when true, allows the use of
  // follower reads to dynamically detect and report a query's home region
  // when the enforce_home_region session setting is also true.
  bool enforce_home_region_follower_reads_enabled = 93;
  // OptimizerAlwaysUseHistograms, when true, ensures that the optimizer
  // always uses histograms to calculate statistics if available.
  bool optimizer_always_use_histograms = 94;
  // EnableCreateStatsUsingExtremes, when true, allows the use of CREATE
  // STATISTICS .. USING EXTREMES.
  bool enable_create_stats_using_extremes = 95;
  // AllowRoleMembershipsToChangeDuringTransaction, when true, means that
  // operations which consult the role membership cache do not retain their
  // lease on that version of the cache throughout the transaction. The
  // consequence of this is that the transaction may not experience a singular
  // view of role membership, and it may be able to commit after the revocation
  // of a role membership which the transaction relied on has successfully been
  // committed and acknowledged to the user.
  bool allow_role_memberships_to_change_during_transaction = 96;
  // PreparedStatementsCacheSize, when not equal to 0, causes the LRU prepared
  // statements in a session to be automatically deallocated when total prepared
  // statement memory usage for that session is more than the cache size.
  // Execution of these deallocated prepared statements will fail until they are
  // prepared again.
  int64 prepared_statements_cache_size = 97;
  // StreamerEnabled controls whether the Streamer API can be used.
  bool streamer_enabled = 98;
  // DisableDropVirtualCluster causes errors when the client
  // attempts to drop virtual clusters or tenant records.
  bool disable_drop_virtual_cluster = 99;
  // MultipleActivePortalEnabled determines if the pgwire portal execution
  // for certain queries can be paused. If true, portals with read-only SELECT
  // query without sub/post queries can be executed in interleaving manner, but
  // with a local execution plan.
  bool multiple_active_portals_enabled = 100;
  // UnboundedParallelScans, when true, indicates that the TableReader DistSQL
  // processors should parallelize scans across ranges. Note that the
  // parallelization will still be disabled for queries with LIMITs, and it can
  // lead to increased likelihood of OOMs.
  bool unbounded_parallel_scans = 101;
  // OptimizerHoistUncorrelatedEqualitySubqueries, when true, causes the
  // optimizer to hoist uncorrelated subqueries that are part of an equality
  // expression with a column reference, which can produce more efficient query
  // plans.
  bool optimizer_hoist_uncorrelated_equality_subqueries = 102;
  // TestingOptimizerInjectPanics indicates whether random panics are injected
  // during optimization. The goal of this setting is to flush out cases where
  // panics used for error-propagation are uncaught.
  bool testing_optimizer_inject_panics = 103;
  // OptimizerUseImprovedComputedColumnFiltersDerivation, when true, causes the
  // optimizer to derive filters on computed columns in more cases. Previously,
  // filters could only be derived when the expression defining the computed
  // column involved a single column and that column was equated with a single
  // constant value in a WHERE clause filter.
  bool optimizer_use_improved_computed_column_filters_derivation = 104;
  // DefaultTxnIsolationLevel indicates the default isolation level of newly
  // created transactions.
  // NOTE: we'd prefer to use tree.IsolationLevel here, but doing so would
  // introduce a package dependency cycle.
  int64 default_txn_isolation_level = 105;
  // ReplicationMode represents the replication parameter passed in during
  // connection time.
  ReplicationMode replication_mode = 106;
  // ImplicitFKLocking is true if FOR SHARE locking may be used while checking
  // the referenced table during an insert or update to a table with a foreign
  // key.
  bool implicit_fk_locking = 107 [(gogoproto.customname) = "ImplicitFKLocking"];

  ///////////////////////////////////////////////////////////////////////////
  // WARNING: consider whether a session parameter you're adding needs to  //
  // be propagated to the remote nodes. If so, that parameter should live  //
  // in the SessionData message instead.                                   //
  ///////////////////////////////////////////////////////////////////////////
}

// ReplicationMode represents the replication={0,1,on,off,database} connection
// parameter in PostgreSQL.
enum ReplicationMode {
  REPLICATION_MODE_DISABLED = 0;
  REPLICATION_MODE_ENABLED = 1;
  REPLICATION_MODE_DATABASE = 2;
}

// SequenceCacheEntry is an entry in a SequenceCache.
message SequenceCacheEntry {
  // CachedVersion stores the descpb.DescriptorVersion that cached values are associated with.
  // The version is checked to determine if cache needs to be invalidated. The version is stored as
  // a uint32 to prevent an import cycle with the descpb package.
  uint32 cached_version = 1;
  // CurrentValue stores the present value of the sequence to be given out.
  int64 current_value = 2;
  // Increment stores the amount to Increment the currentVal by each time the
  // currentVal is used. This value corresponds to descpb.TableDescriptor_SequenceOpts.Increment.
  int64 increment = 3;
  // NumValues represents the number of values to cache. The cache is considered
  // to be empty when NumValues is 0.
  int64 num_values = 4;
}