Trait Session 

pub trait Session {
    // Required methods
    fn date_format(&self) -> DateFormat;
    fn interval_style(&self) -> IntervalStyle;
    fn zone(&self) -> Result<Rc<dyn TimeZone>>;
    fn extra_float_digits(&self) -> i32;
    fn bytea_output(&self) -> ByteaOutput;
    fn array_nulls(&self) -> bool;
    fn transaction_start(&self) -> i64;
    fn statement_start(&self) -> i64;
    fn clock(&self) -> i64;
    fn user(&self) -> Cow<'_, str>;
    fn session_user(&self) -> &str;
    fn database(&self) -> &str;
    fn schemas(&self) -> Vec<String>;
    fn backend_pid(&self) -> i32;
    fn version(&self) -> String;
    fn setting(&self, name: &str) -> Option<String>;
    fn set_setting(
        &self,
        name: &str,
        value: Option<&str>,
        local: bool,
    ) -> Result<String>;

    // Provided methods
    fn system_user(&self) -> Option<String> { ... }
    fn query(&self) -> Option<String> { ... }
    fn temp_number(&self) -> Option<i32> { ... }
    fn trigger_depth(&self) -> i32 { ... }
    fn transaction_id(&self, assign: bool) -> Option<u64> { ... }
    fn next_transaction_id(&self) -> u64 { ... }
    fn stable_transaction_id(&self) -> u32 { ... }
    fn transaction_state(&self, xid: u32) -> Option<XactState> { ... }
    fn current_snapshot(&self) -> Option<Snapshot> { ... }
    fn setting_list(&self, name: &str, text: &str) -> Option<Vec<String>> { ... }
    fn start_function_call(
        &self,
        config: &[String],
        definer: Option<u32>,
    ) -> Result<()> { ... }
    fn end_function_call(&self) { ... }
    fn interrupted(&self) -> Result<()> { ... }
    fn sleep(&self, micros: i64) -> Result<()> { ... }
    fn advisory_lock(&self, lock: AdvisoryLock, wait: bool) -> Result<bool> { ... }
    fn advisory_unlock(&self, lock: AdvisoryLock) -> Result<bool> { ... }
    fn advisory_unlock_all(&self) -> Result<()> { ... }
    fn all_settings(&self) -> Vec<Vec<Value>> { ... }
    fn prepared_statements(&self) -> Vec<Vec<Value>> { ... }
    fn cursors(&self) -> Vec<Vec<Value>> { ... }
    fn hba_rules(&self) -> Result<Vec<Vec<Value>>> { ... }
    fn ident_mappings(&self) -> Result<Vec<Vec<Value>>> { ... }
    fn file_settings(&self) -> Vec<Vec<Value>> { ... }
    fn role_password(&self, role: u32) -> Option<String> { ... }
    fn sequence_row(&self, file: u32) -> Option<SequenceData> { ... }
    fn change_sequence(
        &self,
        file: u32,
        initial: SequenceData,
        change: &mut dyn FnMut(&mut SequenceData) -> Result<()>,
    ) -> Result<()> { ... }
    fn local_sequences(&self) -> Option<&RefCell<Sequences>> { ... }
    fn randomness(&self) -> Option<&RefCell<Randomness>> { ... }
    fn strong_random(&self, buf: &mut [u8]) { ... }
    fn catalog(&self) -> Option<&Catalog> { ... }
    fn transition_rows(&self, name: &str) -> Option<Rc<Vec<Vec<Value>>>> { ... }
    fn databases(&self) -> Arc<[Database]>  { ... }
    fn tablespaces(&self) -> Arc<[Tablespace]>  { ... }
    fn db_role_settings(&self) -> Vec<(u32, u32, Vec<String>)> { ... }
    fn backends(&self) -> Arc<[Backend]>  { ... }
    fn blocking_pids(&self, pid: i32) -> Vec<i32> { ... }
    fn clear_backends(&self) { ... }
    fn count_scan(&self, relation: u32) { ... }
    fn table_rows(&self, relation: u32) -> Result<Vec<Vec<Value>>> { ... }
    fn table_rows_with_xids(&self, relation: u32) -> Result<Vec<Vec<Value>>> { ... }
    fn relation_counts(&self, relation: u32) -> Option<RelationCounts> { ... }
    fn pending_scans(&self, relation: u32) -> i64 { ... }
    fn pending_writes(&self, relation: u32) -> Writes { ... }
    fn stats_reset(&self) -> i64 { ... }
    fn addresses(&self) -> (Client, Client) { ... }
    fn input_checks(&self, ty: u32, value: &Value) -> Result<Option<Error>> { ... }
    fn warn(&self, warning: Error) { ... }
    fn run_query(&self, text: &str) -> Result<(Vec<u32>, Vec<Vec<Value>>)> { ... }
    fn current_of(&self, cursor: &str, table: u32) -> Result<(Value, Value)> { ... }
    fn call_sql_function(
        &self,
        func: u32,
        types: &[u32],
        args: &[Value],
    ) -> Result<(Vec<u32>, Vec<Vec<Value>>)> { ... }
    fn call_function(
        &self,
        func: u32,
        types: &[u32],
        ret: u32,
        args: &[Value],
    ) -> Result<Vec<Value>> { ... }
}

