Run data-quality checks on one schema or table.

Best for: Finding null-rate spikes, missing primary keys, low-cardinality issues, duplicate rows, and orphaned foreign keys. Not recommended for: Replacing a full observability or data-governance system. Common mistakes: Forgetting to scope the audit to one table when you only need one table.

Usage Example:

{
  "name": "whodb_audit",
  "arguments": {
    "connection": "mydb",
    "schema": "public",
    "table": "orders",
    "null_warning": 15,
    "null_error": 60
  }
}

Returns: Audit results per table, including issue summaries and the underlying table/column findings.

Describe the columns in a database table.

Best for: Understanding table structure before writing queries; discovering primary keys and foreign key relationships. Not recommended for: When you need actual data (use whodb_query with SELECT). Common mistakes: Forgetting to specify the table name; not using this before writing INSERT/UPDATE queries.

Usage Example:

{
  "name": "whodb_columns",
  "arguments": {
    "connection": "mydb",
    "table": "users",
    "schema": "public"
  }
}

Returns: Array of column objects with:

• name: Column name

• type: Data type (varchar, integer, timestamp, etc.)

• is_primary: Whether this is a primary key

• is_foreign_key: Whether this references another table

• referenced_table/referenced_column: Foreign key target (if applicable)

Pro tip: Always call this before writing INSERT queries to ensure correct column names and types.

Confirm and execute a pending write operation.

Best for: Executing write queries after user approval in confirm-writes mode. Not recommended for: Read queries (they execute immediately without confirmation). Common mistakes: Using an expired token (tokens expire after 5 minutes); not explaining the query to the user before confirming.

Usage Example:

{
  "name": "whodb_confirm",
  "arguments": {
    "token": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Workflow:

1. Call whodb_query with a write operation (INSERT, UPDATE, DELETE, etc.)

2. Receive confirmation_required=true, a confirmation_token, and confirmation_expiry

3. Explain to the user what the query will do in plain language

4. After user approves, call whodb_confirm with the token

5. Query executes and returns results

Token behavior: Tokens are valid for 5 minutes (expiry time is in the response). If confirmation fails due to a connection error or timeout, you can retry with the same token — it is only consumed after successful execution. Use whodb_pending to list active tokens if you lose track.

List all available database connections.

Best for: Discovering what databases are configured; choosing which connection to use. Not recommended for: When you already know the connection name. Common mistakes: Not calling this first when connection name is unknown.

Usage Example:

{
  "name": "whodb_connections",
  "arguments": {}
}

Returns: Array of connection objects with:

• name: Connection identifier to use in other tools

• type: Database type (postgres, mysql, sqlite, duckdb, etc.)

• host/port/database: Connection details (passwords are never exposed)

• source: "saved" (from CLI config) or "env" (from environment variables)

Note: If only one connection exists, other tools will use it automatically when connection is omitted.

Compare schema metadata between two database connections.

Best for: Spotting drift between environments; comparing staging vs production; reviewing storage-unit, column, and relationship changes. Not recommended for: Row-level data comparison. Common mistakes: Forgetting to specify both connections; comparing the same connection and schema without overrides.

Usage Example:

{
  "name": "whodb_diff",
  "arguments": {
    "from_connection": "staging",
    "to_connection": "prod",
    "from_schema": "public",
    "to_schema": "public"
  }
}

Returns: A structured schema diff with storage-unit, column, and relationship summaries plus per-object changes.

Load backend graph metadata for a schema or database.

Best for: Understanding how tables relate before writing joins; inspecting primary/foreign key relationships programmatically. Not recommended for: Query execution. Common mistakes: Expecting row data instead of metadata.

Usage Example:

{
  "name": "whodb_erd",
  "arguments": {
    "connection": "mydb",
    "schema": "public"
  }
}

Returns: Storage units with columns plus normalized relationship edges sourced from backend graph metadata.

Run EXPLAIN for a SQL query using the database's native explain mode.

Best for: Understanding query plans; checking whether a query will scan too much data before you run the real query. Not recommended for: Fetching actual data (use whodb_query for that). Common mistakes: Passing a non-SQL string; forgetting that EXPLAIN output is database-specific.

Usage Example:

{
  "name": "whodb_explain",
  "arguments": {
    "connection": "mydb",
    "query": "SELECT * FROM users WHERE email LIKE '%@example.com' LIMIT 10"
  }
}

Returns: The database-native EXPLAIN output with columns and rows, ready for follow-up analysis.

List all pending write confirmations that are waiting for approval.

Best for: Recovering lost confirmation tokens; checking what operations are pending. Not recommended for: Anything else — this is a utility tool for the confirm-writes workflow.

Usage Example:

{
  "name": "whodb_pending",
  "arguments": {}
}

Returns: Array of pending confirmations with token, query, connection, and expiry time.

Important: Tokens are single-use and expire after 60 seconds. If expired, re-submit the original query to get a new token.

Execute a SQL query against a database connection.

Best for: Running SQL SELECT, INSERT, UPDATE, DELETE statements when you need to query or modify data. Not recommended for: Schema exploration (use whodb_schemas, whodb_tables, whodb_columns instead for faster, structured results). Common mistakes: Running queries without specifying connection when multiple exist; using SELECT * instead of specific columns; forgetting LIMIT on large tables.

Usage Example (simple query):

{
  "name": "whodb_query",
  "arguments": {
    "connection": "mydb",
    "query": "SELECT id, name, email FROM users WHERE active = true LIMIT 10"
  }
}

Usage Example (parameterized query - RECOMMENDED for user input):

{
  "name": "whodb_query",
  "arguments": {
    "connection": "mydb",
    "query": "SELECT * FROM users WHERE id = $1 AND status = $2",
    "parameters": [123, "active"]
  }
}

Placeholder syntax by database: PostgreSQL uses $1, $2, $3; MySQL/SQLite/DuckDB/ClickHouse use ?

Best practices:

• Use parameterized queries when incorporating user-provided values - this prevents SQL injection

• Always use LIMIT for exploratory queries to avoid overwhelming results

• Prefer specific column selection over SELECT *

• Check schema structure with whodb_columns before writing complex queries

Security Mode: CONFIRM-WRITES (Default) Write operations (INSERT, UPDATE, DELETE, etc.) require user confirmation. When you submit a write query:

1. The query is validated but NOT executed

2. You receive a confirmation_token

3. Explain to the user what the query will do

4. Call whodb_confirm with the token after user approves

5. The query executes and returns results

List all schemas (namespaces) in a database.

Best for: Discovering what schemas exist in a database; understanding database organization before exploring tables. Not recommended for: When you already know the schema name (proceed directly to whodb_tables). Common mistakes: Calling this repeatedly - schema lists rarely change during a session.

Usage Example:

{
  "name": "whodb_schemas",
  "arguments": {
    "connection": "mydb"
  }
}

Returns: Array of schema names (e.g., ["public", "analytics", "audit"]). Typical workflow: whodb_schemas → whodb_tables(include_columns=true) → whodb_query

Optional parameter: Set "include_tables": true to also return all tables within each schema in a single call. This populates a "details" array with schema names and their tables, saving you a separate whodb_tables call per schema.

Load backend-generated starter queries for a schema or database.

Best for: Quickly orienting yourself in an unfamiliar database; suggesting first queries for exploration. Not recommended for: Exhaustive SQL tutoring. Common mistakes: Treating the suggestions as guaranteed-valid business logic rather than onboarding hints.

Usage Example:

{
  "name": "whodb_suggestions",
  "arguments": {
    "connection": "mydb",
    "schema": "public"
  }
}

Returns: A short list of backend-generated query suggestions derived from the actual storage units in the resolved schema.

List all tables in a database schema.

Best for: Discovering what tables exist in a schema; getting table metadata like row counts. Not recommended for: When you already know the table name (proceed directly to whodb_columns or whodb_query). Common mistakes: Not specifying schema when the database has multiple schemas with same-named tables.

Usage Example:

{
  "name": "whodb_tables",
  "arguments": {
    "connection": "mydb",
    "schema": "public"
  }
}

Returns: Array of table objects with name and attributes (row count, size, etc.). Note: If schema is omitted, uses the connection's default schema or the first available schema.

Optional parameter: Set "include_columns": true to also return column details (name, type, primary key, foreign keys) for each table. This saves you separate whodb_columns calls and gives you everything needed to write queries in a single round-trip.