Struct SchemaCache 

pub struct SchemaCache {
    pub tables: TablesMap,
    pub relationships: RelationshipsMap,
    pub routines: RoutineMap,
    pub timezones: HashSet<String>,
    pub pg_version: i32,
    pub media_handlers: MediaHandlerMap,
    pub representations: HashMap<(String, String), String>,
}

Cached PostgreSQL schema metadata.

Serializable, so a host that cannot afford to load it on every cold start – a Cloudflare Worker – can keep a copy elsewhere. The maps keyed by more than a string are written as lists of [key, value] pairs, since a JSON object can only be keyed by a string.

Fields

tables: TablesMap

Tables and views by qualified identifier.

relationships: RelationshipsMap

Relationships between tables.

routines: RoutineMap

Stored functions/procedures.

timezones: HashSet<String>

Valid timezone names.

pg_version: i32

PostgreSQL version.

media_handlers: MediaHandlerMap

User-defined renderers for media types, by (schema, media type).

representations: HashMap<(String, String), String>

Casts between a domain and json/text, by (source, target) type.

A schema uses these to decide how a value of one of its domains is written on the wire and how one written by a client is read back.

Implementations

impl SchemaCache

pub async fn load(pool: &PgPool, schemas: &[String]) -> Result<Self>

Load schema cache from the database.

pub async fn load_with_search_path( pool: &PgPool, schemas: &[String], extra_search_path: &[String], ) -> Result<Self>

Load the cache, resolving functions along extra_search_path as well. See Self::load_with_search_path_from.

pub async fn load_from<D: Db>(db: &D, schemas: &[String]) -> Result<Self>

Load schema cache through any Db – a sqlx pool, or the socket driver a Cloudflare Worker uses.

pub async fn load_with_search_path_from<D: Db>( db: &D, schemas: &[String], extra_search_path: &[String], ) -> Result<Self>

Load the cache, resolving functions along extra_search_path as well.

A computed column’s function is reached the way the database reaches it, which is along the search path – so it may live in a schema the API does not expose. The table it reads must still be exposed.

Every catalog query runs on one transaction, through the same interface a request uses, so any driver that can serve requests can load the cache.

pub fn get_table(&self, qi: &QualifiedIdentifier) -> Option<&Table>

Get a table by qualified identifier.

pub fn require_table(&self, qi: &QualifiedIdentifier) -> Result<&Table>

Get a table, returning an error if not found.

pub fn get_relationships( &self, qi: &QualifiedIdentifier, schema: &str, ) -> Option<&Vec<Relationship>>

Get relationships for a table.

pub fn get_routines(&self, qi: &QualifiedIdentifier) -> Option<&Vec<Routine>>

Get a routine by qualified identifier.

pub fn is_valid_timezone(&self, tz: &str) -> bool

Check if a timezone is valid.

pub fn summary(&self) -> String

Get a summary of the cached schema.

pub fn routine_returned_table(&self, qi: &QualifiedIdentifier) -> Option<&Table>

The table whose rows a function returns, if it returns rows of one.

This is what makes a function behave like a table for everything after the call: its result can be selected from, filtered, ordered, paged and embedded on, all of which need a table to resolve columns against.

format_type may or may not qualify the name, depending on the search path it was rendered against, so both spellings are tried – and an unqualified one is looked for in the function’s own schema.

pub fn returned_table(&self, routine: &Routine) -> Option<&Table>

The same, for a routine already chosen.

A name may carry several signatures returning different things, so which overload was selected decides which table the result is shaped by – and only the caller knows that.

pub fn representation(&self, pg_type: &str, target: &str) -> Option<&str>

The function that renders a value of pg_type as target, if the schema declared one.

pub fn media_handler<'a>( &'a self, schema: &str, media_type: &'a str, table: &QualifiedIdentifier, default_select: bool, ) -> Option<(&'a MediaHandler, &'a str)>

Find a user-defined renderer for a media type on a given table.

A handler declared for the table itself wins over one taking anyelement, which is the schema-wide fallback. A schema may also declare a handler for */*, which renders whatever was asked for. What comes back is the handler and the media type the response should be labelled with – not always the one requested, since */* is not a type a response can claim to be. PostgREST resolves it to application/octet-stream, which is what a body of unnamed bytes is, and this follows it. A handler declared for one table renders that table as it is, so it only applies to a request that asked for the table as it is: ?select=id is a different shape from the one the handler was written against, and running it over that shape produces either nonsense or an error. PostgREST guards both table-specific lookups on the selection being the default one, and default_select is that guard.

pub fn relationship_not_found( &self, from: &QualifiedIdentifier, to_name: &str, hint: Option<&str>, schema: &str, ) -> Error

The error to report when no relationship connects two resources.

Built here rather than at the call site because the suggestion needs the relationships the origin actually has, which is what the client most likely meant to name.

pub fn similar_routine(&self, qi: &QualifiedIdentifier) -> Option<String>

The exposed function whose name is closest to one that does not exist.

Only when the name itself is wrong: an existing name whose arguments do not match is a different mistake, and the overloads answer it better.

pub fn find_relationship( &self, from: &QualifiedIdentifier, to_name: &str, hint: Option<&str>, schema: &str, ) -> Result<Option<&Relationship>>

Find a relationship between two tables by name.

hint is the !hint of person_detail!message_sender_fkey(name), which names the relationship when the two resources are connected by more than one.

Returns Ok(None) when nothing matches, and an error when several do and no hint told them apart – picking one arbitrarily would answer a question the client did not ask.

Trait Implementations

impl Clone for SchemaCache

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SchemaCache

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SchemaCache

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for SchemaCache

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.