The state of the session that the functions read.

Required Methods

fn date_format(&self) -> DateFormat

The DateStyle setting.

fn interval_style(&self) -> IntervalStyle

The IntervalStyle setting.

fn zone(&self) -> Result<Rc<dyn TimeZone>>

The TimeZone setting.

Errors

22023 when the value of TimeZone is not a zone.

fn extra_float_digits(&self) -> i32

The extra_float_digits setting.

fn bytea_output(&self) -> ByteaOutput

The bytea_output setting.

fn array_nulls(&self) -> bool

The array_nulls setting.

fn transaction_start(&self) -> i64

The start of the transaction in microseconds since 2000-01-01 UTC.

fn statement_start(&self) -> i64

The start of the statement in microseconds since 2000-01-01 UTC.

fn clock(&self) -> i64

The time now in microseconds since 2000-01-01 UTC.

fn user(&self) -> Cow<'_, str>

The current user, which is the owner during a call of a SECURITY DEFINER function.

fn session_user(&self) -> &str

The session user.

fn database(&self) -> &str

The current database.

fn schemas(&self) -> Vec<String>

The schemas of search_path that exist, in order, without the implicit schemas.

fn backend_pid(&self) -> i32

The process ID of the session.

fn version(&self) -> String

The text of version().

fn setting(&self, name: &str) -> Option<String>

The value of a setting as SHOW gives it, or None for a name that is not a setting.

fn set_setting( &self, name: &str, value: Option<&str>, local: bool, ) -> Result<String>

set_config_option for set_config: sets a parameter for the session, or for the transaction when local is true, and gives the new value as SHOW gives it. value is None for a reset.

Errors

The errors of SET for the name and the value.

Provided Methods

fn system_user(&self) -> Option<String>

SYSTEM_USER: the method of the authentication and the identity that it checked, as auth_method:authn_id, or None when the method checked no identity, as for trust.

fn query(&self) -> Option<String>

debug_query_string: the text of the message of the client that runs the statement, which current_query gives.

fn temp_number(&self) -> Option<i32>

The number of the session in the table of the sessions, which names its temporary schema pg_temp_N, or None for a session that cannot have temporary objects.

fn trigger_depth(&self) -> i32

MyTriggerDepth: the number of the trigger functions that run, one in the other. It is 0 outside of a trigger.

fn transaction_id(&self, assign: bool) -> Option<u64>

The ID of the transaction: GetTopFullTransactionId when assign is true, which gives an ID to a transaction that has none, and GetTopFullTransactionIdIfAny when it is false. None when the transaction has no ID or the session has no server.

fn next_transaction_id(&self) -> u64

ReadNextFullTransactionId: the ID that the next transaction gets.

fn stable_transaction_id(&self) -> u32

GetStableLatestTransactionId: the ID of the transaction, or the ID that the next transaction gets when it has none, the same for the whole transaction.

fn transaction_state(&self, xid: u32) -> Option<XactState>

The state of the transaction xid, which is before Session::next_transaction_id, or None when the session does not know it.

fn current_snapshot(&self) -> Option<Snapshot>

GetActiveSnapshot: the snapshot of the statement as a pg_snapshot, or None when the statement has no snapshot.

fn setting_list(&self, name: &str, text: &str) -> Option<Vec<String>>

GetConfigOptionFlags with GUC_LIST_QUOTE and SplitGUCList: the elements of the value text of the parameter name when the parameter quotes the elements of its list, or None for another parameter and for a name that is not a parameter.

fn start_function_call( &self, config: &[String], definer: Option<u32>, ) -> Result<()>

fmgr_security_definer for a function with settings or with SECURITY DEFINER: definer, the owner of a SECURITY DEFINER function, is the current user, and ProcessGUCArray with GUC_ACTION_SAVE gives the settings of proconfig, each one as name=value, until Session::end_function_call. A session with no settings does nothing.

