mz_sql::session

Module vars

Source
Expand description

Run-time configuration parameters

§Overview

Materialize roughly follows the PostgreSQL configuration model, which works as follows. There is a global set of named configuration parameters, like DateStyle and client_encoding. These parameters can be set in several places: in an on-disk configuration file (in Postgres, named postgresql.conf), in command line arguments when the server is started, or at runtime via the ALTER SYSTEM or SET statements. Parameters that are set in a session take precedence over database defaults, which in turn take precedence over command line arguments, which in turn take precedence over settings in the on-disk configuration. Note that changing the value of parameters obeys transaction semantics: if a transaction fails to commit, any parameters that were changed in that transaction (i.e., via SET) will be rolled back to their previous value.

The Materialize configuration hierarchy at the moment is much simpler. Global defaults are hardcoded into the binary, and a select few parameters can be overridden per session. A select few parameters can be overridden on disk.

The set of variables that can be overridden per session and the set of variables that can be overridden on disk are currently disjoint. The infrastructure has been designed with an eye towards merging these two sets and supporting additional layers to the hierarchy, however, should the need arise.

The configuration parameters that exist are driven by compatibility with PostgreSQL drivers that expect them, not because they are particularly important.

§Structure

Thw most meaningful exports from this module are:

  • SessionVars represent per-session parameters, which each user can access independently of one another, and are accessed via SET.

    The fields of SessionVars are either;

    • SessionVar, which is preferable and simply requires full support of the SessionVar impl for its embedded value type.
    • ServerVar for types that do not currently support everything required by SessionVar, e.g. they are fixed-value parameters.

    In the fullness of time, all fields in SessionVars should be SessionVar.

  • SystemVars represent system-wide configuration settings and are accessed via ALTER SYSTEM SET.

    All elements of SystemVars are SystemVar.

Some VarDefinition are also marked as a FeatureFlag; this is just a wrapper to make working with a set of VarDefinition easier, primarily from within SQL planning, where we might want to check if a feature is enabled before planning it.

Modules§

cluster_scheduling
Configuration for how cluster replicas are scheduled.
constraints 🔒
Defines constraints that can be imposed on variables.
definitions 🔒
errors 🔒
grpc_client
Configuration for gRPC client connections.
polyfill 🔒
The types in this module exist to overcome limitations of the Rust compiler, namely limitations in const generics.
upsert_rocksdb
Tuning for RocksDB used by UPSERT sources that takes effect on restart.
value 🔒

Structs§

DateStyle
This style should actually be some more complex struct, but we only support this configuration of it, so this is fine for the time being.
Failpoints
FeatureFlag
flag.
MzVersion
SessionVar
A SessionVar is the session value for a configuration parameter. If unset, the server default is used instead.
SessionVars
Session variables.
SystemVar
A SystemVar is persisted on disk value for a configuration parameter. If unset, the server default is used instead.
SystemVars
On disk variables.
VarDefinition
Definition of a variable.

Enums§

ClientEncoding
ClientSeverity
Severity levels can used to be used to filter which messages get sent to a client.
EndTransactionAction
The action to take during end_transaction.
IntervalStyle
IsolationLevel
List of valid isolation levels.
NetworkPolicyError
OwnedVarInput
An owned version of VarInput.
TimeZone
List of valid time zones.
VarDefaultValue
The kinds of compiled in default values that can be used with VarDefinition.
VarError
Errors that can occur when working with Vars
VarInput
Represents the input to a variable.
VarParseError
Errors that can occur when parsing VarInput.

Constants§

DEFAULT_DATABASE_NAME
The name of the default database that Materialize uses.
IS_SUPERUSER_NAME
MZ_VERSION_NAME
OLD_AUTO_ROUTE_CATALOG_QUERIES
OLD_CATALOG_SERVER_CLUSTER
SCHEMA_ALIAS
SERVER_MAJOR_VERSION
The major version of PostgreSQL that Materialize claims to be.
SERVER_MINOR_VERSION
The minor version of PostgreSQL that Materialize claims to be.
SERVER_PATCH_VERSION
The patch version of PostgreSQL that Materialize claims to be.
TRANSACTION_ISOLATION_VAR_NAME

Statics§

