Struct Session

pub struct Session<T = Timestamp>
where
    T: Debug + Clone + Send + Sync,
{

    conn_id: ConnectionId,
    uuid: Uuid,
    prepared_statements: BTreeMap<String, PreparedStatement>,
    portals: BTreeMap<String, Portal>,
    transaction: TransactionStatus<T>,
    pcx: Option<PlanContext>,
    metrics: SessionMetrics,
    builtin_updates: Option<Pin<Box<dyn Future<Output = ()> + Send + Sync + 'static>>>,
    role_metadata: Option<RoleMetadata>,
    client_ip: Option<IpAddr>,
    vars: SessionVars,
    notices_tx: UnboundedSender<AdapterNotice>,
    notices_rx: UnboundedReceiver<AdapterNotice>,
    next_transaction_id: TransactionId,
    secret_key: u32,
    external_metadata_rx: Option<Receiver<ExternalUserMetadata>>,
    qcell_owner: QCellOwner,
    session_oracles: BTreeMap<Timeline, InMemoryTimestampOracle<T, NowFn<T>>>,
    state_revision: u64,
}

A session holds per-connection state.

Fields

conn_id: ConnectionId

uuid: Uuid

A globally unique identifier for the session. Not to be confused with conn_id, which may be reused.

prepared_statements: BTreeMap<String, PreparedStatement>

portals: BTreeMap<String, Portal>

transaction: TransactionStatus<T>

pcx: Option<PlanContext>

metrics: SessionMetrics

builtin_updates: Option<Pin<Box<dyn Future<Output = ()> + Send + Sync + 'static>>>

role_metadata: Option<RoleMetadata>

The role metadata of the current session.

Invariant: role_metadata must be Some after the user has successfully connected to and authenticated with Materialize.

Prefer using this value over SessionConfig::user.

client_ip: Option<IpAddr>

vars: SessionVars

notices_tx: UnboundedSender<AdapterNotice>

notices_rx: UnboundedReceiver<AdapterNotice>

next_transaction_id: TransactionId

secret_key: u32

external_metadata_rx: Option<Receiver<ExternalUserMetadata>>

qcell_owner: QCellOwner

session_oracles: BTreeMap<Timeline, InMemoryTimestampOracle<T, NowFn<T>>>

state_revision: u64

Incremented when session state that is relevant to prepared statement planning changes. Currently, only changes to portals are tracked. Changes to prepared_statements don’t need to be tracked, because prepared statements can’t depend on other prepared statements. TODO: We might want to track changes also to session variables. (Catalog::transient_revision similarly tracks changes on the catalog side.)

Implementations

impl<T: TimestampManipulation> Session<T>

