Query consoles

Last modified: 11 October 2024

Enable the Database Tools and SQL plugin

This functionality relies on the Database Tools and SQL plugin, which is bundled and enabled in PyCharm by default. If the relevant features are not available, make sure that you did not disable the plugin.

note

The Database Tools and SQL plugin is available only in PyCharm Professional.

  1. Press to open settings and then select Plugins.

  2. Open the Installed tab, find the Database Tools and SQL plugin, and select the checkbox next to the plugin name.

Overview

Query or database consoles are SQL files that are attached to a data source. You can write and execute SQL statements in query consoles the same way as you do it in terminal. The consoles are not included in the project context.

When you create a data source, the data source's default query console is created automatically. If necessary, you can create additional query consoles.

Query console

Each console creates a new connection session. If you do not want to create new connections, enable single session mode.

All the created query consoles are located in the internal Database Consoles directory. To open this folder, open the Project tool window () and navigate to Scratches and Consoles | Database Consoles. On your machine, the query console files are stored in the consoles subdirectory of the IDE configuration directory.

For more information about working with query results in query consoles, refer to Query results.

Database connection session

For each console, a database connection session is created automatically. You can create new connection sessions and attach your console to existing ones in the console toolbar.

In the following example, the PostgreSQL console is associated with the guest.public schema of a data source and connected to it via the console connection session. You can change the console session to actor or create a new session and attach the console to it.

Change the connection session

Code editor

The code editor is where you compose your SQL statements using the resolve modes and coding assistance features, and execute them against the associated data source.

Find the code editor toolbar controls in Code editor controls. Read more about the editor in Editor basics.

SQL statement execution

When you execute a statement, the Services tool window opens. The Services tool window displays available connection sessions, Output and Result tabs. For more information about the Services tool windows, refer to Services tool window.

  • If the executed statement retrieves data (for example, SELECT), results are displayed in the Result tab that has a title of a qualified table name. For more information about creating custom titles for result tabs, refer to Use custom titles for tabs with results.

  • If the executed statement does not retrieve data, results are displayed in the Output tab.

    Query console with an active Result tab of Services tool window

    1. Query console tab toolbar.

    2. Code editor.

    3. Services tool window.

    4. Output and Result tabs. Result tab is active.

    5. Result tab toolbar.

Work with console files

Create a query console

To create a console, use one of the following actions in the Database tool window ( View | Tool Windows | Database).

  • Click a data source and select File | New | Query Console.

  • Right-click a data source and select New | Query Console.

  • Click a data source, press , and select Query Console.

  • Click a data source, press , and select New Query Console.

  • Click a data source and press .

note

New console means a new connection to a data source. You can work with just one connection for the data source and have all consoles use that same one connection. Read more about the single session mode in Single session mode.

Open a console

When a console is open, you can write SQL here, run it and get the result.

  • In the Project tool window ( View | Tool Windows | Project) , navigate to Scratches and Consoles | Database Consoles | <data_source_name>, double-click a console file.

  • In the Database tool window ( View | Tool Windows | Database) , click the Jump to Query Console button (the Jump to Query Console icon ) and select a console that you want to open or create a new one.

  • Click a data source, press , and select the console that you need.

    Open a console

Rename a query console

To rename a query console file, do one of the following:

  • Right-click a console tab, and select Rename File.

  • Open the Project tool window ( View | Tool Windows | Project) and navigate to Scratches and Consoles | Database Consoles. Expand a data source group that includes your console, right-click the console file, and select Refactor | Rename ().

    Rename a query console file

Group consoles under the data source directory

  1. In the Project tool window ( View | Tool Windows | Project) , navigate to Scratches and Consoles | Database Consoles.

  2. Right-click a data source group where you want to create a new directory, select New | Directory.

  3. Specify a name of the directory.

  4. Select and drag console files to the directory.

  5. In the Move dialog, click Refactor.

    Group consoles under the data source directory

Delete a query console

  1. In the Project tool window ( View | Tool Windows | Project) , navigate to Scratches and Consoles | Database Consoles.

  2. Expand a data source group that includes your console.

  3. Right-click a console file and select Delete.

Copy a console file to a new location

  1. In the Project tool window ( View | Tool Windows | Project) , navigate to Scratches and Consoles | Database Consoles.

  2. Expand a data source group that includes your console.

  3. Right-click a console file and select Refactor | Copy File.

  4. In the To directory field, specify a new location for the file.

    Copy a console file to a new location

Open a console file in the file browser

To open a console file in your file browser, do one of the following:

  • Right-click a console tab and navigate to Open In | <file_browser>.

  • Open the Project tool window ( View | Tool Windows | Project) and navigate to Scratches and Consoles | Database Consoles. Expand a data source group that includes your console, right-click the console file, and select Open In | <file_browser>.

Open a console file in the file browser

Configure console settings

Change a schema

  • In the query console toolbar, open the list of databases and schemas by clicking the <schema> button and select the one that you want to run queries against.

    For more information about schemas, refer to Schemas.

    Change a schema

