Connect to PostgreSQL or check connection status.

LEVEL: Server (connection management)

USE FOR: connecting, checking status, discovering databases. DO NOT USE FOR: health metrics (database_health), queries (execute_query).

ERROR RECOVERY:

• "connection refused": Check host/port, ensure PostgreSQL is running

• "authentication failed": Verify user/password credentials

• "database does not exist": List available databases with discover=True

• "SSL required": Add use_ssl=True or check server SSL config

• "certificate verify failed": Set ssl_verify=False for SSH tunnels

Examples: connect() - Check status connect(discover=True) - Find databases connect(url='postgresql://user:pass@localhost:5432/mydb')

Close the database connection and release pool resources.

LEVEL: Server (connection management)

USE FOR: ending session, cleanup, releasing connections. DO NOT USE FOR: checking status (use connect() or health_check).

Check connection health - pool stats, version, extensions.

LEVEL: Server (connection management)

USE FOR: connection status, pool health, "is database reachable?". DO NOT USE FOR: database metrics (database_health), query stats (query_performance).

Discover database schema - tables, columns, relationships, indexes.

LEVEL: Database (lists all schemas) or Schema (specific schema details)

USE FOR: listing tables, columns, foreign keys, ERD generation. DO NOT USE FOR: table data (execute_query), index health (maintenance_analysis).

ERROR RECOVERY:

• "schema not found": Call get_schema() without params to list all schemas

• "no tables found": Schema exists but is empty, verify with execute_query

• "not connected": Call connect() first or pass url parameter

PAGINATION: For large schemas (100+ tables), use limit/offset.

Examples: get_schema() - List all schemas get_schema(schema='public') - Tables in public get_schema(schema='public', limit=50, offset=50) - Page 2 get_schema(format='mermaid') - ERD diagram

Validate SQL syntax, detect anti-patterns, N+1, duplicates.

LEVEL: Query (SQL statement analysis - no DB connection needed for basic parsing)

USE FOR: SQL validation, N+1 detection, batch analysis. DO NOT USE FOR: running queries (execute_query), write impact (analyze_impact).

Examples: analyze_query(query='SELECT * FROM users') analyze_query(query='SELECT * FROM users', schema='shipment', include_explain=True)

Execute read-only SELECT queries. Writes are blocked.

LEVEL: Data (actual table data retrieval)

USE FOR: fetching data, counting rows, aggregations, joins. DO NOT USE FOR: INSERT/UPDATE/DELETE (use analyze_impact first).

ERROR RECOVERY:

• "relation does not exist": Verify table name with get_schema()

• "permission denied": User lacks SELECT privilege on table

• "query timeout": Reduce limit, add WHERE clause, or increase timeout_ms

• "not connected": Call connect() first

Examples: execute_query(query='SELECT * FROM users LIMIT 10') execute_query(query='SELECT COUNT(*) FROM orders')

Preview DELETE/UPDATE/DROP impact WITHOUT executing. Shows affected rows and rollback SQL.

LEVEL: Query (write operation preview - never executes)

USE FOR: previewing write impact, cascade effects, risk assessment. DO NOT USE FOR: reading data (execute_query), INSERT operations.

Examples: analyze_impact(query="DELETE FROM users WHERE status='inactive'", schema='public') analyze_impact(query="UPDATE orders SET status='cancelled' WHERE id=1", schema='shipment')

Optimize slow queries - EXPLAIN plan, table stats, index recommendations.

LEVEL: Query (single query optimization)

USE FOR: slow query diagnosis, CREATE INDEX suggestions, execution plans. DO NOT USE FOR: running queries (execute_query), syntax validation (analyze_query).

Examples: query_optimizer(query='SELECT * FROM orders WHERE customer_id=123', schema='shipment') query_optimizer(query='SELECT * FROM users', schema='public', run_explain=True)

Live database health - monitors active connections, sessions, locks, transactions.

LEVEL: Database (single database monitoring)

