Trait mz_sql::catalog::SessionCatalog

pub trait SessionCatalog:
    Debug
    + ExprHumanizer
    + Send
    + Sync
    + ConnectionResolver {
    // Required methods
    fn active_role_id(&self) -> &RoleId;
    fn active_database(&self) -> Option<&DatabaseId>;
    fn active_cluster(&self) -> &str;
    fn search_path(&self) -> &[(ResolvedDatabaseSpecifier, SchemaSpecifier)];
    fn get_prepared_statement_desc(&self, name: &str) -> Option<&StatementDesc>;
    fn resolve_database(
        &self,
        database_name: &str,
    ) -> Result<&dyn CatalogDatabase, CatalogError>;
    fn get_database(&self, id: &DatabaseId) -> &dyn CatalogDatabase;
    fn get_databases(&self) -> Vec<&dyn CatalogDatabase>;
    fn resolve_schema(
        &self,
        database_name: Option<&str>,
        schema_name: &str,
    ) -> Result<&dyn CatalogSchema, CatalogError>;
    fn resolve_schema_in_database(
        &self,
        database_spec: &ResolvedDatabaseSpecifier,
        schema_name: &str,
    ) -> Result<&dyn CatalogSchema, CatalogError>;
    fn get_schema(
        &self,
        database_spec: &ResolvedDatabaseSpecifier,
        schema_spec: &SchemaSpecifier,
    ) -> &dyn CatalogSchema;
    fn get_schemas(&self) -> Vec<&dyn CatalogSchema>;
    fn get_mz_internal_schema_id(&self) -> SchemaId;
    fn get_mz_unsafe_schema_id(&self) -> SchemaId;
    fn is_system_schema_specifier(&self, schema: SchemaSpecifier) -> bool;
    fn resolve_role(
        &self,
        role_name: &str,
    ) -> Result<&dyn CatalogRole, CatalogError>;
    fn resolve_network_policy(
        &self,
        network_policy_name: &str,
    ) -> Result<&dyn CatalogNetworkPolicy, CatalogError>;
    fn try_get_role(&self, id: &RoleId) -> Option<&dyn CatalogRole>;
    fn get_role(&self, id: &RoleId) -> &dyn CatalogRole;
    fn get_roles(&self) -> Vec<&dyn CatalogRole>;
    fn mz_system_role_id(&self) -> RoleId;
    fn collect_role_membership(&self, id: &RoleId) -> BTreeSet<RoleId>;
    fn get_network_policy(
        &self,
        id: &NetworkPolicyId,
    ) -> &dyn CatalogNetworkPolicy;
    fn get_network_policies(&self) -> Vec<&dyn CatalogNetworkPolicy>;
    fn resolve_cluster<'a, 'b>(
        &'a self,
        cluster_name: Option<&'b str>,
    ) -> Result<&dyn CatalogCluster<'a>, CatalogError>;
    fn resolve_cluster_replica<'a, 'b>(
        &'a self,
        cluster_replica_name: &'b QualifiedReplica,
    ) -> Result<&dyn CatalogClusterReplica<'a>, CatalogError>;
    fn resolve_item(
        &self,
        item_name: &PartialItemName,
    ) -> Result<&dyn CatalogItem, CatalogError>;
    fn resolve_function(
        &self,
        item_name: &PartialItemName,
    ) -> Result<&dyn CatalogItem, CatalogError>;
    fn resolve_type(
        &self,
        item_name: &PartialItemName,
    ) -> Result<&dyn CatalogItem, CatalogError>;
    fn get_system_type(&self, name: &str) -> &dyn CatalogItem;
    fn try_get_item(&self, id: &CatalogItemId) -> Option<&dyn CatalogItem>;
    fn try_get_item_by_global_id(
        &self,
        id: &GlobalId,
    ) -> Option<Box<dyn CatalogCollectionItem>>;
    fn get_item(&self, id: &CatalogItemId) -> &dyn CatalogItem;
    fn get_item_by_global_id(
        &self,
        id: &GlobalId,
    ) -> Box<dyn CatalogCollectionItem>;
    fn get_items(&self) -> Vec<&dyn CatalogItem>;
    fn get_item_by_name(
        &self,
        name: &QualifiedItemName,
    ) -> Option<&dyn CatalogItem>;
    fn get_type_by_name(
        &self,
        name: &QualifiedItemName,
    ) -> Option<&dyn CatalogItem>;
    fn get_cluster(&self, id: ClusterId) -> &dyn CatalogCluster<'_>;
    fn get_clusters(&self) -> Vec<&dyn CatalogCluster<'_>>;
    fn get_cluster_replica(
        &self,
        cluster_id: ClusterId,
        replica_id: ReplicaId,
    ) -> &dyn CatalogClusterReplica<'_>;
    fn get_cluster_replicas(&self) -> Vec<&dyn CatalogClusterReplica<'_>>;
    fn get_system_privileges(&self) -> &PrivilegeMap;
    fn get_default_privileges(
        &self,
    ) -> Vec<(&DefaultPrivilegeObject, Vec<&DefaultPrivilegeAclItem>)>;
    fn find_available_name(&self, name: QualifiedItemName) -> QualifiedItemName;
    fn resolve_full_name(&self, name: &QualifiedItemName) -> FullItemName;
    fn resolve_full_schema_name(
        &self,
        name: &QualifiedSchemaName,
    ) -> FullSchemaName;
    fn resolve_item_id(&self, global_id: &GlobalId) -> CatalogItemId;
    fn resolve_global_id(
        &self,
        item_id: &CatalogItemId,
        version: RelationVersionSelector,
    ) -> GlobalId;
    fn config(&self) -> &CatalogConfig;
    fn now(&self) -> EpochMillis;
    fn aws_privatelink_availability_zones(&self) -> Option<BTreeSet<String>>;
    fn system_vars(&self) -> &SystemVars;
    fn system_vars_mut(&mut self) -> &mut SystemVars;
    fn get_owner_id(&self, id: &ObjectId) -> Option<RoleId>;
    fn get_privileges(&self, id: &SystemObjectId) -> Option<&PrivilegeMap>;
    fn object_dependents(&self, ids: &Vec<ObjectId>) -> Vec<ObjectId>;
    fn item_dependents(&self, id: CatalogItemId) -> Vec<ObjectId>;
    fn all_object_privileges(&self, object_type: SystemObjectType) -> AclMode;
    fn get_object_type(&self, object_id: &ObjectId) -> ObjectType;
    fn get_system_object_type(&self, id: &SystemObjectId) -> SystemObjectType;
    fn minimal_qualification(
        &self,
        qualified_name: &QualifiedItemName,
    ) -> PartialItemName;
    fn add_notice(&self, notice: PlanNotice);
    fn get_item_comments(
        &self,
        id: &CatalogItemId,
    ) -> Option<&BTreeMap<Option<usize>, String>>;
    fn is_cluster_size_cc(&self, size: &str) -> bool;

    // Provided methods
    fn active_database_name(&self) -> Option<&str> { ... }
    fn resolve_item_or_type(
        &self,
        name: &PartialItemName,
    ) -> Result<&dyn CatalogItem, CatalogError> { ... }
}

