> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pawsql.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> PawSQL 是一个产品：Cloud 是公网部署形态，Engine / Optimizer / Auditor / Advisor / Patroller 是同一产品的组件与交付形态，不是彼此独立的产品。 / PawSQL is a single product: Cloud is the public deployment form, while Engine / Optimizer / Auditor / Advisor / Patroller are components and delivery forms of the same product, not separate products.
> 术语以站内术语表为准：SQL 审核对应英文 SQL Review，查询重写对应 Query Rewrite，索引推荐对应 Index Recommendation；英文内容统一用 Review，不用 Audit。 / Use the site glossary for terminology: 审核 is SQL Review, 重写 is Query Rewrite, 索引推荐 is Index Recommendation; English content uses Review, never Audit.
> 引用能力范围或版本支持时以对应页面为准；标注 unknown、或 status 非 published 的内容表示尚未经产品核实，不应作为事实引用。 / Cite capability scope and version support from the corresponding page; content marked unknown, or with a status other than published, is not yet product-verified and must not be cited as fact.

# Optimize SQL in JetBrains IDEs

> Install and configure PawSQL Client for JetBrains to optimize selected SQL, files, folders, and MyBatis Mapper input.

PawSQL Client for JetBrains integrates SQL review, query rewrite, index recommendation, and performance validation with the IntelliJ Platform. Developers can tune the current statement or analyze SQL files, directories, and MyBatis Mapper input in a batch.

<Note>
  Some interfaces and earlier documentation use the name **PawSQL Advisor**. Search for either PawSQL Client or PawSQL Advisor during installation, and expect existing context-menu commands to retain the PawSQL Advisor name.
</Note>

## Goal

Install and configure PawSQL Client for JetBrains so you can optimize the current SQL statement or batch-analyze SQL files, directories, and MyBatis Mapper input.

## Prerequisites

A compatible IntelliJ Platform IDE and access to the JetBrains Marketplace (or an offline plugin package supplied by PawSQL or an approved internal repository) are required before installing the plugin and running optimization.

## Supported IDEs

The plugin supports IntelliJ Platform products including IntelliJ IDEA, DataGrip, PyCharm, GoLand, WebStorm, PhpStorm, DataSpell, and Android Studio. Check JetBrains Marketplace for current product and version compatibility.

## Install the plugin

Install from the JetBrains Marketplace; see [Install IDE Extensions](/en/user-guide/installation/ide-plugins) for steps. After installation, open a SQL file or project directory and confirm that **PawSQL Advisor** actions appear in the context menu.

If your network cannot reach Marketplace, use only an offline package supplied by PawSQL or an approved internal repository. Verify compatibility across the IDE, plugin, and PawSQL Server versions.

## Configure input and optimization

PawSQL Advisor provides project-level settings. Common options include:

| Setting                   | Purpose                                                                 |
| ------------------------- | ----------------------------------------------------------------------- |
| Input type                | Choose native SQL files or MyBatis Mapper files                         |
| Output language           | Produce recommendations in English or Chinese                           |
| SQL rewrite               | Enable semantically equivalent rewrite candidates                       |
| What-If validation        | Compare plans and estimated cost before and after optimization          |
| Live execution validation | Use measured runtime where permitted instead of relying only on EXPLAIN |

Mapper analysis expands dynamic branches into possible SQL combinations. Poorly constrained Mapper logic can generate statements that never run in the application and lead to irrelevant index recommendations. Review dynamic conditions before a batch task.

## Configure database context

A database connection can supply tables, views, columns, indexes, and statistics, and it can support performance validation. Configuration typically includes the engine, host, port, username, password, default database, and database or schema scope.

<Warning>
  What-If or live execution validation connects to the target database and, when supported, may create and remove candidate indexes for evaluation. Do not enable it against production without reviewing permissions, resource use, locking, and application impact.
</Warning>

## Configure index recommendations

Align these controls with your engineering policy:

* deduplication against existing indexes;
* whether covering indexes may be recommended;
* maximum columns in a covering index;
* maximum columns in a standard candidate index;
* the warning threshold for indexes per table.

A covering index can reduce table access, but it also increases storage and write-maintenance cost. More included columns do not automatically produce a better design.

## Optimize selected SQL

<Steps>
  <Step title="Select a complete statement">
    Select one complete SQL statement without adjacent statements, logs, or Markdown fences.
  </Step>

  <Step title="Start optimization">
    Right-click and choose **PawSQL Advisor > Optimize Selected**.
  </Step>

  <Step title="Adjust this run if needed">
    Choose **Optimize Selected Config...** to change settings before submission.
  </Step>

  <Step title="Monitor execution">
    Use the IDE console to inspect parsing, connectivity, and optimization progress.
  </Step>

  <Step title="Open the result">
    Review the generated summary and statement-level details when processing completes.
  </Step>
</Steps>

<Frame caption="PawSQL Advisor actions in the context menu">
  Screenshot placeholder · /images/dev-tools/jetbrains-optimize.png
</Frame>

## Optimize a file or folder

Right-click a SQL file or directory and choose **PawSQL Advisor > Optimize**. Use **Optimize Config...** to change settings before the run.

Before batch optimization, confirm:

* the input type matches the files;
* encoding and SQL delimiters are correct;
* generated files, backups, and unrelated logs are excluded;
* the workspace or connection represents the target environment;
* the batch size fits current service limits.

## Read the result

After completion, the plugin generates and opens a `pawTuningSummary` Markdown file. It commonly contains:

* task overview and processed SQL inventory;
* recommended-index summary;
* original and rewritten SQL with applied rewrite strategies;
* rule findings and affected SQL fragments;
* existing-index, redundant-index, and index-count observations;
* performance improvement and before-and-after plans when validation is enabled.

<Frame caption="Optimization summary file pawTuningSummary">
  Screenshot placeholder · /images/dev-tools/jetbrains-summary.png
</Frame>

Open a statement from the summary, then review findings, rewrite candidates, index recommendations, and performance evidence in that order.

## Verification

After a run, confirm that the `pawTuningSummary` file opened and that the task overview, rewrite candidates, index recommendations, and any validation evidence appear as expected.

## Before applying a recommendation

* Verify result, parameter, and transaction semantics.
* Check candidate indexes for overlap or conflict with existing indexes.
* Account for write, storage, and maintenance costs.
* Validate plans with representative data and parameter values.
* Use code review, testing, and database change control for deployment.

## Troubleshooting

| Symptom                                         | Check first                                                          |
| ----------------------------------------------- | -------------------------------------------------------------------- |
| Plugin is missing from Marketplace              | IDE version, proxy, and corporate plugin policy                      |
| PawSQL Advisor is missing from the context menu | Plugin status, file type, and whether the IDE restarted              |
| Only part of the SQL is detected                | Selection, delimiters, dialect, encoding, and placeholders           |
| Mapper analysis produces irrelevant advice      | Dynamic conditions, unreachable branches, and generated combinations |
| Database objects are unresolved                 | Connection, default schema, permissions, and metadata                |
| Validation results are absent                   | Validation settings, connection permissions, and engine capability   |

## Related documentation

<CardGroup cols={2}>
  <Card title="Input SQL to Optimize" href="/en/user-guide/optimization/create-workload" />

  <Card title="Read Optimization Results" href="/en/user-guide/optimization/explain-output" />

  <Card title="Evaluate and Apply Suggestions" href="/en/user-guide/optimization/apply-suggestions" />
</CardGroup>