USE FOR: "is database healthy?", connection issues, lock problems, blocked queries, idle transactions, deadlock detection, XID wraparound check, "why is DB slow right now?". DO NOT USE FOR: index analysis (use maintenance_analysis), slow query history (use query_performance), table sizes/stats (use maintenance_analysis), query optimization (use query_optimizer), PostgreSQL server config (use configuration_review), replication (use replication_status). REAL-TIME: Shows current state of database activity.

ERROR RECOVERY:

• "not connected": Call connect() first or pass url parameter

• "permission denied on pg_stat_*": User needs pg_monitor role or superuser

• Use summary_only=True for large/busy databases to reduce payload size

INCLUDE OPTIONS:

• 'all': Everything (default)

• 'summary': Database stats, connections by state, checkpoint stats

• 'sessions': Session summary, by app/user/host, idle in transaction, active sessions

• 'locks': Lock summary, waiting locks, blocking tree, table lock hotspots, deadlocks

• 'transactions': XID wraparound status, transaction stats, long-running transactions

• 'queries': Active queries, long-running queries, wait events

• 'bloat': Tables needing vacuum

Examples: database_health() - Full health report database_health(include='locks') - Only lock information database_health(include='sessions') - Only session information database_health(include='transactions') - XID status and long transactions database_health(format='markdown') - Human-readable output

Table and index maintenance - analyzes indexes, vacuum status, table bloat, FK indexes.

LEVEL: Database ↔ Schema ↔ Table (multi-level tool)

• schema='all': Database level - maintenance status for ALL schemas

• schema='': Schema level - all tables in that schema (supports ANY schema name: 'sales', 'billing', 'auth', 'analytics', etc.)

• table='users': Table level - specific table analysis

REQUIRED: Specify schema explicitly - use 'all' for all schemas or a specific schema name.

USE FOR: finding unused indexes, duplicate indexes, tables needing vacuum, FK missing indexes, table sizes, TOAST analysis, autovacuum status, "which indexes should I drop?". DO NOT USE FOR: live connections/locks (use database_health), slow query history (use query_performance), specific query optimization (use query_optimizer), schema structure (use get_schema), partitioned tables (use partition_analysis). STATIC: Analyzes stored statistics, not real-time activity.

ERROR RECOVERY:

• "not connected": Call connect() first or pass url parameter

• "schema not found": Verify schema exists with get_schema()

• Large payload: Use summary_only=True or include='indexes' to filter results

• "permission denied": User needs read access to pg_catalog views

INCLUDE OPTIONS:

• 'all': Everything (default)

• 'indexes': All indexes, unused indexes, duplicate indexes, tables needing indexes, largest indexes

• 'tables': Table statistics, hot tables (most active)

• 'vacuum': Bloated tables, never vacuumed, tables needing freeze, autovacuum settings

• 'fk_indexes': Foreign keys missing supporting indexes

• 'toast': TOAST storage analysis (large object storage)

Examples: maintenance_analysis() - All tables in public schema (default) maintenance_analysis(schema='all') - All schemas (database-wide) maintenance_analysis(schema='billing') - All tables in billing schema maintenance_analysis(schema='auth', table='users') - Specific table in auth schema maintenance_analysis(include='indexes') - Only index analysis maintenance_analysis(include='vacuum') - Only vacuum/bloat analysis maintenance_analysis(include='fk_indexes') - Only FK index analysis

Historical query stats - shows top queries by time/calls/IO from pg_stat_statements.

LEVEL: Database (database-wide query statistics)

USE FOR: "what queries are slowest?", finding high-frequency queries, cache hit analysis, queries using temp files, overall query patterns, "which queries consume most time?". DO NOT USE FOR: analyzing ONE specific query (use query_optimizer), live running queries (use database_health), index recommendations (use maintenance_analysis), query syntax validation (use analyze_query). REQUIRES: pg_stat_statements extension installed.

Examples: query_performance() - Top 20 queries by total time query_performance(order_by='calls') - Most frequently called queries query_performance(order_by='mean_time') - Slowest average execution query_performance(limit=50, min_calls=100) - Top 50, only queries called 100+ times

Comprehensive replication health - physical, logical, CDC, slots, WAL, archiving.

LEVEL: Server (PostgreSQL instance level)

USE FOR: replication status, replica lag, standby, streaming replication, replication slots, CDC, logical replication, publications, subscriptions, WAL archiving, backup progress, "is replication healthy?", "how far behind is the replica?". DO NOT USE FOR: database-level health (use database_health), query performance (use query_performance), PostgreSQL settings (use configuration_review).

INCLUDE OPTIONS:

• 'all': Everything (default)

• 'physical': Standbys, streaming replication, replay lag

• 'logical': CDC status, wal_level, publications, subscriptions, logical slots

• 'slots': All replication slots (physical and logical), inactive slot warnings

• 'wal': WAL info, WAL settings

• 'archiving': Archive mode, archiver status, failed archives, active basebackups

Examples: replication_status() - Full replication report replication_status(include='physical') - Physical replication only replication_status(include='logical') - Logical replication/CDC only replication_status(include='slots') - Replication slots only replication_status(include='wal') - WAL status only replication_status(include='archiving') - WAL archiving status

Reviews PostgreSQL configuration settings and provides tuning observations.

LEVEL: Server (PostgreSQL instance configuration)

USE FOR: configuration, settings, postgresql.conf, parameters, tuning, memory, extensions, "why is DB slow globally?", "is autovacuum configured correctly?", server tuning review. DO NOT USE FOR: database-level health (use database_health), query optimization (use query_optimizer), replication settings (use replication_status), table-specific issues (use maintenance_analysis).

INCLUDE OPTIONS:

• 'all': Everything (default)

• 'memory': shared_buffers, effective_cache_size, work_mem analysis

• 'connections': max_connections, current utilization, pooling recommendations

• 'logging': log_min_duration_statement, log_checkpoints, statement_timeout

• 'autovacuum': autovacuum enabled, workers, thresholds

• 'extensions': Installed extensions, recommended extensions not installed

Examples: configuration_review() - Full configuration review configuration_review(include='memory') - Memory settings only configuration_review(include='connections') - Connection limits only configuration_review(include='autovacuum') - Autovacuum settings only configuration_review(include='logging') - Logging configuration configuration_review(include='extensions') - Installed extensions

Detect duplicate rows in a table based on specified columns.

LEVEL: Table ↔ Column (requires table and columns parameters)

USE FOR: finding duplicates, duplicate rows, "are there duplicate emails?", detecting duplicate records, data deduplication analysis. DO NOT USE FOR: general data quality (use data_quality_report), schema structure (use get_schema), null analysis (use data_quality_report with include='nulls').

Examples: duplicate_detection(table='users', columns='email', schema='public') duplicate_detection(table='orders', columns='customer_id,product_id', schema='shipment')

Comprehensive data quality analysis - nulls, types, empty tables, outliers, soft deletes.

LEVEL: Database ↔ Schema ↔ Table ↔ Column (multi-level tool)

• schema='all': Database level - quality analysis for ALL schemas

• schema='': Schema level - all tables in that schema (supports ANY schema name: 'sales', 'billing', 'auth', 'analytics', etc.)

• table='users': Table level - specific table analysis

• outlier_column='age': Column level - outlier detection for specific column

REQUIRED: Specify schema explicitly - use 'all' for all schemas or a specific schema name.

USE FOR: data quality, data profiling, finding nulls, empty tables, outliers, soft deletes, cardinality analysis, "which columns have too many nulls?", data validation. DO NOT USE FOR: finding duplicates (use duplicate_detection), security/PII scan (use sensitive_data_scan), schema structure (use get_schema).

INCLUDE OPTIONS:

• 'all': Everything (default)

• 'nulls': Null analysis - columns with high NULL percentages

• 'cardinality': Cardinality analysis - unique value counts

• 'empty': Empty tables - tables with zero rows

• 'outliers': Outlier detection (requires table and outlier_column params)

• 'soft_delete': Soft delete patterns - finds deleted_at, is_deleted columns

• 'types': Data type consistency recommendations

Examples: data_quality_report() - All tables in public schema (default) data_quality_report(schema='all') - Database-wide analysis data_quality_report(schema='billing') - All tables in billing schema data_quality_report(include='nulls') - Only null analysis data_quality_report(include='empty') - Only empty tables data_quality_report(include='soft_delete') - Find soft delete patterns data_quality_report(table='users', include='outliers', outlier_column='age') - Outlier detection