A catalog keeps track of SQL objects and session state available to the planner.

The sql crate is agnostic to any particular catalog implementation. This trait describes the required interface.

The SQL standard mandates a catalog hierarchy of exactly three layers. A catalog contains databases, databases contain schemas, and schemas contain catalog items, like sources, sinks, view, and indexes.

There are two classes of operations provided by a catalog:

• Resolution operations, like resolve_item. These fill in missing name components based upon connection defaults, e.g., resolving the partial name view42 to the fully-specified name materialize.public.view42.

• Lookup operations, like SessionCatalog::get_item. These retrieve metadata about a catalog entity based on a fully-specified name that is known to be valid (i.e., because the name was successfully resolved, or was constructed based on the output of a prior lookup operation). These functions panic if called with invalid input.

• Session management, such as managing variables’ states and adding notices to the session.

Required Methods

fn active_role_id(&self) -> &RoleId

Returns the id of the role that is issuing the query.

fn active_database(&self) -> Option<&DatabaseId>

Returns the database to use if one is not explicitly specified.

fn active_cluster(&self) -> &str

Returns the cluster to use if one is not explicitly specified.

fn search_path(&self) -> &[(ResolvedDatabaseSpecifier, SchemaSpecifier)]

Returns the resolved search paths for the current user. (Invalid search paths are skipped.)

fn get_prepared_statement_desc(&self, name: &str) -> Option<&StatementDesc>

Returns the descriptor of the named prepared statement on the session, or None if the prepared statement does not exist.

fn resolve_database( &self, database_name: &str, ) -> Result<&dyn CatalogDatabase, CatalogError>

Resolves the named database.

If database_name exists in the catalog, it returns a reference to the resolved database; otherwise it returns an error.

fn get_database(&self, id: &DatabaseId) -> &dyn CatalogDatabase

Gets a database by its ID.

Panics if id does not specify a valid database.

fn get_databases(&self) -> Vec<&dyn CatalogDatabase>

Gets all databases.

fn resolve_schema( &self, database_name: Option<&str>, schema_name: &str, ) -> Result<&dyn CatalogSchema, CatalogError>

Resolves a partially-specified schema name.

If the schema exists in the catalog, it returns a reference to the resolved schema; otherwise it returns an error.

