Для пользователей 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.