Executes a series of diagnostic SQL scripts concurrently based on the
specified level ('basic' or 'full'). Aggregates raw results or errors
from each script into a dictionary.

Args:
    ctx: The MCP context object.
    level: Level of detail: 'basic' for operational status, 'full' for
           comprehensive table design/maintenance checks. Defaults to 'basic'.
    time_window_days: Lookback period in days for time-sensitive checks
                      (e.g., queue waits, commit waits). Defaults to 1.

Returns:
    A dictionary where keys are script names and values are either the raw
    list of dictionary results from the SQL query or an Exception object
    if that specific script failed.

Raises:
    DataApiError: If a critical error occurs during script execution that
                  prevents gathering results (e.g., config error). Individual
                  script errors are captured within the returned dictionary.

Fetches all current lock information and then filters it based on the
optional target PID, target table name, and minimum wait time.
Formats the results into a list of contention details and a summary.

Args:
    ctx: The MCP context object.
    target_pid: Optional: Filter results to show locks held by or waited
                for by this specific process ID (PID).
    target_table_name: Optional: Filter results for locks specifically on
                       this table name (schema qualification recommended
                       if ambiguous).
    min_wait_seconds: Minimum seconds a lock must be in a waiting state
                      to be included. Defaults to 5.

Returns:
    A list of dictionaries, where each dictionary represents a row
    from the lock contention query result.

Raises:
    DataApiError: If fetching the initial lock information fails.

Fetches query text, execution plan, metrics, alerts, compilation info,
skew details, and optionally historical run data. Uses a formatting
utility to synthesize this into a structured report with potential issues
and recommendations.

Args:
    ctx: The MCP context object.
    query_id: The numeric ID of the Redshift query to analyze.
    compare_historical: Fetch performance data for previous runs of the
                       same query text. Defaults to True.

Returns:
    A dictionary conforming to DiagnoseQueryPerformanceResult structure:
    - On success: Contains detailed performance breakdown, issues, recommendations.
    - On query not found: Raises QueryNotFound exception.
    - On other errors: Raises DataApiError or similar for FastMCP to handle.

Raises:
    DataApiError: If a critical error occurs during script execution or parsing.
    QueryNotFound: If the specified query_id cannot be found in key tables.

Designed as an escape hatch for advanced users or queries not covered by
specialized tools. Returns a structured dictionary indicating success
(with results) or failure (with error details).

Args:
    ctx: The MCP context object.
    sql_query: The exact SQL query string to execute.

Returns:
    A dictionary conforming to ExecuteAdHocQueryResult structure:
    - On success: {"status": "success", "columns": [...], "rows": [...], "row_count": ...}
    - On error: {"status": "error", "error_message": "...", "error_type": "..."}
    (Note: Actual return might be handled by FastMCP error handling for raised exceptions)

Raises:
    DataApiConfigError: If configuration is invalid.
    SqlExecutionError: If the SQL execution itself fails.
    DataApiTimeoutError: If the Data API call times out.
    DataApiError: For other Data API related errors or unexpected issues.
    ClientError: For AWS client-side errors.

Executes a SQL script designed to generate or retrieve the CREATE TABLE
statement for the given table.

Args:
    ctx: The MCP context object.
    schema_name: The schema name of the table.
    table_name: The name of the table.

Returns:
    A dictionary conforming to GetTableDefinitionResult structure:
    - On success: {"status": "success", "ddl": "<CREATE TABLE statement>"}
    - On table not found or DDL retrieval error:
      {"status": "error", "error_message": "...", "error_type": "..."}

Raises:
    TableNotFound: If the specified table is not found.
    DataApiError: If a critical, unexpected error occurs during execution.

Fetches table OID, then concurrently executes various inspection scripts
covering design, storage, health, usage, and encoding.

Args:
    ctx: The MCP context object.
    schema_name: The schema name of the table.
    table_name: The name of the table.

Returns:
    A dictionary where keys are script names and values are either the raw
    list of dictionary results from the SQL query, the extracted DDL string,
    or an Exception object if that specific script failed.
    - On success: Dictionary containing raw results or Exception objects for each script.
    - On table not found: Raises TableNotFound exception.
    - On critical errors (e.g., OID lookup failure): Raises DataApiError or similar.

Raises:
    DataApiError: If a critical error occurs during script execution.
    TableNotFound: If the specified table cannot be found via its OID.

Executes various SQL scripts concurrently to gather data on resource usage,
WLM performance, top queries, queuing, COPY performance, and disk-based
queries. Returns a dictionary containing the raw results (or Exceptions)
keyed by the script name.

Args:
    ctx: The MCP context object.
    time_window_days: Lookback period in days for the workload analysis.
                      Defaults to 2.
    top_n_queries: Number of top queries (by total execution time) to
                   consider for the 'top_queries.sql' script. Defaults to 10.

Returns:
    A dictionary where keys are script names (e.g., 'workload/top_queries.sql')
    and values are either a list of result rows (as dictionaries) or the
    Exception object if that script failed.

Raises:
    DataApiError: If a critical error occurs during configuration loading.
                  (Note: Individual script errors are returned in the result dict).