Errors

The errors of the names and of the values.

fn end_function_call(&self)

The end of the call of Session::start_function_call: the current user from before the call comes back, and AtEOXact_GUC gives the settings their values from before the call, other than the ones that a SET in the call changed.

fn interrupted(&self) -> Result<()>

CHECK_FOR_INTERRUPTS: the check for a cancel of the statement, which a long loop of the executor, such as the loop of a recursive query, does at each step. A session with no server has no cancel.

Errors

57014 when a client canceled the statement.

fn sleep(&self, micros: i64) -> Result<()>

WaitLatch with the wait event PgSleep: the session waits for at most micros microseconds. A cancel ends the wait early, and the next call of Session::interrupted gives its error.

Errors

0A000 for a session with no server, which cannot wait.

fn advisory_lock(&self, lock: AdvisoryLock, wait: bool) -> Result<bool>

LockAcquire of an advisory lock in the database of the session. With wait, the session waits while another session holds or waits for a lock that conflicts, and then gives true. Without wait, it gives false at once.

Errors

57014 for a cancel, 40P01 for a deadlock, 55P03 for the end of lock_timeout, and 0A000 for a session with no server.

fn advisory_unlock(&self, lock: AdvisoryLock) -> Result<bool>

LockRelease of an advisory lock of the session level. It gives false when the session does not hold the lock in this mode at the session level.

Errors

0A000 for a session with no server.

fn advisory_unlock_all(&self) -> Result<()>

LockReleaseSession: releases all the advisory locks of the session level.

Errors

0A000 for a session with no server.

fn all_settings(&self) -> Vec<Vec<Value>>

The rows of pg_show_all_settings, one for each parameter that SHOW ALL lists, in the 17 columns of the function.

fn prepared_statements(&self) -> Vec<Vec<Value>>

The rows of pg_prepared_statement, one for each named prepared statement of the session, in the 8 columns of the function. The order is not defined.

fn cursors(&self) -> Vec<Vec<Value>>

The rows of pg_cursor, one for each cursor of DECLARE that is open in the session, in the 6 columns of the function. The order is not defined.

fn hba_rules(&self) -> Result<Vec<Vec<Value>>>

The rows of pg_hba_file_rules, one for each line of the host rules, in the 11 columns of the function. A session with no server has no rules and no rows.

Errors

The error of a file of the rules that does not open.

fn ident_mappings(&self) -> Result<Vec<Vec<Value>>>

The rows of pg_ident_file_mappings, one for each line of the user maps, in the 7 columns of the function. A session with no server has no maps and no rows.

Errors

The error of a file of the maps that does not open.

fn file_settings(&self) -> Vec<Vec<Value>>

The rows of pg_show_all_file_settings, one for each line of the configuration files and each error in them, in the 7 columns of the function. A session with no server has no rows.

fn role_password(&self, role: u32) -> Option<String>

The stored secret of the password of a role, which pg_authid.rolpassword shows, or None for a role with no password.

fn sequence_row(&self, file: u32) -> Option<SequenceData>

The row of the file of a sequence as the sessions changed it, or None when no session changed it, so that the row is the one of the file when it was made.

fn change_sequence( &self, file: u32, initial: SequenceData, change: &mut dyn FnMut(&mut SequenceData) -> Result<()>, ) -> Result<()>

The change of the row of the file of a sequence, outside of the transaction, so that a rollback does not undo it. initial is the row when no session changed it yet. The change stays only when change gives no error, and no other session changes the row at the same time.

Errors

The error of change, and 0A000 for a session with no server.

fn local_sequences(&self) -> Option<&RefCell<Sequences>>

The cache of the sequences of the session, or None for a session with no server.

fn randomness(&self) -> Option<&RefCell<Randomness>>

The state of random and uuidv7 of the session, or None for a session with no server, which uses a state of its thread.

fn strong_random(&self, buf: &mut [u8])

pg_strong_random: fills buf with random bytes. A session with no server takes them from a generator with a seed from the clock.

fn catalog(&self) -> Option<&Catalog>

The catalog of the user objects that the statement sees, or None when the session has no catalog.

fn transition_rows(&self, name: &str) -> Option<Rc<Vec<Vec<Value>>>>

The rows of the transition table name of the trigger that runs, which a scan of a NamedTuplestoreScan reads, or None when the trigger has no such table.

fn databases(&self) -> Arc<[Database]>

The rows of pg_database of the databases that CREATE DATABASE made, in the order of their OIDs. The rows of initdb are static rows. A session with no server has no other databases.

fn tablespaces(&self) -> Arc<[Tablespace]>