ALLOWED_CLUSTER_REPLICA_SIZES
ALLOW_REAL_TIME_RECENCY
APPLICATION_NAME
ARRANGEMENT_EXERT_PROPORTIONALITY
AUTO_ROUTE_CATALOG_QUERIES
CLIENT_ENCODING
CLIENT_MIN_MESSAGES
CLUSTER
CLUSTER_REPLICA
COORD_SLOW_MESSAGE_WARN_THRESHOLD
CURRENT_OBJECT_MISSING_WARNINGS
DATABASE
DATE_STYLE
DEFAULT_CLUSTER_REPLICATION_FACTOR
DEFAULT_DATE_STYLE
DISK_CLUSTER_REPLICAS_DEFAULT
The default for the DISK option when creating managed clusters and cluster replicas.
EMIT_INTROSPECTION_QUERY_NOTICE
EMIT_PLAN_INSIGHTS_NOTICE
EMIT_TIMESTAMP_NOTICE
EMIT_TRACE_ID_NOTICE
ENABLE_ALTER_SET_CLUSTER
ENABLE_ALTER_SWAP
ENABLE_ALTER_TABLE_ADD_COLUMN
ENABLE_AWS_MSK_IAM_AUTH
ENABLE_BINARY_DATE_BIN
ENABLE_CARDINALITY_ESTIMATES
ENABLE_CLOCK_LOAD_GENERATOR
ENABLE_CLUSTER_SCHEDULE_REFRESH
ENABLE_COLLECTION_PARTITION_BY
ENABLE_CONNECTION_VALIDATION_SYNTAX
ENABLE_CONSOLIDATE_AFTER_UNION_NEGATE
ENABLE_CONTINUAL_TASK_CREATE
ENABLE_CONTINUAL_TASK_RETAIN
ENABLE_CONTINUAL_TASK_TRANSFORM
ENABLE_COPY_FROM_REMOTE
ENABLE_COPY_TO_EXPR
ENABLE_CREATE_TABLE_FROM_SOURCE
ENABLE_DATE_BIN_HOPPING
ENABLE_DEFAULT_CONNECTION_VALIDATION
ENABLE_DEQUADRATIC_EQPROP_MAP
ENABLE_DISK_CLUSTER_REPLICAS
ENABLE_EAGER_DELTA_JOINS
ENABLE_ENVELOPE_DEBEZIUM_IN_SUBSCRIBE
ENABLE_ENVELOPE_MATERIALIZE
ENABLE_ENVELOPE_UPSERT_INLINE_ERRORS
ENABLE_EXPLAIN_PUSHDOWN
ENABLE_EXPRESSIONS_IN_LIMIT_SYNTAX
ENABLE_INDEX_OPTIONS
ENABLE_INTERNAL_STATEMENT_LOGGING
ENABLE_JOIN_PRIORITIZE_ARRANGED
ENABLE_KAFKA_SINK_HEADERS
ENABLE_LAUNCHDARKLY
Boolean flag indicating whether to enable syncing from LaunchDarkly. Can be turned off as an emergency measure to still be able to alter parameters while LD is broken.
ENABLE_LESS_REDUCE_IN_EQPROP
ENABLE_LETREC_FIXPOINT_ANALYSIS
ENABLE_LIST_LENGTH_MAX
ENABLE_LIST_N_LAYERS
ENABLE_LIST_REMOVE
ENABLE_LOAD_GENERATOR_KEY_VALUE
ENABLE_LOGICAL_COMPACTION_WINDOW
ENABLE_MANAGED_CLUSTER_AVAILABILITY_ZONES
ENABLE_MULTI_WORKER_STORAGE_PERSIST_SINK
ENABLE_MZ_NOTICES
ENABLE_NETWORK_POLICIES
ENABLE_NEW_OUTER_JOIN_LOWERING
ENABLE_NOTICES_FOR_INDEX_ALREADY_EXISTS
ENABLE_NOTICES_FOR_INDEX_EMPTY_KEY
ENABLE_NOTICES_FOR_INDEX_TOO_WIDE_FOR_LITERAL_CONSTRAINTS
ENABLE_OFF_THREAD_OPTIMIZATION
ENABLE_PERSIST_STREAMING_COMPACTION
ENABLE_PERSIST_STREAMING_SNAPSHOT_AND_FETCH
ENABLE_PRIMARY_KEY_NOT_ENFORCED
ENABLE_PROJECTION_PUSHDOWN_AFTER_RELATION_CSE
ENABLE_RAISE_STATEMENT
ENABLE_RBAC_CHECKS
ENABLE_REDACTED_TEST_OPTION
ENABLE_REDUCE_MFP_FUSION
ENABLE_REDUCE_REDUCTION
ENABLE_REFRESH_EVERY_MVS
ENABLE_REPEAT_ROW
ENABLE_SESSION_CARDINALITY_ESTIMATES
ENABLE_SESSION_RBAC_CHECKS
ENABLE_SESSION_TIMELINES
ENABLE_SQL_SERVER_SOURCE
ENABLE_STORAGE_SHARD_FINALIZATION
ENABLE_TIME_AT_TIME_ZONE
ENABLE_UNLIMITED_RETAIN_HISTORY
ENABLE_VARIADIC_LEFT_JOIN_LOWERING
ENABLE_WITHIN_TIMESTAMP_ORDER_BY_IN_SUBSCRIBE
ENABLE_WORKER_CORE_AFFINITY
ENABLE_YUGABYTE_CONNECTION
ENABLE_ZERO_DOWNTIME_CLUSTER_RECONFIGURATION
EXTRA_FLOAT_DIGITS
FAILPOINTS
FEATURE_FLAGS
FORCE_SOURCE_TABLE_SYNTAX
IDLE_IN_TRANSACTION_SESSION_TIMEOUT
INTEGER_DATETIMES
INTERVAL_STYLE
KAFKA_FETCH_METADATA_TIMEOUT
Controls the timeout when fetching kafka metadata. Defaults to 10s.
KAFKA_PROGRESS_RECORD_FETCH_TIMEOUT
Controls the timeout when fetching kafka progress records. Defaults to 60s.
KAFKA_SOCKET_CONNECTION_SETUP_TIMEOUT
Controls socket.connection.setup.timeout.ms for rdkafka client connections. Defaults to the rdkafka default (30000ms). Cannot be greater than i32::MAX or less than 1000ms
KAFKA_SOCKET_KEEPALIVE
Enables socket.keepalive.enable for rdkafka client connections. Defaults to true.
KAFKA_SOCKET_TIMEOUT
Controls socket.timeout.ms for rdkafka client connections. Defaults to the rdkafka default (60000ms). Cannot be greater than 300000ms, more than 100ms greater than kafka_transaction_timeout, or less than 10ms.
KAFKA_TRANSACTION_TIMEOUT
Controls transaction.timeout.ms for rdkafka client connections. Defaults to the rdkafka default (60000ms). Cannot be greater than i32::MAX or less than 1000ms.
KEEP_N_PRIVATELINK_STATUS_HISTORY_ENTRIES
Controls mz_storage_types::parameters::StorageParameters::keep_n_privatelink_status_history_entries.
KEEP_N_SINK_STATUS_HISTORY_ENTRIES
Controls mz_storage_types::parameters::StorageParameters::keep_n_sink_status_history_entries.
KEEP_N_SOURCE_STATUS_HISTORY_ENTRIES
Controls mz_storage_types::parameters::StorageParameters::keep_n_source_status_history_entries.
LOGGING_FILTER
LOGGING_FILTER_DEFAULTS
MAX_AWS_PRIVATELINK_CONNECTIONS
MAX_CLUSTERS
MAX_CONNECTIONS
MAX_CONTINUAL_TASKS
MAX_COPY_FROM_SIZE
MAX_CREDIT_CONSUMPTION_RATE
MAX_DATABASES
MAX_IDENTIFIER_LENGTH
MAX_KAFKA_CONNECTIONS
MAX_MATERIALIZED_VIEWS
MAX_MYSQL_CONNECTIONS
MAX_NETWORK_POLICIES
MAX_OBJECTS_PER_SCHEMA
MAX_POSTGRES_CONNECTIONS
MAX_QUERY_RESULT_SIZE
MAX_REPLICAS_PER_CLUSTER
MAX_RESULT_SIZE
MAX_ROLES
MAX_RULES_PER_NETWORK_POLICY
MAX_SCHEMAS_PER_DATABASE
MAX_SECRETS
MAX_SINKS
MAX_SOURCES
MAX_SQL_SERVER_CONNECTIONS
MAX_TABLES
MAX_TIMESTAMP_INTERVAL
METRICS_RETENTION
The logical compaction window for builtin tables and sources that have the retained_metrics_relation flag set.
MIN_TIMESTAMP_INTERVAL
MYSQL_SOURCE_CONNECT_TIMEOUT
Sets the timeout for establishing an authenticated connection to MySQL
MYSQL_SOURCE_SNAPSHOT_LOCK_WAIT_TIMEOUT
Sets the lock_wait_timeout value to use during the snapshotting phase of MySQL sources.
MYSQL_SOURCE_SNAPSHOT_MAX_EXECUTION_TIME
Sets the max_execution_time value to use during the snapshotting phase of MySQL sources.
MYSQL_SOURCE_TCP_KEEPALIVE
Sets the time between TCP keepalive probes when connecting to MySQL via mz_mysql_util.
NETWORK_POLICY
OPENTELEMETRY_FILTER
OPENTELEMETRY_FILTER_DEFAULTS
OPTIMIZER_E2E_LATENCY_WARNING_THRESHOLD
OPTIMIZER_ONESHOT_STATS_TIMEOUT
OPTIMIZER_STATS_TIMEOUT
PERSIST_FAST_PATH_LIMIT
PG_SOURCE_CONNECT_TIMEOUT
Controls the connect_timeout setting when connecting to PG via mz_postgres_util.
PG_SOURCE_SNAPSHOT_COLLECT_STRICT_COUNT
Please see PgSourceSnapshotConfig.
PG_SOURCE_SNAPSHOT_FALLBACK_TO_STRICT_COUNT
Please see PgSourceSnapshotConfig.
PG_SOURCE_SNAPSHOT_STATEMENT_TIMEOUT
Sets the statement_timeout value to use during the snapshotting phase of PG sources.
PG_SOURCE_SNAPSHOT_WAIT_FOR_COUNT
Please see PgSourceSnapshotConfig.
PG_SOURCE_TCP_CONFIGURE_SERVER
Sets whether to apply the TCP configuration parameters on the server when connecting to PG via mz_postgres_util.
PG_SOURCE_TCP_KEEPALIVES_IDLE
Sets the amount of idle time before a keepalive packet is sent on the connection when connecting to PG via mz_postgres_util.
PG_SOURCE_TCP_KEEPALIVES_INTERVAL
Sets the time interval between TCP keepalive probes when connecting to PG via mz_postgres_util.
PG_SOURCE_TCP_KEEPALIVES_RETRIES
Sets the maximum number of TCP keepalive probes that will be sent before dropping a connection when connecting to PG via mz_postgres_util.
PG_SOURCE_TCP_USER_TIMEOUT
Sets the TCP user timeout when connecting to PG via mz_postgres_util.
PG_SOURCE_WAL_SENDER_TIMEOUT
Sets the wal_sender_timeout value to use during the replication phase of PG sources.
PG_TIMESTAMP_ORACLE_CONNECTION_POOL_MAX_SIZE
Controls mz_adapter::coord::timestamp_oracle::postgres_oracle::DynamicConfig::pg_connection_pool_max_size.
PG_TIMESTAMP_ORACLE_CONNECTION_POOL_MAX_WAIT
Controls mz_adapter::coord::timestamp_oracle::postgres_oracle::DynamicConfig::pg_connection_pool_max_wait.
PG_TIMESTAMP_ORACLE_CONNECTION_POOL_TTL
Controls mz_adapter::coord::timestamp_oracle::postgres_oracle::DynamicConfig::pg_connection_pool_ttl.
PG_TIMESTAMP_ORACLE_CONNECTION_POOL_TTL_STAGGER
Controls mz_adapter::coord::timestamp_oracle::postgres_oracle::DynamicConfig::pg_connection_pool_ttl_stagger.
PRIVATELINK_STATUS_UPDATE_QUOTA_PER_MINUTE
REAL_TIME_RECENCY
Feature flag indicating whether real time recency is enabled. Not that unlike other feature flags, this is made available at the session level, so is additionally gated by a feature flag.
REAL_TIME_RECENCY_TIMEOUT
REPLICA_STATUS_HISTORY_RETENTION_WINDOW
Controls mz_storage_types::parameters::StorageParameters::replica_status_history_retention_window.
SEARCH_PATH
SENTRY_FILTERS
SERVER_VERSION
SERVER_VERSION_NUM
SESSION_SYSTEM_VARS 🔒
Set of SystemVars that can also get set at a per-Session level.
SQL_SAFE_UPDATES
SSH_CHECK_INTERVAL
Controls the check interval for connections to SSH bastions via mz_ssh_util.
SSH_CONNECT_TIMEOUT
Controls the connect timeout for connections to SSH bastions via mz_ssh_util.
SSH_KEEPALIVES_IDLE
Controls the keepalive idle interval for connections to SSH bastions via mz_ssh_util.
STANDARD_CONFORMING_STRINGS
STATEMENT_LOGGING_DEFAULT_SAMPLE_RATE
STATEMENT_LOGGING_MAX_DATA_CREDIT
STATEMENT_LOGGING_MAX_SAMPLE_RATE
STATEMENT_LOGGING_SAMPLE_RATE
STATEMENT_LOGGING_TARGET_DATA_RATE
STATEMENT_LOGGING_USE_REPRODUCIBLE_RNG
STATEMENT_TIMEOUT
STORAGE_DATAFLOW_MAX_INFLIGHT_BYTES
The maximum number of in-flight bytes emitted by persist_sources feeding storage dataflows. Currently defaults to 256MiB = 268435456 bytes Note: Backpressure will only be turned on if disk is enabled based on storage_dataflow_max_inflight_bytes_disk_only flag
STORAGE_DATAFLOW_MAX_INFLIGHT_BYTES_DISK_ONLY
STORAGE_DATAFLOW_MAX_INFLIGHT_BYTES_TO_CLUSTER_SIZE_FRACTION
The fraction of the cluster replica size to be used as the maximum number of in-flight bytes emitted by persist_sources feeding storage dataflows. If not configured, the storage_dataflow_max_inflight_bytes value will be used. For this value to be used storage_dataflow_max_inflight_bytes needs to be set.
STORAGE_RECORD_SOURCE_SINK_NAMESPACED_ERRORS
STORAGE_SHRINK_UPSERT_UNUSED_BUFFERS_BY_RATIO
Configuration ratio to shrink unusef buffers in upsert by. For eg: is 2 is set, then the buffers will be reduced by 2 i.e. halved. Default is 0, which means shrinking is disabled.
STORAGE_STATISTICS_COLLECTION_INTERVAL
The interval to collect statistics for mz_source_statistics_per_worker and mz_sink_statistics_per_worker in clusterd. Controls the accuracy of metrics.
STORAGE_STATISTICS_INTERVAL
The interval to submit statistics to mz_source_statistics_per_worker and mz_sink_statistics_per_worker.
SUPERUSER_RESERVED_CONNECTIONS
TIMEZONE
TRANSACTION_ISOLATION
UNSAFE_ENABLE_TABLE_CHECK_CONSTRAINT
UNSAFE_ENABLE_TABLE_FOREIGN_KEY
UNSAFE_ENABLE_TABLE_KEYS
UNSAFE_ENABLE_UNORCHESTRATED_CLUSTER_REPLICAS
UNSAFE_ENABLE_UNSAFE_FUNCTIONS
UNSAFE_ENABLE_UNSTABLE_DEPENDENCIES
UNSAFE_MOCK_AUDIT_EVENT_TIMESTAMP
UNSAFE_NEW_TRANSACTION_WALL_TIME
USER_STORAGE_MANAGED_COLLECTIONS_BATCH_DURATION
WEBHOOKS_SECRETS_CACHING_TTL_SECS
WEBHOOK_CONCURRENT_REQUEST_LIMIT
WELCOME_MESSAGE

Traits§

AsAny
Helper trait to cast a &dyn T to a &dyn Any.
Value
Defines a value that get stored as part of a System or Session variable.
Var
A Var represents a configuration parameter of an arbitrary type.

Functions§

compat_translate 🔒
If the given variable name and/or input is deprecated, return a corresponding updated value, otherwise return the original.
compat_translate_name 🔒
is_cluster_scheduling_var
Returns whether the named variable is a cluster scheduling config
is_http_config_var
Returns whether the named variable is an HTTP server related config var.
is_pg_timestamp_oracle_config_var
Returns whether the named variable is a Postgres/CRDB timestamp oracle configuration parameter.
is_secrets_caching_var
Returns whether the named variable is a caching configuration parameter.
is_tracing_var
is_upsert_rocksdb_config_var 🔒