Find PII/PHI columns - passwords, credit cards, SSN, emails.

LEVEL: Database (scans all schemas by default) or Schema (if specified)

USE FOR: finding sensitive data, GDPR compliance, security review. DO NOT USE FOR: permissions (security_audit), data quality (data_quality_report).

Examples: sensitive_data_scan() - Scan all schemas sensitive_data_scan(schema='public') - Public schema only

Audit roles, privileges, RLS, SSL, and security definer functions.

LEVEL: Schema or Database (schema='all') REQUIRED: Specify schema explicitly - use 'all' for all schemas or a specific schema name.

USE FOR: security audit, role permissions, RLS policies, SSL status. DO NOT USE FOR: PII detection (sensitive_data_scan), data quality.

INCLUDE: all, roles, privileges, rls, ssl, sensitive, functions

Examples: security_audit(schema='sales') - Audit sales schema security_audit(schema='all') - All schemas security_audit(schema='billing', include='roles') - Roles only in billing

Comprehensive dependency analysis - views, functions, triggers, sequences, FDW.

LEVEL: Database ↔ Schema ↔ Table (multi-level tool)

• schema='all': Database level - dependencies for ALL schemas

• schema='': Schema level - dependencies in that schema (supports ANY schema name: 'sales', 'billing', 'auth', 'analytics', etc.)

• table='users': Table level - what depends on this specific table

REQUIRED: Specify schema explicitly - use 'all' for all schemas or a specific schema name.

USE FOR: dependencies, views, functions, triggers, sequences, extensions, FDW, lineage, "what depends on this table?", "what views exist?", impact analysis before DROP. DO NOT USE FOR: table structure (use get_schema), index analysis (use maintenance_analysis), security permissions (use security_audit).

INCLUDE OPTIONS:

• 'all': Everything (default)

• 'views': Views, materialized views, view dependencies

• 'functions': User-defined functions, trigger functions

• 'triggers': Triggers on tables

• 'sequences': Sequences and their usage

• 'extensions': Installed PostgreSQL extensions

• 'fdw': Foreign data wrappers, foreign servers, foreign tables

Examples: dependency_analysis() - All dependencies in public schema (default) dependency_analysis(schema='all') - Database-wide analysis dependency_analysis(schema='billing') - Dependencies in billing schema dependency_analysis(table='users') - What depends on users table dependency_analysis(include='views') - Only view dependencies dependency_analysis(include='functions') - Only functions dependency_analysis(include='triggers') - Only triggers dependency_analysis(include='fdw') - Foreign data wrappers only

Partition analysis - list all partitioned tables or analyze specific table.

LEVEL: Schema ↔ Table (multi-level tool)

• table=None (default): Lists all partitioned tables across ALL schemas

• table='orders': Requires schema - detailed partition analysis for that table

USE FOR: partitions, partition analysis, partition details, partition size, inheritance, "which tables are partitioned?", partition skew detection, empty partition identification. DO NOT USE FOR: non-partitioned table maintenance (use maintenance_analysis), schema structure (use get_schema), index health (use maintenance_analysis).

INCLUDE OPTIONS (only when table is specified):

• 'all': Everything (default)

• 'details': Partition details - boundaries, row counts, dead rows

• 'size': Size distribution - partition sizes, percentages, skew detection

• 'activity': Partition activity - inserts, updates per partition

• 'indexes': Partition indexes

• 'maintenance': Empty partitions, maintenance candidates, default partitions

Examples: partition_analysis() - List all partitioned tables across all schemas partition_analysis(table='events', schema='logs') - Detailed analysis of events table partition_analysis(table='orders', schema='shipment', include='size') - Size distribution

Retrieve MCP audit logs for accountability and debugging.

USE FOR: viewing tool call history, debugging issues, compliance audits.

Examples: get_audit_logs() - Today's logs get_audit_logs(date='2026-05-29') - Specific date get_audit_logs(limit=10) - Last 10 entries

List available audit log files.

USE FOR: finding available log dates, checking log sizes.

Returns list of log files with date, size, and entry count.