pgadmin4/docs/en_US/ai_tools.rst

.. _ai_tools:

*******************
`AI Reports`:index:
*******************

**AI Reports** is a feature that provides AI-powered database analysis and insights
using Large Language Models (LLMs). Use the *Tools → AI Reports* menu to access
the various AI-powered reports.

The AI Reports feature allows you to:

 * Generate security reports to identify potential security vulnerabilities and configuration issues.

 * Create performance reports with optimization recommendations for queries and configurations.

 * Perform design reviews to analyze database schema structure and suggest improvements.

**Prerequisites:**

Before using AI Reports, you must:

 1. Ensure AI features are enabled in the server configuration (set ``LLM_ENABLED`` to ``True`` in ``config.py``).

 2. Configure an LLM provider in :ref:`Preferences → AI <preferences>`.

**Note:**

 * AI Reports using cloud providers (Anthropic, OpenAI) require an active internet connection.
   Local providers (Ollama, Docker Model Runner) do not require internet access.

 * API usage may incur costs depending on your LLM provider's pricing model.
   Local providers (Ollama, Docker Model Runner) are free to use.

 * The quality and accuracy of reports depend on the LLM provider and model configured.


Configuring AI Reports
**********************

To configure AI Reports, navigate to *File → Preferences → AI* (or click the *Settings*
button and select *AI*).

.. image:: images/preferences_ai.png
    :alt: AI preferences
    :align: center

Select your preferred LLM provider from the dropdown:

**Anthropic**
  Use Claude models from Anthropic, or any Anthropic-compatible API provider.

  * **API URL**: Custom API endpoint URL (leave empty for default: https://api.anthropic.com/v1).
  * **API Key File**: Path to a file containing your Anthropic API key (obtain from https://console.anthropic.com/). This path refers to the filesystem where the pgAdmin server is running (e.g., inside the container if using Docker). The ``~`` prefix is expanded to the home directory of the user running the pgAdmin server process. Optional when using a custom URL with a provider that does not require authentication.
  * **Model**: Select from available Claude models (e.g., claude-sonnet-4-20250514).

**OpenAI**
  Use GPT models from OpenAI, or any OpenAI-compatible API provider (e.g.,
  LiteLLM, LM Studio, EXO, or other local inference servers).

  * **API URL**: Custom API endpoint URL (leave empty for default: https://api.openai.com/v1). Include the ``/v1`` path prefix if required by your provider.
  * **API Key File**: Path to a file containing your OpenAI API key (obtain from https://platform.openai.com/). This path refers to the filesystem where the pgAdmin server is running (e.g., inside the container if using Docker). The ``~`` prefix is expanded to the home directory of the user running the pgAdmin server process. Optional when using a custom URL with a provider that does not require authentication.
  * **Model**: Select from available GPT models (e.g., gpt-4).

**Ollama**
  Use locally-hosted open-source models via Ollama. Requires a running Ollama instance.

  * **API URL**: The URL of your Ollama server (default: http://localhost:11434).
  * **Model**: Enter the name of the Ollama model to use (e.g., llama2, mistral).

**Docker Model Runner**
  Use models running in Docker Desktop's built-in model runner (available in Docker Desktop 4.40+).
  No API key is required.

  * **API URL**: The URL of the Docker Model Runner API (default: http://localhost:12434).
  * **Model**: Select from available models or enter a custom model name.

.. note:: You can also use the *OpenAI* provider with a custom API URL for any
   OpenAI-compatible endpoint, including Docker Model Runner and other local
   inference servers.

After configuring your provider, click *Save* to apply the changes.


.. _ai_data_handling:

Data Handling and Provider Selection
************************************

When a cloud LLM provider is configured, pgAdmin transmits information about
your database to that provider's API. Depending on the feature in use, this may
include schema definitions such as table, column, index and constraint names
and data types; server and database configuration settings read from
``pg_settings``; query text; and EXPLAIN plan output. The *AI Assistant* in the
Query Tool is also able to run queries against your database, within a read-only
transaction and limited to 1000 rows, so row data may be included where the
assistant determines it is needed to answer a question.

None of this is transmitted unless you invoke an AI feature, and none of it is
transmitted at all when no provider has been configured, which is the default;
when AI features have been disabled by the administrator through the
``LLM_ENABLED`` setting; or when a locally hosted provider such as Ollama or
Docker Model Runner is configured.

Each provider processes this data under its own terms of service, privacy policy
and legal jurisdiction, and operates its infrastructure in locations of its own
choosing. If you work in an environment subject to data residency requirements,
procurement policies, or sector-specific rules governing the handling of
database metadata, review both the provider's terms and your own organisation's
policies before enabling a cloud provider.

The providers listed in pgAdmin reflect the APIs that pgAdmin is able to
communicate with. Their inclusion is not a recommendation, and no provider is
enabled by default.


Security Reports
****************

Security Reports analyze your PostgreSQL server, database, or schema for potential
security vulnerabilities and configuration issues.

To generate a security report:

1. In the *Browser* tree, select a server, database, or schema.

2. Choose *Tools → AI Reports → Security* from the menu, or right-click the
   object and select *Security* from the context menu.

3. The report will be generated and displayed in a new tab.

.. image:: images/ai_security_report.png
    :alt: AI security report
    :align: center

**Security Report Scope:**

* **Server Level**: Analyzes server configuration, authentication settings, roles, and permissions.

* **Database Level**: Reviews database-specific security settings, roles with database access, and object permissions.

* **Schema Level**: Examines schema permissions, object ownership, and access controls.

Each report includes:

* **Security Findings**: Identified vulnerabilities or security concerns.

* **Risk Assessment**: Severity levels for each finding (Critical, High, Medium, Low).

* **Recommendations**: Specific actions to remediate security issues.

* **Best Practices**: General security recommendations for PostgreSQL.


Performance Reports
*******************

Performance Reports analyze query performance, configuration settings, and provide
optimization recommendations.

To generate a performance report:

1. In the *Browser* tree, select a server or database.

2. Choose *Tools → AI Reports → Performance* from the menu, or right-click the
   object and select *Performance* from the context menu.

3. The report will be generated and displayed in a new tab.

**Performance Report Scope:**

* **Server Level**: Analyzes server configuration parameters, resource utilization, and overall server performance metrics.

* **Database Level**: Reviews database-specific configuration, query performance, index usage, and table statistics.

Each report includes:

* **Performance Metrics**: Key performance indicators and statistics.

* **Configuration Analysis**: Review of relevant configuration parameters.

* **Query Optimization**: Recommendations for improving slow queries.

* **Index Recommendations**: Suggestions for adding, removing, or modifying indexes.

* **Capacity Planning**: Resource utilization trends and recommendations.


Design Review Reports
*********************

Design Review Reports analyze your database schema structure and suggest
improvements for normalization, naming conventions, and best practices.

To generate a design review report:

1. In the *Browser* tree, select a database or schema.

2. Choose *Tools → AI Reports → Design* from the menu, or right-click the
   object and select *Design* from the context menu.

3. The report will be generated and displayed in a new tab.

**Design Review Scope:**

* **Database Level**: Reviews overall database structure, schema organization, and cross-schema dependencies.

* **Schema Level**: Analyzes tables, views, functions, and other objects within the schema.

Each report includes:

* **Schema Structure Analysis**: Review of table structures, relationships, and constraints.

* **Normalization Review**: Recommendations for database normalization (1NF, 2NF, 3NF, etc.).

* **Naming Conventions**: Suggestions for consistent naming patterns.

* **Data Type Usage**: Review of data type choices and recommendations.

* **Index Design**: Analysis of indexing strategy.

* **Best Practices**: General PostgreSQL schema design recommendations.


Working with Reports
********************

All AI reports are displayed in a dedicated panel with the following features:

**Report Display**
  Reports are formatted as Markdown and rendered with syntax highlighting for SQL code.

**Toolbar Actions**

  * **Stop** - Cancel the current report generation. This is useful if the report
    is taking too long or if you want to change parameters.

  * **Regenerate** - Generate a new report for the same object. Useful when you
    want to get a fresh analysis or if data has changed.

  * **Download** - Download the report as a Markdown (.md) file. The filename
    includes the report type, object name, and date for easy identification.

**Multiple Reports**
  You can generate and view multiple reports simultaneously. Each report opens in
  a new tab, allowing you to compare reports across different servers, databases,
  or schemas.

**Report Management**
  Each report tab can be closed individually by clicking the *X* in the tab.
  Panel titles show the object name and report type for easy identification.

**Copying Content**
  You can select and copy text from reports to use in documentation or share with
  your team.


Troubleshooting
***************

**"AI features are disabled in the server configuration"**
  The administrator has disabled AI features on the server. Contact your
  pgAdmin administrator to enable the ``LLM_ENABLED`` configuration option.

**"Please configure an LLM provider in Preferences"**
  You need to configure an LLM provider before using AI Reports. See *Configuring AI Reports* above.

**"Please connect to the server/database first"**
  You must establish a connection to the server or database before generating reports.

**API Connection Errors**
  * Verify your API key is correct (for Anthropic and OpenAI).
  * Check your internet connection (for cloud providers).
  * For Ollama, ensure the Ollama server is running and accessible.
  * For Docker Model Runner, ensure Docker Desktop 4.40+ is running with the model runner enabled.
  * Check that your firewall allows connections to the LLM provider's API.

**Report Generation Fails**
  * Check the pgAdmin logs for detailed error messages.
  * Verify the database connection is still active.
  * Ensure the selected model is available for your account/subscription.