fn resolve_schema_in_database( &self, database_spec: &ResolvedDatabaseSpecifier, schema_name: &str, ) -> Result<&dyn CatalogSchema, CatalogError>

Resolves a schema name within a specified database.

If the schema exists in the database, it returns a reference to the resolved schema; otherwise it returns an error.

fn get_schema( &self, database_spec: &ResolvedDatabaseSpecifier, schema_spec: &SchemaSpecifier, ) -> &dyn CatalogSchema

Gets a schema by its ID.

Panics if id does not specify a valid schema.

fn get_schemas(&self) -> Vec<&dyn CatalogSchema>

Gets all schemas.

fn get_mz_internal_schema_id(&self) -> SchemaId

Gets the mz_internal schema id.

fn get_mz_unsafe_schema_id(&self) -> SchemaId

Gets the mz_unsafe schema id.

fn is_system_schema_specifier(&self, schema: SchemaSpecifier) -> bool

Returns true if schema is an internal system schema, false otherwise

fn resolve_role( &self, role_name: &str, ) -> Result<&dyn CatalogRole, CatalogError>

Resolves the named role.

fn resolve_network_policy( &self, network_policy_name: &str, ) -> Result<&dyn CatalogNetworkPolicy, CatalogError>

Resolves the named network policy.

fn try_get_role(&self, id: &RoleId) -> Option<&dyn CatalogRole>

Gets a role by its ID.

fn get_role(&self, id: &RoleId) -> &dyn CatalogRole

Gets a role by its ID.

Panics if id does not specify a valid role.

fn get_roles(&self) -> Vec<&dyn CatalogRole>

Gets all roles.

fn mz_system_role_id(&self) -> RoleId

Gets the id of the mz_system role.

fn collect_role_membership(&self, id: &RoleId) -> BTreeSet<RoleId>

Collects all role IDs that id is transitively a member of.

fn get_network_policy(&self, id: &NetworkPolicyId) -> &dyn CatalogNetworkPolicy

Resolves the named cluster. Gets a network_policy by its ID.

Panics if id does not specify a valid role.

fn get_network_policies(&self) -> Vec<&dyn CatalogNetworkPolicy>

Gets all roles.

fn resolve_cluster<'a, 'b>( &'a self, cluster_name: Option<&'b str>, ) -> Result<&dyn CatalogCluster<'a>, CatalogError>

If the provided name is None, resolves the currently active cluster.

fn resolve_cluster_replica<'a, 'b>( &'a self, cluster_replica_name: &'b QualifiedReplica, ) -> Result<&dyn CatalogClusterReplica<'a>, CatalogError>

Resolves the named cluster replica.

fn resolve_item( &self, item_name: &PartialItemName, ) -> Result<&dyn CatalogItem, CatalogError>

Resolves a partially-specified item name, that is NOT a function or type. (For resolving functions or types, please use SessionCatalog::resolve_function or SessionCatalog::resolve_type.)

If the partial name has a database component, it searches only the specified database; otherwise, it searches the active database. If the partial name has a schema component, it searches only the specified schema; otherwise, it searches a default set of schemas within the selected database. It returns an error if none of the searched schemas contain an item whose name matches the item component of the partial name.

Note that it is not an error if the named item appears in more than one of the search schemas. The catalog implementation must choose one.

fn resolve_function( &self, item_name: &PartialItemName, ) -> Result<&dyn CatalogItem, CatalogError>

Performs the same operation as SessionCatalog::resolve_item but for functions within the catalog.

fn resolve_type( &self, item_name: &PartialItemName, ) -> Result<&dyn CatalogItem, CatalogError>

Performs the same operation as SessionCatalog::resolve_item but for types within the catalog.

fn get_system_type(&self, name: &str) -> &dyn CatalogItem

Gets a type named name from exactly one of the system schemas.

Panics

• If name is not an entry in any system schema
• If more than one system schema has an entry named name.

fn try_get_item(&self, id: &CatalogItemId) -> Option<&dyn CatalogItem>

Gets an item by its ID.

fn try_get_item_by_global_id( &self, id: &GlobalId, ) -> Option<Box<dyn CatalogCollectionItem>>

Tries to get an item by a GlobalId, returning None if the GlobalId does not exist.

Note: A single Catalog Item can have multiple GlobalIds associated with it.

fn get_item(&self, id: &CatalogItemId) -> &dyn CatalogItem

Gets an item by its ID.

Panics if id does not specify a valid item.

fn get_item_by_global_id(&self, id: &GlobalId) -> Box<dyn CatalogCollectionItem>

Gets an item by a GlobalId.

Panics if id does not specify a valid item.

Note: A single Catalog Item can have multiple GlobalIds associated with it.

fn get_items(&self) -> Vec<&dyn CatalogItem>

Gets all items.

fn get_item_by_name(&self, name: &QualifiedItemName) -> Option<&dyn CatalogItem>

Looks up an item by its name.

fn get_type_by_name(&self, name: &QualifiedItemName) -> Option<&dyn CatalogItem>

Looks up a type by its name.

fn get_cluster(&self, id: ClusterId) -> &dyn CatalogCluster<'_>

Gets a cluster by ID.

fn get_clusters(&self) -> Vec<&dyn CatalogCluster<'_>>

Gets all clusters.

fn get_cluster_replica( &self, cluster_id: ClusterId, replica_id: ReplicaId, ) -> &dyn CatalogClusterReplica<'_>

Gets a cluster replica by ID.

fn get_cluster_replicas(&self) -> Vec<&dyn CatalogClusterReplica<'_>>

Gets all cluster replicas.

fn get_system_privileges(&self) -> &PrivilegeMap

Gets all system privileges.

fn get_default_privileges( &self, ) -> Vec<(&DefaultPrivilegeObject, Vec<&DefaultPrivilegeAclItem>)>

Gets all default privileges.

fn find_available_name(&self, name: QualifiedItemName) -> QualifiedItemName

Finds a name like name that is not already in use.

If name itself is available, it is returned unchanged.

fn resolve_full_name(&self, name: &QualifiedItemName) -> FullItemName

Returns a fully qualified human readable name from fully qualified non-human readable name

fn resolve_full_schema_name(&self, name: &QualifiedSchemaName) -> FullSchemaName

Returns a fully qualified human readable schema name from fully qualified non-human readable schema name

fn resolve_item_id(&self, global_id: &GlobalId) -> CatalogItemId

Returns the CatalogItemId for from a GlobalId.

fn resolve_global_id( &self, item_id: &CatalogItemId, version: RelationVersionSelector, ) -> GlobalId

Returns the GlobalId for the specificed Catalog Item, at the specified version.

fn config(&self) -> &CatalogConfig

Returns the configuration of the catalog.

fn now(&self) -> EpochMillis

Returns the number of milliseconds since the system epoch. For normal use this means the Unix epoch. This can safely be mocked in tests and start at 0.

fn aws_privatelink_availability_zones(&self) -> Option<BTreeSet<String>>

Returns the set of supported AWS PrivateLink availability zone ids.

fn system_vars(&self) -> &SystemVars

Returns system vars

fn system_vars_mut(&mut self) -> &mut SystemVars

Returns mutable system vars

Clients should use this this method carefully, as changes to the backing state here are not guarateed to be persisted. The motivating use case for this method was ensuring that features are temporary turned on so catalog rehydration does not break due to unsupported SQL syntax.

fn get_owner_id(&self, id: &ObjectId) -> Option<RoleId>

Returns the RoleId of the owner of an object by its ID.

fn get_privileges(&self, id: &SystemObjectId) -> Option<&PrivilegeMap>

Returns the PrivilegeMap of the object.

fn object_dependents(&self, ids: &Vec<ObjectId>) -> Vec<ObjectId>

Returns all the IDs of all objects that depend on ids, including ids themselves.

The order is guaranteed to be in reverse dependency order, i.e. the leafs will appear earlier in the list than the roots. This is particularly userful for the order to drop objects.

fn item_dependents(&self, id: CatalogItemId) -> Vec<ObjectId>

Returns all the IDs of all objects that depend on id, including id themselves.

The order is guaranteed to be in reverse dependency order, i.e. the leafs will appear earlier in the list than id. This is particularly userful for the order to drop objects.

fn all_object_privileges(&self, object_type: SystemObjectType) -> AclMode

Returns all possible privileges associated with an object type.

fn get_object_type(&self, object_id: &ObjectId) -> ObjectType

Returns the object type of object_id.

fn get_system_object_type(&self, id: &SystemObjectId) -> SystemObjectType

Returns the system object type of id.

fn minimal_qualification( &self, qualified_name: &QualifiedItemName, ) -> PartialItemName

Returns the minimal qualification required to unambiguously specify qualified_name.

fn add_notice(&self, notice: PlanNotice)

Adds a PlanNotice that will be displayed to the user if the plan successfully executes.

fn get_item_comments( &self, id: &CatalogItemId, ) -> Option<&BTreeMap<Option<usize>, String>>

Returns the associated comments for the given id

fn is_cluster_size_cc(&self, size: &str) -> bool

Reports whether the specified cluster size is a modern “cc” size rather than a legacy T-shirt size.

Provided Methods

fn active_database_name(&self) -> Option<&str>

Returns the database to use if one is not explicitly specified.

fn resolve_item_or_type( &self, name: &PartialItemName, ) -> Result<&dyn CatalogItem, CatalogError>

Resolves name to a type or item, preferring the type if both exist.

Implementors