feat(hover): hover on schemas (#514)

<img width="555" height="380" alt="Screenshot 2025-09-13 at 08 37 11"
src="https://github.com/user-attachments/assets/ad449ec2-6bac-401d-86c5-eeb22360aeaf"
/>

Author: juleswritescode

.sqlx/query-36862f7f9d2d1c50ba253b28a7648e76ff7e255960a4ce5466674ff35a97b151.json

@@ -3,6 +3,7 @@ use crate::{contextual_priority::ContextualPriority, to_markdown::ToHoverMarkdow
 mod column;
 mod function;
 mod role;
+mod schema;
 mod table;
 
 mod test_helper;
@@ -14,6 +15,13 @@ pub enum Hoverable<'a> {
     Column(&'a pgt_schema_cache::Column),
     Function(&'a pgt_schema_cache::Function),
     Role(&'a pgt_schema_cache::Role),
+    Schema(&'a pgt_schema_cache::Schema),
+}
+
+impl<'a> From<&'a pgt_schema_cache::Schema> for Hoverable<'a> {
+    fn from(value: &'a pgt_schema_cache::Schema) -> Self {
+        Hoverable::Schema(value)
+    }
 }
 
 impl<'a> From<&'a pgt_schema_cache::Table> for Hoverable<'a> {
@@ -47,6 +55,7 @@ impl ContextualPriority for Hoverable<'_> {
             Hoverable::Column(column) => column.relevance_score(ctx),
             Hoverable::Function(function) => function.relevance_score(ctx),
             Hoverable::Role(role) => role.relevance_score(ctx),
+            Hoverable::Schema(schema) => schema.relevance_score(ctx),
         }
     }
 }
@@ -58,6 +67,7 @@ impl ToHoverMarkdown for Hoverable<'_> {
             Hoverable::Column(column) => ToHoverMarkdown::hover_headline(*column, writer),
             Hoverable::Function(function) => ToHoverMarkdown::hover_headline(*function, writer),
             Hoverable::Role(role) => ToHoverMarkdown::hover_headline(*role, writer),
+            Hoverable::Schema(schema) => ToHoverMarkdown::hover_headline(*schema, writer),
         }
     }
 
@@ -67,6 +77,7 @@ impl ToHoverMarkdown for Hoverable<'_> {
             Hoverable::Column(column) => ToHoverMarkdown::hover_body(*column, writer),
             Hoverable::Function(function) => ToHoverMarkdown::hover_body(*function, writer),
             Hoverable::Role(role) => ToHoverMarkdown::hover_body(*role, writer),
+            Hoverable::Schema(schema) => ToHoverMarkdown::hover_body(*schema, writer),
         }
     }
 
@@ -76,6 +87,7 @@ impl ToHoverMarkdown for Hoverable<'_> {
             Hoverable::Column(column) => ToHoverMarkdown::hover_footer(*column, writer),
             Hoverable::Function(function) => ToHoverMarkdown::hover_footer(*function, writer),
             Hoverable::Role(role) => ToHoverMarkdown::hover_footer(*role, writer),
+            Hoverable::Schema(schema) => ToHoverMarkdown::hover_footer(*schema, writer),
         }
     }
 
@@ -85,6 +97,7 @@ impl ToHoverMarkdown for Hoverable<'_> {
             Hoverable::Column(column) => column.body_markdown_type(),
             Hoverable::Function(function) => function.body_markdown_type(),
             Hoverable::Role(role) => role.body_markdown_type(),
+            Hoverable::Schema(schema) => schema.body_markdown_type(),
         }
     }
 
@@ -94,6 +107,7 @@ impl ToHoverMarkdown for Hoverable<'_> {
             Hoverable::Column(column) => column.footer_markdown_type(),
             Hoverable::Function(function) => function.footer_markdown_type(),
             Hoverable::Role(role) => role.footer_markdown_type(),
+            Hoverable::Schema(schema) => schema.footer_markdown_type(),
         }
     }
 }

.sqlx/query-c775d3eaa6e95504de411dd5c2433a1121d69c7dca3c0e5e202835d9fefaa7cc.json

@@ -0,0 +1,65 @@
+use std::fmt::Write;
+
+use pgt_schema_cache::Schema;
+use pgt_treesitter::TreesitterContext;
+
+use crate::{contextual_priority::ContextualPriority, to_markdown::ToHoverMarkdown};
+
+impl ToHoverMarkdown for Schema {
+    fn hover_headline<W: Write>(&self, writer: &mut W) -> Result<(), std::fmt::Error> {
+        write!(writer, "`{}` - owned by {}", self.name, self.owner)?;
+
+        Ok(())
+    }
+
+    fn hover_body<W: Write>(&self, writer: &mut W) -> Result<bool, std::fmt::Error> {
+        if let Some(comment) = &self.comment {
+            write!(writer, "Comment: '{}'", comment)?;
+            writeln!(writer)?;
+            writeln!(writer)?;
+        }
+
+        if !self.allowed_creators.is_empty() {
+            write!(writer, "CREATE privileges:")?;
+            writeln!(writer)?;
+
+            for creator in &self.allowed_creators {
+                write!(writer, "- {}", creator)?;
+                writeln!(writer)?;
+            }
+
+            writeln!(writer)?;
+        }
+
+        if !self.allowed_users.is_empty() {
+            write!(writer, "USAGE privileges:")?;
+            writeln!(writer)?;
+
+            for user in &self.allowed_users {
+                write!(writer, "- {}", user)?;
+                writeln!(writer)?;
+            }
+
+            writeln!(writer)?;
+        }
+
+        Ok(true)
+    }
+
+    fn hover_footer<W: Write>(&self, writer: &mut W) -> Result<bool, std::fmt::Error> {
+        writeln!(writer)?;
+        write!(
+            writer,
+            "~{}, {} tables, {} views, {} functions",
+            self.total_size, self.table_count, self.view_count, self.function_count,
+        )?;
+        Ok(true)
+    }
+}
+
+impl ContextualPriority for Schema {
+    // there are no schemas with duplicate names.
+    fn relevance_score(&self, _ctx: &TreesitterContext) -> f32 {
+        0.0
+    }
+}