The rows of pg_tablespace of the tablespaces that CREATE TABLESPACE made, in the order of their OIDs. The rows of pg_default and pg_global are static rows. A session with no server has no other tablespaces.

fn db_role_settings(&self) -> Vec<(u32, u32, Vec<String>)>

The rows of pg_db_role_setting: the OID of the database, the OID of the role, and the settings, each as name=value. A session with no server has no rows.

fn backends(&self) -> Arc<[Backend]>

The rows of the table of the sessions in the order of their numbers, from the snapshot of the transaction. The first call of a transaction takes the snapshot.

fn blocking_pids(&self, pid: i32) -> Vec<i32>

BackendPidGetProc and GetBlockerStatusData: the process IDs of the sessions that hold or wait for a lock that the session pid waits for, or for whose transaction it waits. A session with no server has no waits.

fn clear_backends(&self)

pgstat_clear_snapshot: drops the snapshot of the table of the sessions and of the statistics.

fn count_scan(&self, relation: u32)

pgstat_count_heap_scan: counts a sequential scan of a relation in the counts of the transaction. A session with no server keeps no counts.

fn table_rows(&self, relation: u32) -> Result<Vec<Vec<Value>>>

The rows of a table of the user that the snapshot of the statement sees, each with a value for each column of the table when the row was written. A session with no server has no rows.

Errors

An error of the store of the rows.

fn table_rows_with_xids(&self, relation: u32) -> Result<Vec<Vec<Value>>>

The rows of Session::table_rows, each with the system columns xmin and xmax of its version before the ID of the version.

Errors

An error of the store of the rows.

fn relation_counts(&self, relation: u32) -> Option<RelationCounts>

pgstat_fetch_stat_tabentry: the counters of a relation of the database of the session, from the snapshot of the transaction, or None for a relation with no entry. The first call of a transaction takes the snapshot.

fn pending_scans(&self, relation: u32) -> i64

find_tabstat_entry: the sequential scans of a relation that the transaction counted and did not report yet.

fn pending_writes(&self, relation: u32) -> Writes

find_tabstat_entry: the rows that the transaction wrote in a relation and did not report yet, with the rows of the subtransactions that rolled back.

fn stats_reset(&self) -> i64

The time of the last reset of the statistics of the whole server in microseconds since 2000-01-01 UTC, or 0 when the session has no server.

fn addresses(&self) -> (Client, Client)

The two ends of the connection of the session: the client, then the server.

fn input_checks(&self, ty: u32, value: &Value) -> Result<Option<Error>>

domain_check_safe for a value of a domain or for each element of an array of a domain: the error of the first check constraint that rejects the value, or None when the value passes. The engine evaluates the checks, so a session without an engine cannot do this.

Errors

The error of a check expression.

fn warn(&self, warning: Error)

ereport(WARNING) or ereport(NOTICE) in a function: a message for the client, such as the warning of the input of an aclitem value with no grantor. A message with a SQLSTATE of class 00 or with the mark of Error::as_notice is a NOTICE, and any other message is a WARNING. A session with no client drops it.

fn run_query(&self, text: &str) -> Result<(Vec<u32>, Vec<Vec<Value>>)>

SPI_cursor_open of a read-only plan for text and the fetch of all its rows, for a function that runs a query, such as ts_stat. It gives the type of each column and the rows.

Errors

42P11 when the text is not one statement that gives rows, the errors of the query, and 0A000 for a session that cannot run a query.

fn current_of(&self, cursor: &str, table: u32) -> Result<(Value, Value)>

execCurrentOf: the tableoid and the ctid of the row of the table table that the cursor cursor is on.

Errors

34000 when there is no such cursor, and 24000 when the cursor is not on a row of the table.

fn call_sql_function( &self, func: u32, types: &[u32], args: &[Value], ) -> Result<(Vec<u32>, Vec<Vec<Value>>)>

fmgr_sql for a function in SQL whose body is rupg_analyze::Body::Statements: a call of the function func with the values args of the types types. The statements run one after the other, and the call gives the types of the columns of the last statement and its rows.

Errors

The errors of the statements, and 0A000 for a session that cannot run them.

fn call_function( &self, func: u32, types: &[u32], ret: u32, args: &[Value], ) -> Result<Vec<Value>>

plpgsql_call_handler: a call of the function func in PL/pgSQL with the values args of the types types, for the result type ret. It gives the value of the function, or a value for each row of a function that returns a set. A row is a Record.

Errors

The errors of the function, and 0A000 for a session that cannot run a function in PL/pgSQL.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors