Add postgate_helpers schema with tenant utility functions

- Add list_tables() and describe_table() helper functions
- Allow postgate_helpers.* qualified names in SQL parser
- Add migration 002_helper_functions.sql
- Bump version to 0.1.3

Author: max-lt

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "postgate"
-version = "0.1.2"
+version = "0.1.3"
 edition = "2024"
 default-run = "postgate"
 description = "Secure HTTP proxy for PostgreSQL with SQL validation and multi-tenant support"

Cargo.toml

@@ -270,6 +270,31 @@ SELECT * FROM public.users
 
 -- ❌ Blocked: System table access
 SELECT * FROM pg_tables
+
+-- ✅ Allowed: postgate_helpers functions
+SELECT * FROM postgate_helpers.list_tables()
+```
+
+## Helper Functions
+
+The `postgate_helpers` schema provides utility functions accessible to all tenants:
+
+### postgate_helpers.list_tables()
+
+List all tables in the current tenant's schema with row counts.
+
+```sql
+SELECT * FROM postgate_helpers.list_tables();
+-- Returns: { table_name: "users", row_count: 42 }, ...
+```
+
+### postgate_helpers.describe_table(name)
+
+Describe columns of a table in the current tenant's schema.
+
+```sql
+SELECT * FROM postgate_helpers.describe_table('users');
+-- Returns: { column_name, data_type, is_nullable, column_default, is_primary_key }
 ```
 
 ## Multi-Tenant Isolation

README.md

@@ -0,0 +1,121 @@
+-- ============================================================================
+-- POSTGATE HELPER FUNCTIONS
+-- ============================================================================
+--
+-- Utility functions accessible to all tenants via qualified names:
+--   SELECT * FROM postgate_helpers.list_tables();
+--   SELECT * FROM postgate_helpers.describe_table('users');
+--
+
+-- ============================================================================
+-- SCHEMA
+-- ============================================================================
+
+CREATE SCHEMA IF NOT EXISTS postgate_helpers;
+
+COMMENT ON SCHEMA postgate_helpers IS 'Utility functions for tenants (accessible via PostGate)';
+
+-- ============================================================================
+-- FUNCTION: list_tables()
+-- ============================================================================
+-- Lists all tables in the current tenant's schema with row counts.
+--
+-- Example:
+--   SELECT * FROM postgate_helpers.list_tables();
+
+CREATE OR REPLACE FUNCTION postgate_helpers.list_tables()
+RETURNS TABLE(table_name text, row_count bigint)
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
+DECLARE
+    v_schema text;
+    tbl record;
+    cnt bigint;
+BEGIN
+    v_schema := current_schema();
+
+    -- Prevent access to system schemas
+    IF v_schema IN ('public', 'postgate_helpers') THEN
+        RAISE EXCEPTION 'Cannot list tables in system schemas';
+    END IF;
+
+    FOR tbl IN
+        SELECT tablename
+        FROM pg_tables
+        WHERE schemaname = v_schema
+        ORDER BY tablename
+    LOOP
+        EXECUTE format('SELECT count(*) FROM %I.%I', v_schema, tbl.tablename) INTO cnt;
+        table_name := tbl.tablename;
+        row_count := cnt;
+        RETURN NEXT;
+    END LOOP;
+END;
+$$;
+
+COMMENT ON FUNCTION postgate_helpers.list_tables() IS 'List all tables in the current tenant schema with row counts';
+
+-- ============================================================================
+-- FUNCTION: describe_table(table_name)
+-- ============================================================================
+-- Describes columns of a table in the current tenant's schema.
+--
+-- Example:
+--   SELECT * FROM postgate_helpers.describe_table('users');
+
+CREATE OR REPLACE FUNCTION postgate_helpers.describe_table(p_table_name text)
+RETURNS TABLE(
+    column_name text,
+    data_type text,
+    is_nullable boolean,
+    column_default text,
+    is_primary_key boolean
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
+DECLARE
+    v_schema text;
+BEGIN
+    v_schema := current_schema();
+
+    -- Prevent access to system schemas
+    IF v_schema IN ('public', 'postgate_helpers') THEN
+        RAISE EXCEPTION 'Cannot describe tables in system schemas';
+    END IF;
+
+    RETURN QUERY
+    SELECT
+        c.column_name::text,
+        c.data_type::text,
+        (c.is_nullable = 'YES')::boolean,
+        c.column_default::text,
+        COALESCE(
+            (SELECT true
+             FROM information_schema.table_constraints tc
+             JOIN information_schema.key_column_usage kcu
+                ON tc.constraint_name = kcu.constraint_name
+                AND tc.table_schema = kcu.table_schema
+             WHERE tc.constraint_type = 'PRIMARY KEY'
+                AND tc.table_schema = v_schema
+                AND tc.table_name = p_table_name
+                AND kcu.column_name = c.column_name
+             LIMIT 1),
+            false
+        )::boolean
+    FROM information_schema.columns c
+    WHERE c.table_schema = v_schema
+        AND c.table_name = p_table_name
+    ORDER BY c.ordinal_position;
+END;
+$$;
+
+COMMENT ON FUNCTION postgate_helpers.describe_table(text) IS 'Describe columns of a table in the current tenant schema';
+
+-- ============================================================================
+-- PERMISSIONS
+-- ============================================================================
+
+GRANT USAGE ON SCHEMA postgate_helpers TO PUBLIC;
+GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA postgate_helpers TO PUBLIC;

migrations/002_helper_functions.sql

@@ -157,9 +157,12 @@ fn validate_table_refs(table_refs: &[TableRef]) -> Result<HashSet<String>, Parse
 
     for table_ref in table_refs {
         // Block qualified names (schema.table)
+        // Exception: postgate_helpers contains utility functions (list_tables, describe_table)
         if let Some(schema) = &table_ref.schema {
-            let full_name = format!("{}.{}", schema, table_ref.name);
-            return Err(ParseError::QualifiedTableName(full_name));
+            if schema != "postgate_helpers" {
+                let full_name = format!("{}.{}", schema, table_ref.name);
+                return Err(ParseError::QualifiedTableName(full_name));
+            }
         }
 
         let name_lower = table_ref.name.to_lowercase();
@@ -267,4 +270,11 @@ mod tests {
         let result = parse_and_validate("SELECT * FROM information_schema.tables", &ops);
         assert!(matches!(result, Err(ParseError::QualifiedTableName(_))));
     }
+
+    #[test]
+    fn test_postgate_helpers_allowed() {
+        let ops = all_operations();
+        let result = parse_and_validate("SELECT * FROM postgate_helpers.list_tables()", &ops);
+        assert!(result.is_ok());
+    }
 }