From 7ba560939f952698b4908bbf7784e9bd405ce572 Mon Sep 17 00:00:00 2001
From: Steve Dignam <steve@dignam.xyz>
Date: Tue, 14 Apr 2026 22:49:55 -0400
Subject: [PATCH] linter: docs for require-table-schema-rule

---
 .../src/rules/require_table_schema.rs         | 19 +++++-----
 docs/docs/require-table-schema.md             | 38 +++++++++++++++++++
 docs/sidebars.js                              |  1 +
 docs/src/pages/index.js                       |  5 +++
 4 files changed, 53 insertions(+), 10 deletions(-)
 create mode 100644 docs/docs/require-table-schema.md

diff --git a/crates/squawk_linter/src/rules/require_table_schema.rs b/crates/squawk_linter/src/rules/require_table_schema.rs
index 39add30a..79b1ffbb 100644
--- a/crates/squawk_linter/src/rules/require_table_schema.rs
+++ b/crates/squawk_linter/src/rules/require_table_schema.rs
@@ -22,21 +22,20 @@ pub(crate) fn require_table_schema(ctx: &mut Linter, parse: &Parse<SourceFile>)
             ast::Stmt::DropTable(drop_table) => {
                 check_path(ctx, drop_table.path(), drop_table.syntax());
             }
-            _ => {}
+            _ => (),
         }
     }
 }
 
 fn check_path(ctx: &mut Linter, path: Option<ast::Path>, syntax: &squawk_syntax::SyntaxNode) {
-    if let Some(path) = path {
-        if path.qualifier().is_none() {
-            ctx.report(Violation::for_node(
-                Rule::RequireTableSchema,
-                "Table name is not schema-qualified. Use schema.table (e.g., public.my_table)."
-                    .into(),
-                syntax,
-            ));
-        }
+    if let Some(path) = path
+        && path.qualifier().is_none()
+    {
+        ctx.report(Violation::for_node(
+            Rule::RequireTableSchema,
+            "Table name is not schema-qualified. Use schema.table (e.g., public.my_table).".into(),
+            syntax,
+        ));
     }
 }
 
diff --git a/docs/docs/require-table-schema.md b/docs/docs/require-table-schema.md
new file mode 100644
index 00000000..143ee66d
--- /dev/null
+++ b/docs/docs/require-table-schema.md
@@ -0,0 +1,38 @@
+---
+id: require-table-schema
+title: require-table-schema
+---
+
+## problem
+
+Without an explicit schema, Postgres uses the `search_path` when looking up tables and similar objects. This can result in ambiguity as to what specific table you're acting on.
+
+```sql
+-- bad
+create table posts(id bigint);
+
+alter table posts add column name text;
+
+drop table posts;
+
+create table posts as select 1;
+```
+
+## solution
+
+Specify the schema (i.e., `public`) alongside the table names in your DDL.
+
+```sql
+-- good
+create table public.posts(id bigint);
+
+alter table public.posts add column name text;
+
+drop table public.posts;
+
+create table public.posts as select 1;
+```
+
+## links
+
+- https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PATH
diff --git a/docs/sidebars.js b/docs/sidebars.js
index c4cd1592..0ab3b93b 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -35,6 +35,7 @@ module.exports = {
       "require-timeout-settings",
       "ban-uncommitted-transaction",
       "require-enum-value-ordering",
+      "require-table-schema",
       // xtask:new-rule:error-name
     ],
   },
diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js
index b9b9b5b7..bd7aa4ef 100644
--- a/docs/src/pages/index.js
+++ b/docs/src/pages/index.js
@@ -207,6 +207,11 @@ const rules = [
     tags: ["schema"],
     description: "Require BEFORE or AFTER when adding enum values",
   },
+  {
+    name: "require-table-schema",
+    tags: ["schema"],
+    description: "Require explicit schema in table DDL to avoid ambiguity.",
+  },
   // xtask:new-rule:rule-doc-meta
 ]