Skip to main content

uqa_engine/session/
parameters.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Assigning configuration parameters: `SET`, `RESET`, `RESET ALL`, `set_config` and the settings a client gives at startup, with `PostgreSQL`'s contexts, value checks and custom placeholders, and the libraries that define their parameters as a session loads them.
8
9use uqa_sql::catalog::access_methods::{access_method_kind, AccessMethodKind};
10use uqa_sql::semantics::parameters::custom::{
11    check_assignable_custom_name, reserved_placeholder_warning,
12};
13use uqa_sql::semantics::parameters::definition::{
14    ParameterContext, ParameterDefinition, ParameterFlags,
15};
16use uqa_sql::semantics::parameters::identifier_list::split_identifier_list;
17use uqa_sql::semantics::parameters::value::{
18    invalid_value_message, name_truncation_notice, parse_setting_with_context,
19};
20use uqa_sql::SQLNotice;
21
22use super::{default_search_path, Engine, SQLError};
23use crate::capabilities::session_parameters::{setting_key, SessionParameter};
24
25/// The tablespaces of the database: its default one and the one for shared relations.
26const TABLESPACES: [&str; 2] = ["pg_default", "pg_global"];
27
28fn invalid_value(definition: &ParameterDefinition, value: &str, detail: String) -> SQLError {
29    SQLError::Diagnostic {
30        sqlstate: "22023".into(),
31        message: invalid_value_message(definition, value),
32        detail: Some(detail),
33        hint: None,
34    }
35}
36
37/// Whether `definition` is a characteristic of the current transaction, which the transaction rather than the session keeps.
38fn is_transaction_characteristic(definition: &ParameterDefinition) -> bool {
39    matches!(
40        definition.name,
41        "transaction_isolation" | "transaction_read_only" | "transaction_deferrable"
42    )
43}
44
45/// `pg_clean_ascii`: every byte outside printable ASCII written as `\xNN`, as `application_name` keeps it.
46fn clean_ascii(value: &str) -> String {
47    use std::fmt::Write;
48    let mut cleaned = String::with_capacity(value.len());
49    for byte in value.bytes() {
50        if (32..127).contains(&byte) {
51            cleaned.push(char::from(byte));
52        } else {
53            write!(cleaned, "\\x{byte:02x}").expect("writing into a String cannot fail");
54        }
55    }
56    cleaned
57}
58
59impl Engine {
60    pub(crate) fn parser_settings(&self) -> uqa_sql::parser::ParserSettings {
61        let parameters = self.session.parameters.lock();
62        let state = self.session.state.read();
63        uqa_sql::parser::ParserSettings::from_settings(|name| {
64            state
65                .session_vars
66                .get(name)
67                .map(String::as_str)
68                .or_else(|| parameters.client_setting(name))
69        })
70    }
71
72    /// Assign `value` to `name` for the session, as `SET name TO value` does before the assignment's lifetime applies: a defined parameter checks its context and value, and any other valid custom name becomes a placeholder.
73    pub(super) fn assign_parameter(&self, name: &str, value: &str) -> Result<(), SQLError> {
74        match self.session_execution_view().resolve_parameter(name) {
75            Some(SessionParameter::Defined(definition)) => {
76                self.check_parameter_change(definition)?;
77                if is_transaction_characteristic(definition) {
78                    return self.set_transaction_parameter(definition.name, value);
79                }
80                let setting = self.checked_setting(definition, value)?;
81                self.store_setting(definition, Some(setting));
82                Ok(())
83            }
84            Some(SessionParameter::Placeholder(placeholder)) => {
85                self.store_placeholder(&placeholder, Some(value.to_string()));
86                Ok(())
87            }
88            None => {
89                self.create_placeholder(name)?;
90                self.store_placeholder(name, Some(value.to_string()));
91                Ok(())
92            }
93        }
94    }
95
96    /// Restore the setting `RESET name` restores; a valid custom name nothing defines becomes an empty placeholder.
97    pub(super) fn reset_parameter(&self, name: &str) -> Result<(), SQLError> {
98        match self.session_execution_view().resolve_parameter(name) {
99            Some(SessionParameter::Defined(definition)) => {
100                if definition.has_flag(ParameterFlags::NO_RESET) {
101                    return Err(SQLError::Routine {
102                        sqlstate: "0A000".into(),
103                        message: format!("parameter \"{}\" cannot be reset", definition.name),
104                    });
105                }
106                self.check_parameter_change(definition)?;
107                self.store_setting(definition, None);
108                Ok(())
109            }
110            Some(SessionParameter::Placeholder(placeholder)) => {
111                self.store_placeholder(&placeholder, None);
112                Ok(())
113            }
114            None => self.create_placeholder(name),
115        }
116    }
117
118    /// Whether the current role may change `definition` (`set_config_option`'s context checks).
119    fn check_parameter_change(&self, definition: &ParameterDefinition) -> Result<(), SQLError> {
120        match definition.context {
121            ParameterContext::Internal => Err(SQLError::Routine {
122                sqlstate: "55P02".into(),
123                message: format!("parameter \"{}\" cannot be changed", definition.name),
124            }),
125            ParameterContext::Superuser if !self.current_user_is_superuser() => {
126                Err(SQLError::Routine {
127                    sqlstate: "42501".into(),
128                    message: format!("permission denied to set parameter \"{}\"", definition.name),
129                })
130            }
131            ParameterContext::Superuser | ParameterContext::User => Ok(()),
132        }
133    }
134
135    /// Read `value` as a setting of `definition` and apply the parameter's checks, as `parse_and_validate_value` and the check hooks do.
136    fn checked_setting(
137        &self,
138        definition: &ParameterDefinition,
139        value: &str,
140    ) -> Result<String, SQLError> {
141        if let Some(notice) = name_truncation_notice(definition, value) {
142            self.push_sql_notice(SQLNotice::notice(notice).with_sqlstate("42622"));
143        }
144        let setting = parse_setting_with_context(
145            definition,
146            value,
147            &self.session.setting(definition.name),
148            &self.session.reset_setting(definition),
149        )?;
150        match definition.name {
151            "application_name" => Ok(clean_ascii(&setting)),
152            "search_path" => {
153                if split_identifier_list(&setting, b',').is_none() {
154                    return Err(invalid_value(
155                        definition,
156                        &setting,
157                        "List syntax is invalid.".into(),
158                    ));
159                }
160                Ok(setting)
161            }
162            "default_with_oids" if setting == "on" => Err(SQLError::Routine {
163                sqlstate: "0A000".into(),
164                message: "tables declared WITH OIDS are not supported".into(),
165            }),
166            "default_tablespace" => {
167                if !setting.is_empty() && !TABLESPACES.contains(&setting.as_str()) {
168                    return Err(invalid_value(
169                        definition,
170                        &setting,
171                        format!("Tablespace \"{setting}\" does not exist."),
172                    ));
173                }
174                Ok(setting)
175            }
176            "default_table_access_method" => match access_method_kind(&setting) {
177                _ if setting.is_empty() => Err(invalid_value(
178                    definition,
179                    &setting,
180                    "\"default_table_access_method\" cannot be empty.".into(),
181                )),
182                Some(AccessMethodKind::Table) => Ok(setting),
183                Some(AccessMethodKind::Index) => Err(SQLError::Routine {
184                    sqlstate: "55000".into(),
185                    message: format!("access method \"{setting}\" is not of type TABLE"),
186                }),
187                None => Err(invalid_value(
188                    definition,
189                    &setting,
190                    format!("Table access method \"{setting}\" does not exist."),
191                )),
192            },
193            _ => Ok(setting),
194        }
195    }
196
197    /// Keep `setting` as the session's setting of `definition`, or remove the session's setting so that the reset setting applies, with the session state that follows the parameter.
198    fn store_setting(&self, definition: &ParameterDefinition, setting: Option<String>) {
199        let reset_path = (definition.name == "search_path" && setting.is_none())
200            .then(|| self.session_execution_view().reset_setting(definition));
201        let key = setting_key(definition.name);
202        let mut state = self.session.state.write();
203        match definition.name {
204            "search_path" => {
205                let text = setting
206                    .as_deref()
207                    .or(reset_path.as_deref())
208                    .unwrap_or_default();
209                state.search_path =
210                    split_identifier_list(text, b',').expect("checked search path syntax");
211                state.sql_statement_cache.clear();
212            }
213            "session_replication_role" => state.sql_statement_cache.clear(),
214            _ => {}
215        }
216        match setting {
217            Some(setting) => {
218                state.session_vars.insert(key, setting);
219            }
220            None => {
221                state.session_vars.remove(&key);
222            }
223        }
224    }
225
226    fn store_placeholder(&self, name: &str, setting: Option<String>) {
227        let key = setting_key(name);
228        let mut state = self.session.state.write();
229        match setting {
230            Some(setting) => {
231                state.session_vars.insert(key, setting);
232            }
233            None => {
234                state.session_vars.remove(&key);
235            }
236        }
237    }
238
239    /// Create a placeholder for the custom parameter `name`, which outlives the transaction that creates it.
240    fn create_placeholder(&self, name: &str) -> Result<(), SQLError> {
241        let mut registry = self.session.parameters.lock();
242        check_assignable_custom_name(name, registry.reserved_prefixes())?;
243        registry.add_placeholder(name);
244        Ok(())
245    }
246
247    /// The setting the session's search path takes after `RESET ALL` or `DISCARD ALL`.
248    pub(super) fn reset_search_path(&self) -> Vec<String> {
249        let definition = uqa_sql::semantics::parameters::catalog::find_parameter("search_path")
250            .expect("search_path is defined");
251        let setting = self.session_execution_view().reset_setting(definition);
252        split_identifier_list(&setting, b',').unwrap_or_else(default_search_path)
253    }
254
255    /// `set_config(name, value, is_local)`: assign `value`, or restore the reset setting for `None`, for the session or the transaction, and return the value as `SHOW` reports it.
256    pub(crate) fn set_config(
257        &self,
258        name: &str,
259        value: Option<&str>,
260        local: bool,
261    ) -> Result<String, SQLError> {
262        self.set_runtime_parameter(name, value, local)?;
263        self.session_execution_view().show_variable(name)
264    }
265
266    /// Keep `value` as the client's startup setting of `name`, which the session starts with and `RESET` restores (`PGC_S_CLIENT`).
267    pub fn set_client_parameter(&self, name: &str, value: &str) -> Result<(), SQLError> {
268        match self.session_execution_view().resolve_parameter(name) {
269            Some(SessionParameter::Defined(definition))
270                if is_transaction_characteristic(definition)
271                    || matches!(definition.name, "role" | "session_authorization") =>
272            {
273                self.set_variable(definition.name, value)
274            }
275            Some(SessionParameter::Defined(definition)) => {
276                self.check_parameter_change(definition)?;
277                let setting = self.checked_setting(definition, value)?;
278                if definition.name == "search_path" {
279                    self.session.state.write().search_path =
280                        split_identifier_list(&setting, b',').expect("checked search path syntax");
281                }
282                if definition.name == "client_min_messages" {
283                    if let Some(level) = crate::state::message_level(&setting) {
284                        self.session.state.set_reset_client_level(level);
285                    }
286                }
287                if definition.name == "lock_timeout" {
288                    if let Ok(milliseconds) = setting.parse::<u64>() {
289                        self.session.state.set_reset_lock_timeout(milliseconds);
290                    }
291                }
292                if definition.name == "track_io_timing" {
293                    self.session.state.set_reset_io_timing(setting == "on");
294                }
295                self.session
296                    .parameters
297                    .lock()
298                    .set_client_setting(definition.name, setting);
299                // A client that sets a session timeout at startup is idle from then on, as a backend that waits for its first query is.
300                if matches!(
301                    definition.name,
302                    "idle_session_timeout"
303                        | "idle_in_transaction_session_timeout"
304                        | "transaction_timeout"
305                ) && self.runtime.terminations.is_idle()
306                {
307                    self.session_became_idle();
308                }
309                Ok(())
310            }
311            Some(SessionParameter::Placeholder(placeholder)) => {
312                self.store_placeholder(&placeholder, Some(value.to_string()));
313                Ok(())
314            }
315            None => {
316                self.create_placeholder(name)?;
317                self.store_placeholder(name, Some(value.to_string()));
318                Ok(())
319            }
320        }
321    }
322
323    /// Load `library` into the session: its parameters become defined, its prefix is reserved, and each placeholder under the prefix either becomes the setting of the parameter it names or, naming none, is removed with a warning (`MarkGUCPrefixReserved`).
324    pub(crate) fn load_parameter_library(&self, library: &'static str) {
325        let placeholders = {
326            let mut registry = self.session.parameters.lock();
327            if !registry.load_library(library) {
328                return;
329            }
330            registry.placeholders_with_prefix(library)
331        };
332        for placeholder in placeholders {
333            let key = setting_key(&placeholder);
334            let value = self.session.state.read().session_vars.get(&key).cloned();
335            self.session
336                .parameters
337                .lock()
338                .remove_placeholder(&placeholder);
339            let definition = uqa_sql::semantics::parameters::catalog::find_parameter(&placeholder)
340                .filter(|definition| definition.library == Some(library));
341            let Some(definition) = definition else {
342                let (message, detail) = reserved_placeholder_warning(&placeholder, library);
343                self.push_sql_notice(
344                    SQLNotice::warning(message)
345                        .with_sqlstate("42602")
346                        .with_detail(detail),
347                );
348                self.session.state.write().session_vars.remove(&key);
349                continue;
350            };
351            let Some(value) = value else {
352                continue;
353            };
354            match self.checked_setting(definition, &value) {
355                Ok(setting) => {
356                    self.session.state.write().session_vars.insert(key, setting);
357                }
358                Err(error) => {
359                    self.push_sql_notice(
360                        SQLNotice::warning(error.to_string())
361                            .with_sqlstate(error.sqlstate().unwrap_or("22023")),
362                    );
363                    self.session.state.write().session_vars.remove(&key);
364                }
365            }
366        }
367    }
368}