Плагин для анализа планов PostgreSQL в IDE JetBrains и его разработка

Для пользователей explain.tensor.ru — нашего сервиса визуализации PostgreSQL-планов, мы создали плагин «Explain PostgreSQL» для всех IDE от JetBrains, теперь есть возможность форматировать запросы и анализировать планы непосредственно в IDE.

Как использовать плагин и детали о его разработке читайте ниже.

---

Установка плагина

К сожалению, попытка опубликовать плагин в JetBrains Marketplace завершилась отказом:

На основании имеющейся у нас информации, Вы являетесь лицом, связанным с организацией, находящейся в Российской Федерации, и/или с Правительством Российской Федерации.

По этой причине, а также в связи с недавно опубликованной поправкой к санкционному законодательству ЕС (8-й пакет санкций ЕС), JetBrains не может предоставлять Вам услуги ИТ‑консалтинга, включая техническую поддержку или помощь. Проверки и публикация плагинов на Маркетплейсе JetBrains попадают под определение предоставления технической поддержки.

Поэтому установку плагина надо делать из локального файла — скачиваем его с сайта explain.tensor.ru (раздел Download / Plugins ) и в Settings > Plugins выбираем Install plugin from Disk .

Подключение к БД

создаем новый datasource:

скачиваем JDBC-драйвера PostgreSQL и подключаемся к БД:

Форматирование запроса

в консоли набираем текст запроса и нажимаем Ctrl-Q F или в контекстном меню SQL Format:

Анализ запроса

В контекстном меню выбираем Explain Plan > Explain Analyze (Tensor) , при этом выполнится запрос EXPLAIN (ANALYZE, BUFFERS)

полученный план отправится в сервис explain.tensor.ru через публичное API , результат откроется в новом окне:

Для IDE без плагина Database Tools

В WebStorm для работы с БД требуется установка плагина Database Tools and SQL for WebStorm . Если этот плагин не установлен или у вас community-версия IDE то открыть сайт explain.tensor.ru можно прямо в IDE:

Настройка плагина

Для тех кто развернул сервис локально, используя вариант self hosted, или использует сайт explain-postgresql.com , можно поменять сайт в настройках IDE в Tools > Explain PostgreSQL:

О разработке плагина для JetBrains IDE

Создаем новый проект «IDE plugin».
В окне есть ссылка на официальную документацию IntelliJ Platform SDK , в ней приведены основные сведения, используемые при разработке.

Создание Tool Window

1. создаем класс, реализующий интерфейс ToolWindowFactory и переопределяем метод createToolWindowContent , который будет вызываться при нажатии на кнопку окна — здесь в окне создается новая вкладка с сайтом explain.tensor.ru и кнопка новой вкладки:

public class ExplainToolWindowFactory implements ToolWindowFactory, DumbAware {  @Override public void createToolWindowContent(@NotNull Project project, @NotNull ToolWindow toolWindow) { createNewTab(project); ButtonNewTab newTabBtn = new ButtonNewTab("New Tab", null, AllIcons.Toolbar.AddSlot); ((ToolWindowEx) toolWindow).setTabActions(newTabBtn); }      public static void createNewTab(Project project) { ApplicationManager.getApplication().invokeLater((new Runnable() { @Override public void run() { ExplainBrowser browser = new ExplainBrowser(true); ToolWindow toolWindow = ToolWindowManager.getInstance(project).getToolWindow(explainWindow); Content content = ContentFactory.getInstance().createContent(browser.getComponent(), "Explain", false); content.setDisposer(browser); @NotNull ContentManager contentManager = toolWindow.getContentManager(); contentManager.addContent(content); contentManager.setSelectedContent(content); } })); } } 

2. кнопка создания новой вкладки — наследуем AnActionButton и переопределяем методы:

   actionPerformed — выполняется при нажатии на кнопку, здесь мы создаем новую вкладку или открываем новое окно браузера если нажали вместе с Ctrl

   updateButton — выполняется для определения доступности кнопки, в нашем случае если JDK с поддержкой JCEF браузера и открыто tool window

public class ButtonNewTab extends AnActionButton {  public ButtonNewTab(String text, String descr, Icon icon) { super(text, descr, icon); }  @Override public void actionPerformed(@NotNull AnActionEvent e) { if (e.getInputEvent().isControlDown()) { BrowserUtil.browse(AppSettingsState.getInstance().getExplainUrl()); } else { ExplainToolWindowFactory.createNewTab(e.getProject()); } }  @Override public void updateButton(@NotNull AnActionEvent e) { super.updateButton(e); boolean enabled = ExplainBrowser.isSupported && ExplainToolWindowFactory.getToolWindow(e.getProject()).isVisible(); e.getPresentation().setEnabled(enabled); } } 

