Struct Session 

pub struct Session<'a> { /* private fields */ }

The statements that make a transaction run as a caller.

Built from the caller’s role and claim settings and the configuration; everything about an HTTP request is optional and added with the builder methods. A session with no request at all still sets the role, the claims, the search_path – the default schema and db_extra_search_path – and the app.settings.*, and still runs db_pre_request, so a hand-written route sees what a policy or function expects to see. The request settings it was not given (request.method, request.path, request.headers, request.cookies) are left unset, which current_setting(name, true) reads as null.

Implementations

impl Session<'_>

pub async fn apply_sqlx(&self, conn: &mut PgConnection) -> Result<(), DbError>

Run this session’s statements on a sqlx connection, in order.

For code that holds a sqlx transaction of its own rather than a Tx – GraphQL’s resolvers, a hand-written route – and has to make it the caller’s. Pass the transaction (&mut *tx): every setting is transaction-local, so it is gone when the transaction ends and the connection goes back to the pool as it came. On a connection outside a transaction each statement would be its own, and nothing would stay.

Parameters are bound as SqlxTx binds them, so a session means the same thing to both. A failure here is reported as a queued statement’s, as it is when Tx::queue runs the same statements.

impl<'a> Session<'a>

pub fn new( config: &'a AppConfig, role: impl Into<String>, claims: Vec<(String, String)>, ) -> Self

A session for role, carrying claims – the request.jwt.claims* settings, as postrust_auth::AuthResult::claim_settings renders them.

Read-write, with db_pre_request run if one is configured.

pub fn schema(self, schema: impl Into<String>) -> Self

The schema the request is for, which leads the search_path. Without one it is the configuration’s default schema.

pub fn request(self, method: impl Into<String>, path: impl Into<String>) -> Self

The request’s method and path, as request.method and request.path.

pub fn headers(self, headers: &IndexMap<String, String>) -> Self

The request’s headers, as request.headers.

pub fn cookies(self, cookies: &IndexMap<String, String>) -> Self

The request’s cookies, as request.cookies.

pub fn trace_id(self, trace_id: Option<String>) -> Self

The trace the request belongs to, as request.trace_id.

So that a statement seen in pg_stat_activity or the server log – by auto_explain, or a log_line_prefix reading the setting – can be tied back to the trace of the request that sent it. Unset without one.

pub fn timezone(self, timezone: Option<String>) -> Self

The session time zone, from Prefer: timezone.

pub fn setting(self, name: impl Into<String>, value: impl Into<String>) -> Self

One more setting, set after all of the others.

For what a caller other than REST tells the database about itself – GraphQL’s hasura.* session variables, say. The name is bound as a parameter like every other, so it is PostgreSQL that decides whether it is a name it will take.

pub fn isolation(self, isolation: Option<IsolationLevel>) -> Self

The transaction’s isolation level, over the role’s and the server’s.

Without one it is the role’s own setting where it has one, and PGRST_DB_TX_ISOLATION otherwise. For a caller that knows what it needs of one transaction – a hand-written route that reads twice and needs both reads to agree. None leaves the choice to the configuration.

pub fn read_only(self, read_only: bool) -> Self

Whether the transaction is read-only. See Session::statements.

pub fn set_search_path(self, set_search_path: bool) -> Self

Whether to set search_path to the schema and db_extra_search_path. On unless turned off.

Off for SQL that qualifies every name it means to come from the API’s schemas, and should otherwise resolve names as the role and the database normally would – GraphQL’s, which calls extension functions such as PostGIS’s unqualified, wherever the database installed them.

pub fn pre_request(self, pre_request: bool) -> Self

Whether to call db_pre_request, where one is configured. On unless turned off.

pub fn role(&self) -> &str

The role this session runs as.

pub fn apply<T: Tx>(&self, tx: &mut T)

Queue this session’s statements on tx, to go out ahead of its next statement – see Tx::queue. They have to be the first statements on the transaction: SET TRANSACTION is refused after any other.

pub fn statements(&self) -> Vec<SessionStatement>

The statements Session::apply queues, in the order it queues them.

At most four, and usually two: an isolation level, read-only, every setting in one SELECT, and the pre-request function.

Trait Implementations

impl<'a> Clone for Session<'a>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Session<'a>

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

Formats the value using the given formatter.