Struct Context

pub struct Context { /* private fields */ }

Context information provided by PgDog to the plugin at statement execution. It contains the actual statement and several metadata about the state of the database cluster:

• Number of shards
• Does it have replicas
• Does it have a primary

Example

use pgdog_plugin::{Context, Route, macros, Shard, ReadWrite};

#[macros::route]
fn route(context: Context) -> Route {
    let shards = context.shards();
    let read_only = context.read_only();
    let ast = context.statement().protobuf();

    println!("shards: {} (read_only: {})", shards, read_only);
    println!("ast: {:#?}", ast);

    let read_write = if read_only {
        ReadWrite::Read
    } else {
        ReadWrite::Write
    };

    Route::new(Shard::Direct(0), read_write)
}

Implementations

impl Context

pub fn statement(&self) -> Statement

Returns a reference to the Abstract Syntax Tree (AST) created by pg_query.

Example

let ast = context.statement().protobuf();
let nodes = ast.nodes();

pub fn read_only(&self) -> bool

Returns true if the database cluster doesn’t have a primary database and can only serve read queries.

Example

let read_only = context.read_only();

if read_only {
    println!("Database cluster doesn't have a primary, only replicas.");
}

pub fn has_replicas(&self) -> bool

Returns true if the database cluster has replica databases.

Example

let has_replicas = context.has_replicas();

if has_replicas {
    println!("Database cluster can load balance read queries.")
}

pub fn has_primary(&self) -> bool

Returns true if the database cluster has a primary database and can serve write queries.

Example

let has_primary = context.has_primary();

if has_primary {
    println!("Database cluster can serve write queries.");
}

pub fn shards(&self) -> usize

Returns the number of shards in the database cluster.

Example

let shards = context.shards();

if shards > 1 {
    println!("Plugin should consider which shard to route the query to.");
}

pub fn sharded(&self) -> bool

Returns true if the database cluster has more than one shard.

Example

let sharded = context.sharded();
let shards = context.shards();

if sharded {
    assert!(shards > 1);
} else {
    assert_eq!(shards, 1);
}

pub fn write_override(&self) -> bool

Returns true if PgDog strongly believes the statement should be sent to a primary. This indicates that the statement is not a SELECT (e.g. UPDATE, DELETE, etc.), or a SELECT that is very likely to write data to the database, e.g.:

WITH users AS (
    INSERT INTO users VALUES (1, '[email protected]') RETURNING *
)
SELECT * FROM users;

Example

if context.write_override() {
    println!("We should really send this query to the primary.");
}

pub fn parameters(&self) -> Parameters

Returns a list of parameters bound on the statement. If using the simple protocol, this is going to be empty and parameters will be in the actual query text.

Example

use pgdog_plugin::prelude::*;
let params = context.parameters();
if let Some(param) = params.get(0) {
    let value = param.decode(params.parameter_format(0));
    println!("{:?}", value);
}

impl Context

pub unsafe fn doc_test() -> Context

Used for doc tests only. Do not use.

Safety

Not safe, don’t use. We use it for doc tests only.

Trait Implementations

impl From<PdRouterContext> for Context

fn from(value: PdRouterContext) -> Self

Converts to this type from the input type.