Modify console settings

  • Open a console and click the Open Query Execution Settings... button (the Open Database Settings icon).

Configure console dialects

Change the SQL dialect in the code editor

note

For query consoles, SQL dialect is defined by a data source that is attached to the console. It can only be changed for the Oracle consoles.

  • Right-click the editing area and select Change Dialect (<current_dialect>) to. In the Change SQL Dialect window, select a dialect.

Productivity tips

View history of a query console

  • In a console, right-click any area and select Local History | Show History.

Apply a code style in the editor

  • Right-click any area or a selection of code in the editor and select Reformat Code. Alternatively, press .

    Apply a code style in the editor

View the file path of a query console

  • To see the details of a file, hover over the console tab.

  • Press , select Project View and press .

Edit data in INSERT statements as a table

  1. Select INSERT statements that you want to edit.

  2. Right-click the selection and click Edit as Table.

    Edit data in INSERT statements as a table

  3. In the table editor that opens, make necessary changes in the table cell. Press to confirm.

Context menu

In the code editor context menu, use the following actions to increase your productivity:

Action

Shortcut

Description

Edit as Table

In INSERT statements, opens the editor for working with the data in a table format.

Change Dialect (<CurrentDialect>)

Change the SQL dialect. Select a dialect from the list.

Explain Plan

  • Explain Plan: show an execution plan (or explain plan) for the current statement. The result is shown in a mixed tree/table format on a dedicated Plan tab.

    To build a diagram of the execution plan, click the Show Diagram icon (the Show Diagram icon) on the left of the Plan tab, or press .

    To build a flame graph, click the Flame Graph button (the Flame Graph icon).

  • Explain Plan (Raw): show an execution plan (or explain plan) for the current statement. The result is shown in table format. Technically, EXPLAIN <CURRENT_STATEMENT> or similar statement is executed.

the Execute icon Execute

Execute the current statement or the sequence of selected statements.

the Execute to File icon Execute to File

Execute the current statement and save results in a text file. Select the output format and specify the file location and name.

Run 'console [data_source]'

Execute all the statements in the query console.

Query console reference

Use the code editor to compose and execute your SQL statements as well as to perform other associated tasks.

Read more about the editor in Editor basics.

Toolbar controls

Icon

Action and shortcut

Description

the Execute button

Execute

Execute selected SQL statement or statements.

If nothing is selected, the current statement is executed.

the Browse Query History button

Browse Query History

Open a dialog that shows all the statements that you have run for the corresponding data source.

See also, Use the Query History dialog.

the View Parameters button

View Parameters

Open or close the Parameters dialog.

For more information about user parameters, refer to the Run queries topic.

the Open Query Execution Settings button

Open Query Execution Settings

Open the Tools | Database | Query Execution section of the Settings dialog to view or edit the query execution settings.

For more information about these settings, refer to Query Execution.

Transaction mode

Transaction Mode

and

Transaction Isolation

Select the isolation level for database transactions and the way the transactions are committed.

  • Auto: the current transaction is committed automatically when you submit your local changes to the database server.

  • Manual: the changes submitted to the database server are accumulated in a transaction that can either be committed or rolled back explicitly by means of the Submit and Commit (the Submit and Commit icon) or Roll Back (the Roll Back button) buttons on the toolbar.

For more information about database transaction modes and isolation, refer to Submit changes to a database.

the Commit icon

Commit

(For the Manual transaction mode.) Commit the current transaction. This button is available only for the manual transaction mode. See also, transaction mode and isolation.

the Roll back icon

Roll back

(For the Manual transaction mode.) Roll back changes. This button is available only for the manual transaction mode. See also, transaction modes and isolation.

the Cancel Running Statements icon

Cancel Running Statements

Terminate execution of the current statement or statements.

Playground

File Resolve Mode

Select the resolve mode to manage the context that database objects in your code are resolved to.

  • Playground: default mode for query consoles. All the database objects are resolved to the same context.

  • Script: default mode for local SQL files. The USE SQL statement (SET search_path TO for PostgreSQL) overrides the default context that the database objects are resolved to.

For more information about the resolve modes, refer to Resolve modes.

In the following video, the public schema is selected as default for the query console. The schema contains the actor table, whereas the information_schema schema does not contain it. When the resolve mode is Playground, the database object is resolved to default schema in both SELECT statements, because all the statements are considered unrelated.

Once the resolve mode is changed to Script, the second SELECT statement is considered related to the SET search_path TO information_schema one. The actor table is no longer resolved in that statement.

In-Editor Results

Toggle the display of query result within the code editor of query console.

For more information about the in-editor results, refer to In-Editor Results.

the Schema icon <schema>

Switch current schema

Select the default schema or database. For PostgreSQL, Amazon Redshift, and Greenplum use the <schema> list to form the schema search path.

Select a search path for PostgreSQL

For more information about schemas, refer to Schemas.

the Session icon <session>

Switch attached session

Select the database connection session.

For more information about the database connection sessions, refer to Managing connection sessions

See also

Procedures

Reference

Language and Framework-Specific Guidelines