pub(crate) fn new( build_info: &'static BuildInfo, config: SessionConfig, metrics: SessionMetrics, ) -> Session<T>

Creates a new session for the specified connection ID.

pub fn meta(&self) -> SessionMeta

Returns a reference-less collection of data usable by other tasks that don’t have ownership of the Session.

pub(crate) fn mint_logging<A: AstInfo>( &self, raw_sql: String, stmt: Option<&Statement<A>>, now: EpochMillis, ) -> Arc<QCell<PreparedStatementLoggingInfo>>

Creates new statement logging metadata for a one-off statement.

pub(crate) fn qcell_rw<'a, T2: 'a>( &'a mut self, cell: &'a Arc<QCell<T2>>, ) -> &'a mut T2

pub fn uuid(&self) -> Uuid

Returns a unique ID for the session. Not to be confused with connection_id, which can be reused.

pub fn dummy() -> Session<T>

Creates a new dummy session.

Dummy sessions are intended for use when executing queries on behalf of the system itself, rather than on behalf of a user.

fn new_internal( build_info: &'static BuildInfo, _: SessionConfig, metrics: SessionMetrics, ) -> Session<T>

pub fn secret_key(&self) -> u32

Returns the secret key associated with the session.

fn new_pcx(&self, wall_time: DateTime<Utc>) -> PlanContext

pub fn start_transaction( &mut self, wall_time: DateTime<Utc>, access: Option<TransactionAccessMode>, isolation_level: Option<TransactionIsolationLevel>, ) -> Result<(), AdapterError>

Starts an explicit transaction, or changes an implicit to an explicit transaction.

pub fn start_transaction_implicit( &mut self, wall_time: DateTime<Utc>, stmts: usize, )

Starts either a single statement or implicit transaction based on the number of statements, but only if no transaction has been started already.

pub fn start_transaction_single_stmt(&mut self, wall_time: DateTime<Utc>)

Starts a single statement transaction, but only if no transaction has been started already.

pub fn clear_transaction(&mut self) -> TransactionStatus<T>

Clears a transaction, setting its state to Default and destroying all portals. Returned are:

• sinks that were started in this transaction and need to be dropped
• the cleared transaction so its operations can be handled

The Postgres protocol docs specify:

a named portal object lasts till the end of the current transaction and An unnamed portal is destroyed at the end of the transaction

pub fn fail_transaction(self) -> Self

Marks the current transaction as failed.

pub fn transaction(&self) -> &TransactionStatus<T>

Returns the current transaction status.

pub fn transaction_mut(&mut self) -> &mut TransactionStatus<T>

Returns the current transaction status.

pub fn transaction_code(&self) -> TransactionCode

Returns the session’s transaction code.

pub fn add_transaction_ops( &mut self, add_ops: TransactionOps<T>, ) -> Result<(), AdapterError>

Adds operations to the current transaction. An error is produced if they cannot be merged (i.e., a timestamp-dependent read cannot be merged to an insert).

pub fn retain_notice_transmitter(&self) -> UnboundedSender<AdapterNotice>

Returns a channel on which to send notices to the session.

pub fn add_notice(&self, notice: AdapterNotice)

Adds a notice to the session.

pub fn add_notices(&self, notices: impl IntoIterator<Item = AdapterNotice>)

Adds multiple notices to the session.

pub async fn recv_notice(&mut self) -> AdapterNotice

Awaits a possible notice.

This method is cancel safe.

pub fn drain_notices(&mut self) -> Vec<AdapterNotice>

Returns a draining iterator over the notices attached to the session.

fn notice_filter(&self, notice: AdapterNotice) -> Option<AdapterNotice>

Returns Some if the notice should be reported, otherwise None.

pub fn clear_transaction_ops(&mut self)

Sets the transaction ops to TransactionOps::None. Must only be used after verifying that no transaction anomalies will occur if cleared.

pub fn take_transaction_timestamp_context( &mut self, ) -> Option<TimestampContext<T>>

If the current transaction ops belong to a read, then sets the ops to None, returning the old read timestamp context if any existed. Must only be used after verifying that no transaction anomalies will occur if cleared.

pub fn get_transaction_timestamp_determination( &self, ) -> Option<TimestampDetermination<T>>

Returns the transaction’s read timestamp determination, if set.

Returns None if there is no active transaction, or if the active transaction is not a read transaction.

pub fn contains_read_timestamp(&self) -> bool

Whether this session has a timestamp for a read transaction.

pub fn set_prepared_statement( &mut self, name: String, stmt: Option<Statement<Raw>>, raw_sql: String, desc: StatementDesc, state_revision: StateRevision, now: EpochMillis, )

Registers the prepared statement under name.

pub fn remove_prepared_statement(&mut self, name: &str) -> bool

Removes the prepared statement associated with name.

Returns whether a statement previously existed.

pub fn remove_all_prepared_statements(&mut self)

Removes all prepared statements.

pub fn get_prepared_statement_unverified( &self, name: &str, ) -> Option<&PreparedStatement>

Retrieves the prepared statement associated with name.

This is unverified and could be incorrect if the underlying catalog has changed.

pub fn get_prepared_statement_mut_unverified( &mut self, name: &str, ) -> Option<&mut PreparedStatement>

Retrieves the prepared statement associated with name.

This is unverified and could be incorrect if the underlying catalog has changed.

pub fn prepared_statements(&self) -> &BTreeMap<String, PreparedStatement>

Returns the prepared statements for the session.

pub fn portals(&self) -> &BTreeMap<String, Portal>

Returns the portals for the session.

pub fn set_portal( &mut self, portal_name: String, desc: StatementDesc, stmt: Option<Statement<Raw>>, logging: Arc<QCell<PreparedStatementLoggingInfo>>, params: Vec<(Datum<'_>, SqlScalarType)>, result_formats: Vec<Format>, state_revision: StateRevision, ) -> Result<(), AdapterError>

Binds the specified portal to the specified prepared statement.

If the prepared statement contains parameters, the values and types of those parameters must be provided in params. It is the caller’s responsibility to ensure that the correct number of parameters is provided.

The results_formats parameter sets the desired format of the results, and is stored on the portal.

pub fn remove_portal(&mut self, portal_name: &str) -> bool

Removes the specified portal.

If there is no such portal, this method does nothing. Returns whether that portal existed.

pub fn get_portal_unverified(&self, portal_name: &str) -> Option<&Portal>

Retrieves a reference to the specified portal.

If there is no such portal, returns None.

pub fn get_portal_unverified_mut( &mut self, portal_name: &str, ) -> Option<PortalRefMut<'_>>

Retrieves a mutable reference to the specified portal.

If there is no such portal, returns None.

Note: When using the returned PortalRefMut, there is no need to increment Session::state_revision, because the portal’s meaning is not changed.

pub fn create_new_portal( &mut self, stmt: Option<Statement<Raw>>, logging: Arc<QCell<PreparedStatementLoggingInfo>>, desc: StatementDesc, parameters: Params, result_formats: Vec<Format>, state_revision: StateRevision, ) -> Result<String, AdapterError>

Creates and installs a new portal.

pub fn reset(&mut self)

Resets the session to its initial state. Returns sinks that need to be dropped.

pub fn application_name(&self) -> &str

Returns the application_name that created this session.

pub fn vars(&self) -> &SessionVars

Returns a reference to the variables in this session.

pub fn vars_mut(&mut self) -> &mut SessionVars

Returns a mutable reference to the variables in this session.

pub fn try_grant_write_locks( &mut self, guards: WriteLocks, ) -> Result<(), &WriteLocks>

Grants a set of write locks to this session’s inner Transaction.

Panics

If the inner transaction is idle. See TransactionStatus::try_grant_write_locks.

pub fn apply_external_metadata_updates(&mut self)

Drains any external metadata updates and applies the changes from the latest update.

pub fn initialize_role_metadata(&mut self, role_id: RoleId)

Initializes the session’s role metadata.

pub fn ensure_timestamp_oracle( &mut self, timeline: Timeline, ) -> &mut InMemoryTimestampOracle<T, NowFn<T>>

Ensures that a timestamp oracle exists for timeline and returns a mutable reference to the timestamp oracle.

pub fn ensure_local_timestamp_oracle( &mut self, ) -> &mut InMemoryTimestampOracle<T, NowFn<T>>

Ensures that a timestamp oracle exists for reads and writes from/to a local input and returns a mutable reference to the timestamp oracle.

pub fn get_timestamp_oracle( &self, timeline: &Timeline, ) -> Option<&InMemoryTimestampOracle<T, NowFn<T>>>

Returns a reference to the timestamp oracle for timeline.

pub fn apply_write(&mut self, timestamp: T)

If the current session is using the Strong Session Serializable isolation level advance the session local timestamp oracle to write_ts.

pub fn metrics(&self) -> &SessionMetrics

Returns the SessionMetrics instance associated with this Session.

pub fn set_builtin_table_updates( &mut self, fut: Pin<Box<dyn Future<Output = ()> + Send + Sync + 'static>>, )

Sets the BuiltinTableAppendNotify for this session.

pub fn clear_builtin_table_updates( &mut self, ) -> Option<impl Future<Output = ()> + 'static>

Takes the stashed BuiltinTableAppendNotify, if one exists, and returns a Future that waits for the writes to complete.

pub fn state_revision(&self) -> u64

Return the state_revision of the session, which can be used by dependent objects for knowing when to re-plan due to session state changes.

Trait Implementations

impl<T> Debug for Session<T>

where T: Debug + Clone + Send + Sync + Debug,

fn fmt(&self, __f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> SessionMetadata for Session<T>

where T: Debug + Clone + Send + Sync + TimestampManipulation,

fn conn_id(&self) -> &ConnectionId

Returns the connection ID associated with the session.

fn client_ip(&self) -> Option<&IpAddr>

Returns the client address associated with the session.

fn pcx(&self) -> &PlanContext

Returns the current transaction’s PlanContext. Panics if there is not a current transaction.

fn role_metadata(&self) -> &RoleMetadata

Returns the role metadata for this session.

fn vars(&self) -> &SessionVars

Returns the session vars for this session.

fn current_role_id(&self) -> &RoleId

Returns the session’s current role ID.

fn session_role_id(&self) -> &RoleId

Returns the session’s session role ID.

fn user(&self) -> &User

fn database(&self) -> &str

fn search_path(&self) -> &[Ident]

fn is_superuser(&self) -> bool

fn enable_session_rbac_checks(&self) -> bool