crates/pgt_hover/src/hoverables/mod.rs

@@ -26,6 +26,11 @@ impl HoveredNode {
 
         match under_cursor.kind() {
             "identifier" if ctx.matches_ancestor_history(&["relation", "object_reference"]) => {
+                let num_sibs = ctx.num_siblings();
+                if ctx.node_under_cursor_is_nth_child(1) && num_sibs > 0 {
+                    return Some(HoveredNode::Schema(NodeIdentification::Name(node_content)));
+                }
+
                 if let Some(schema) = ctx.schema_or_alias_name.as_ref() {
                     Some(HoveredNode::Table(NodeIdentification::SchemaAndName((
                         schema.clone(),
@@ -60,6 +65,7 @@ impl HoveredNode {
             "identifier" if ctx.matches_ancestor_history(&["alter_role"]) => {
                 Some(HoveredNode::Role(NodeIdentification::Name(node_content)))
             }
+
             "revoke_role" | "grant_role" | "policy_role" => {
                 Some(HoveredNode::Role(NodeIdentification::Name(node_content)))
             }

crates/pgt_hover/src/hoverables/schema.rs

@@ -107,6 +107,17 @@ pub fn on_hover(params: OnHoverParams) -> Vec<String> {
                 hovered_node::NodeIdentification::SchemaAndTableAndName(_) => vec![],
             },
 
+            HoveredNode::Schema(node_identification) => match node_identification {
+                hovered_node::NodeIdentification::Name(schema_name) => params
+                    .schema_cache
+                    .find_schema(&schema_name)
+                    .map(Hoverable::from)
+                    .map(|s| vec![s])
+                    .unwrap_or_default(),
+
+                _ => vec![],
+            },
+
             _ => todo!(),
         };
 

crates/pgt_hover/src/hovered_node.rs

@@ -443,6 +443,25 @@ async fn test_column_hover_with_quoted_column_name_with_table(test_db: PgPool) {
     .await;
 }
 
+#[sqlx::test(migrator = "pgt_test_utils::MIGRATIONS")]
+async fn hover_on_schemas(test_db: PgPool) {
+    let setup = r#"
+        create schema auth;
+
+        create table auth.users (
+            id serial primary key,
+            email varchar(255) not null
+        );
+    "#;
+
+    let query = format!(
+        r#"select * from au{}th.users;"#,
+        QueryWithCursorPosition::cursor_marker()
+    );
+
+    test_hover_at_cursor("hover_on_schemas", query, Some(setup), &test_db).await;
+}
+
 #[sqlx::test(migrator = "pgt_test_utils::MIGRATIONS")]
 async fn test_policy_table_hover(test_db: PgPool) {
     let setup = r#"

crates/pgt_hover/src/lib.rs

@@ -0,0 +1,20 @@
+---
+source: crates/pgt_hover/tests/hover_integration_tests.rs
+expression: snapshot
+---
+# Input
+```sql
+select * from auth.users;
+                ↑ hovered here
+```
+
+# Hover Results
+### `auth` - owned by postgres  
+```plain  
+  
+```  
+---    
+```plain  
+
+~16 kB, 1 tables, 0 views, 0 functions  
+```

crates/pgt_hover/tests/hover_integration_tests.rs

@@ -1,7 +1,35 @@
 select
   n.oid :: int8 as "id!",
   n.nspname as name,
-  u.rolname as "owner!"
+  u.rolname as "owner!",
+  obj_description(n.oid, 'pg_namespace') as "comment",
+
+  coalesce((
+    select array_agg(grantee::regrole::text)
+    from aclexplode(n.nspacl)
+    where privilege_type = 'USAGE'
+    and grantee::regrole::text <> ''
+    and grantee::regrole::text <> '-'
+  ), ARRAY[]::text[]) as "allowed_users!",
+
+  coalesce((
+    select array_agg(grantee::regrole::text)
+    from aclexplode(n.nspacl)
+    where privilege_type = 'CREATE'
+    and grantee::regrole::text <> ''
+    and grantee::regrole::text <> '-'
+  ), ARRAY[]::text[]) as "allowed_creators!",
+
+  (select count(*) from pg_class c where c.relnamespace = n.oid and c.relkind = 'r') as "table_count!",
+  (select count(*) from pg_class c where c.relnamespace = n.oid and c.relkind = 'v') as "view_count!",
+  (select count(*) from pg_proc p where p.pronamespace = n.oid) as "function_count!",
+
+  coalesce(
+  (select pg_size_pretty(sum(pg_total_relation_size(c.oid)))
+    from pg_class c 
+    where c.relnamespace = n.oid and c.relkind in ('r', 'i', 'm')),
+  '0 bytes'
+) as "total_size!"
 from
   pg_namespace n,
   pg_roles u

crates/pgt_hover/tests/snapshots/hover_on_schemas.snap

@@ -63,6 +63,11 @@ impl SchemaCache {
         })
     }
 
+    pub fn find_schema(&self, name: &str) -> Option<&Schema> {
+        let sanitized_name = Self::sanitize_identifier(name);
+        self.schemas.iter().find(|s| s.name == sanitized_name)
+    }
+
     pub fn find_tables(&self, name: &str, schema: Option<&str>) -> Vec<&Table> {
         let sanitized_name = Self::sanitize_identifier(name);
         self.tables