3. окно с JCEF-браузером

   JCEF — это реализация Chromium Embedded Framework в Java, определяем возможность его использования методом isSupported и если нет, то вместо компонента с окном браузера выдаем сообщение:

public class ExplainBrowser implements Disposable { public static final String EXPLAIN_URL = "https://explain.tensor.ru"; public static final boolean isSupported = JBCefApp.isSupported(); private JBCefBrowser browser = null; private JPanel panel = null; public ExplainBrowser(boolean loadOnStart) { if (isSupported) { browser = new JBCefBrowser(EXPLAIN_URL); } else { panel = new JPanel(new BorderLayout()); JLabel label = new JLabel("JCEF browser is not supported"); panel.add(label, BorderLayout.CENTER); } }  public JComponent getComponent() { if (browser == null) { return panel; } else { return browser.getComponent(); } } } 

4. добавляем описание tool window в plugin.xml в разделе extensions, в параметре factoryClass указываем созданный в п.1 класс. IDE при старте прочитает plugin.xml и создаст наше окно снизу на панели инструментов

  <extensions defaultExtensionNs="com.intellij">     <toolWindow factoryClass="com.mgorkov.toolwindow.ExplainToolWindowFactory"                 id="Explain PostgreSQL"                 anchor="bottom"                 secondary="true"                 canCloseContents="true"                 largeStripeAnchor="true"                 icon="AllIcons.Xml.Browsers.Chrome"                 doNotActivateOnStart="true"     />   </extensions> 

Форматирование запроса

Создаем класс SQLFormatter и наследуем от AnAction , в нем также как и в AnActionButton надо переопределить методы actionPerformed и update.

В actionPerformed мы получаем текст документа и, используя API explain.tensor.ru , форматируем и заменяем исходный текст.

public class SQLFormatter extends AnAction {      private Document document = null;     private String formatted = null;      @Override     public void actionPerformed(@NotNull AnActionEvent e) {         Editor editor = e.getData(CommonDataKeys.EDITOR);         if (editor != null) {             document = editor.getDocument();             String text = document.getText();             formatted = explainApi.beautifier(e, text).join();             if (formatted != null) {                 WriteCommandAction.runWriteCommandAction(e.getProject(), () -> {                   document.deleteString(0, document.getTextLength());                   document.insertString(0, formatted);                 });             }         }     } } 

Чтобы IDE узнала об этом действии нужно зарегистрировать его в plugin.xml в разделе actions , указав реализующий класс, место размещения и комбинацию клавиш. Здесь мы размещаем действие в EditorPopupMenu и оно доступно при нажатии Ctrl Q F

<actions>   <action id="SQLFormat" class="com.mgorkov.actions.SQLFormatter" text="SQL Format">     <add-to-group group-id="EditorPopupMenu" anchor="last"/>     <keyboard-shortcut keymap="$default" first-keystroke="ctrl Q" second-keystroke="F"/>   </action> </actions> 

При наличии синтаксических ошибок выдается предупреждение:

Это реализовано в методе showErrorMessage сервиса ExplainApiService:

private void showErrorMessage(@NotNull AnActionEvent e, String msg) {     ApplicationManager.getApplication().invokeLater(() -> {         HintManager.getInstance().showErrorHint(Objects.requireNonNull(e.getData(CommonDataKeys.EDITOR)), msg);     }); }

Анализ запроса

Для выполнение запросов к базе используем плагин JetBrains Database Tools, он встроен во все IDE , кроме community edition и WebStorm (можно установить отдельно).

Здесь мы наследуем класс ExplainActionBase.Ui и в нем переопределяем метод explainStatement , в котором выполняем запрос и выводим окно браузера с результатом анализа в новой вкладке редактора:

FileEditor[] editors = FileEditorManager.getInstance(console.getProject()).openFile(file, true); Arrays.stream(editors).filter(e -> e instanceof PgPlanEditor).forEach(e -> {     PgPlanEditor editor = (PgPlanEditor) e;     editor.getExplainWindow().updatePlan(mdl.getJson()); });

Далее регистрируем новые действия в контекстном меню JDBC-консоли. Чтобы плагин мог работать в IDE без Database Tools добавим в plugin.xml опциональную зависимость от него:

<depends optional="true" config-file="plugin-withdatabase.xml">com.intellij.database</depends>

и создадим plugin-withdatabase.xml :

<actions>     <action id="com.mgorkov.actions.ExplainAnalyzeAction"             class="com.mgorkov.actions.ExplainAnalyzeAction" text="Explain Analyze (Tensor)"             icon="DatabaseIcons.ConsoleShowPlan">         <add-to-group group-id="Console.Jdbc.ExplainGroup" anchor="last"/>     </action>     <action id="com.mgorkov.actions.ExplainAction" class="com.mgorkov.actions.ExplainAction"             text="Explain Plan (Tensor)"             icon="DatabaseIcons.ConsoleShowPlan">         <add-to-group group-id="Console.Jdbc.ExplainGroup" anchor="last"/>     </action> </actions>

Настройка плагина

В IDE есть понятие сервисов, это компоненты плагина, которые загружаются по требованию при вызове getService() . При этом сервисы реализуют паттерн singleton, т.е. при вызове getService() всегда возвращается один и тот же компонент. Хранение настроек плагина реализуется сервисом типа applicationService (всего их три).

Реализация настроек выполнена по схеме MVC.

Роль модели выполняет класс AppSettingsState, реализующий PersistentStateComponent, при этом в аннотации надо указать имя параметра и файла, в котором сохраняются настройки:

@State(         name = "com.mgorkov.settings.AppSettingsState",         storages = @Storage("ExplainPostgreSQLSettingsPlugin.xml") ) public final class AppSettingsState implements PersistentStateComponent<AppSettingsState> {      private String ExplainUrl = "https://explain.tensor.ru";      public static AppSettingsState getInstance() {         return ApplicationManager.getApplication().getService(AppSettingsState.class);     }      public void setExplainUrl(String explainUrl) {         ExplainUrl = explainUrl;     } } 

Роль контроллера — класс AppSettingsConfigurable реализующий интерфейс Configurable , в котором переопределены методы:

getDisplayName — выдает название пункта меню Settings, используется при поиске

public class AppSettingsConfigurable implements Configurable {      private AppSettingsComponent appSettingsComponent;      @Override     public @NlsContexts.ConfigurableName String getDisplayName() {         return "Explain PostgreSQL";     }      @Override     public @Nullable JComponent createComponent() {         appSettingsComponent = new AppSettingsComponent();         return appSettingsComponent.getPanel();     }      @Override     public void apply() throws ConfigurationException {         AppSettingsState settings = AppSettingsState.getInstance();         String explainUrl = appSettingsComponent.getExplainUrl();         try {             new URL(explainUrl).openStream().close();             settings.setExplainUrl(explainUrl);         } catch (Exception e) {             throw new ConfigurationException(e.getMessage());         }     } } 

apply — выполняет проверку на валидность URL и возможность подключиться к нему, в случае ошибок бросает исключение ConfigurationException , текст из которого выводится снизу на странице настроек.

createComponent — создает страницу настроек, о ней ниже.

Роль представления реализует класс AppSettingsComponent , в котором создается форма с текстовым полем и меткой:

public class AppSettingsComponent {     private final JPanel panel;     private final JBTextField explainUrlTextField = new JBTextField();      public AppSettingsComponent() {         panel = FormBuilder.createFormBuilder()                 .addLabeledComponent(new JBLabel("Explain PostgreSQL site: "), explainUrlTextField, 1, false)                 .addComponentFillVertically(new JPanel(), 0)                 .getPanel();     }      public JPanel getPanel() {         return panel;     }      public String getExplainUrl() {         return explainUrlTextField.getText();     }      public void setExplainUrl(@NotNull String url) {         explainUrlTextField.setText(url);     } } 

Регистрируем модель и контроллер в plugin.xml , для контроллера необходимо указать пункт меню Settings, в котором будут наши настройки, т.е. tools:

<extensions defaultExtensionNs="com.intellij">   <applicationConfigurable parentId="tools"                            instance="com.mgorkov.settings.AppSettingsConfigurable"                            id="com.mgorkov.settings.AppSettingsConfigurable"                            displayName="Explain PostgreSQL"   />   <applicationService serviceImplementation="com.mgorkov.settings.AppSettingsState"/> </extensions>

Отладка плагина

Для вывода сообщений в лог используем Logger :

private static final Logger log = Logger.getInstance(ExplainApiService.class); log.debug("POST JSON: " + jsonObject);

Лог хранится в файле idea.log , открыть который можно через меню Help -> Open Log in Editor

По умолчанию в лог пишутся все события уровня INFO.

Чтобы записать события с уровнем DEBUG надо добавить список имен в Help -> Diagnostic Tools -> Debug Log Settings :

Для включения внутренних команд в IDE надо добавить опцию idea.is.internal=true в Help -> Edit Custom Properties

После перезапуска появится дополнительный пункт меню Tools -> Internal Actions

Теперь при одновременном нажатии Ctrl-Alt-A и щелчке мыши на любом элементе можно посмотреть его состав, как в DevTools браузера

Сборка и публикация плагина

Сборка осуществляется Gradle, при скачивании зависимостей в защищенной корпоративной среде могут быть ошибки типа «not found», для решения надо добавить сертификат в хранилище, используя стандартный пароль «changeit», и перезапустить IDE:

keytool -import -trustcacerts -alias root -file <файл с сертификатом> -keystore <путь к IDE>/jbr/lib/security/cacerts

Конфигурация сборки задается в файле build.gradle.kts , при необходимости можно поменять параметры по умолчанию. Например для варианта сборки с библиотекой json версии 20231013 и тестового запуска плагина в IDE IntelliJ IDEA Ultimate Edition версии 2022.2.5 :

dependencies {   implementation("org.json:json:20231013") }  intellij {   version.set("2022.2.5")   type.set("IU") // Target IDE Platform    plugins.set(listOf("com.intellij.database")) } 

Описание всех опций сборки можно почитать здесь.

Gradle создает набор задач, для которых можно поменять конфигурацию запуска, например чтобы при тестовом запуске IDE лог-файл idea.log отображался в консоли в отдельной вкладке надо поменять конфигурацию задачи runIde и добавить idea.log , путь к которому можно посмотреть в Help -> Show Log in Files:

Для подписи плагина потребуется поменять конфигурацию задачи signPlugin и добавить несколько переменных окружения:

Эти переменные используются при сборке и уже прописаны в build.gradle.kts :

signPlugin {     certificateChain.set(System.getenv("CERTIFICATE_CHAIN"))     privateKey.set(System.getenv("PRIVATE_KEY"))     password.set(System.getenv("PRIVATE_KEY_PASSWORD")) }

Процесс создания подписей есть в документации, но там нет описания для получения значений в виде одной строки, а это можно сделать так:

# строка для переменной PRIVATE_KEY openssl genpkey -aes-256-cbc -algorithm RSA -pkeyopt rsa_keygen_bits:4096 | openssl rsa | tee private.pem | openssl base64 | tr -d '\n'  # строка для CERTIFICATE_CHAIN openssl req -key private.pem -new -x509 -days 365 | openssl base64 | tr -d '\n'

Для проверки совместимости плагина с разными версиями версиями IDE можно использовать задачу verifyPlugin и добавить параметры для нее в конфиг сборки (build.gradle.kts) , например мы хотим проверить плагин в DataGrip версий 2023.3 и 3.1 :

runPluginVerifier {   ideVersions.set(listOf(           "DG-2023.3.1",           "DG-2023.3"   )) }

По умолчанию верификация плагина происходит на сайте plugins.jetbrains.com при загрузке новой версии плагина, на каких версиях производится проверка задается в build.gradle.kts :

patchPluginXml {   sinceBuild.set("222")   untilBuild.set("233.*") }

Можно также запустить проверку на сайте для конкретной версии, например для версий 221.* плагин не совместим из-за отсутствия методов:

Для публикации плагина первичная загрузка производится вручную, собранный файл находится в build/distributions (его кстати можно установить прямо с диска, для этого зайти в Settings -> Plugins -> Install Plugin from Disk)

В дальнейшем можно автоматизировать публикацию, для этого на сайте plugins.jetbrains.com в своем профиле во вкладке Tokens сгенерить токен и прописать его в переменной PUBLISH_TOKEN в конфигурации задачи publishToken.

---

В статье написал обо всех этапах создания плагина, пропустив детали реализации, не относящиеся непосредственно к теме разработки плагинов в IDE JetBrains.

Код плагина опубликован в github под лицензией MIT.

Дополнение: в комментариях к статье обнаружилась непонятная проблема с внешней библиотекой json на M1 MacOS 14 Sonoma — ошибка NoClassDefFoundError при создании

new JSONObject();

Проблему решили заменой библиотеки на Gson , которая входит в состав библиотек во всех IDE JetBrains.