PyCharm 2024.1 Help

Sessions

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 aren't available, make sure that you didn't disable the plugin.

  1. Press Ctrl+Alt+S 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.

In PyCharm, connections to the database are established in special wrappers — sessions. Each session is a wrapper over a single connection, and it stores the connection's information (for example, whether it is active or not, transaction control mode, and other settings).

Within a session, connections can open and close when required and in accordance with the defined settings.

Sessions can have clients — files, whose queries are sent via the connection that the session holds. Data editor can also be a client for a session.

You can view data sources, sessions, and session clients in the Services tool window. Green dot in the corner of session's icon indicates a connected session.

The Services tool window

In the picture above, the Services tool window displays the following nodes:

  1. Data source.

  2. Disconnected session.

  3. Connected session.

  4. Session clients.

For more information about the session managing options and toolbar controls, refer to Services tool window controls.

If you close PyCharm and open it again, all your sessions will be available in the Services tool window, but they will be empty.

New session

Depending on the way you create a new session, it can be connected either automatically, or after a certain action. Green dot in the corner of session's icon indicates the connected status.

You can create a new session by doing either of the following:

  • Open a query console, view database object's data in data editor, or attach an SQL file to a data source.

    As a result, under the data source node in the Services tool window, the new session node appears with a client node under it.

    1. For a query console, the session will be connected once you perform an action that requires interaction with the database. For example, once you run a query.

    2. For a table, the session is connected automatically, as PyCharm requires an active connection to request the table data from the database, receive it, and display it in the data editor.

    3. For an SQL file, the session is connected automatically. To run queries against either of the data source databases or schemas, you have to attach your file to them by selecting them in the <schema> list.

  • Perform an action that requires interaction with the database. For example, run a stored procedure or run a script via run configurations.

    As a result, the new connected session node appears under the data source node in the Services tool window.

Manage sessions

Switch sessions

In case you need to run your queries or SQL file in a different session, you can switch the session to another one.

  • To switch the session, in the Services tool window, right-click the file that you want to switch the session for, click Switch Session and select the session that you want to attach the file to.

Switch sessions for an SQL file in the Services tool window

Work in a single session

You can run queries from multiple SQL files and receive multiple database objects data in a single session. For example, if each new query requires an MFA approval.

To work in a single session, enable the single session mode by doing the following:

  1. Open the Data Sources and Drivers dialog (Shift+Enter) and select your data source.

  2. On the right pane of the dialog, open the Options tab.

  3. In the Connection settings section, select the Single session mode checkbox.

  4. Click OK to apply the changes.

  5. (Optional) If the Apply Changes dialog appears, select the way you want to proceed.

    the Apply Changes dialog
    • No: Leaves the connected sessions intact.

    • Yes: Disconnects all the connected sessions.

  6. Run your queries.

All new queries will run in the default session.

Queries from multiple SQL files run in a sigle session

The following table includes other basic actions that you can use to work with sessions.

Action

Description

Rename a session

In the Services tool window, right-click a session and select Rename Session.

Rename a connection session

Move a session or a data source to a separate tab

In the Services tool window, right-click a session or a data source and select Open in New Tab. To revert this action, close the separated tab.

Move a session or a data source to a separate tab

Close a session

In the Services tool window, right-click a session and select Close Session.

The session will be detached from its session clients, it will also disappear from the list.

Close all sessions

In the Services tool window, right-click a data source and select Close All Sessions.

Close all connection sessions

Services tool window controls

For more information about the Services tool window, refer to the Services tool window topic.

Database services in the Services tool window

Left toolbar controls

Icon

Action and shortcut

Description

The Jump to Console button

Jump to Query Console Ctrl+Shift+F10

Open the Query Consoles popup. In the Query Consoles popup, you can select a query console that you want to open in the editor.

the Deactivate icon

Deactivate Ctrl+F2

Close the database connection for the selected data source or data sources. (The data sources with connected sessions are indicated with a green dot in the corner of their icon.)

Icon

Action and shortcut

Description

Tx

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

Ctrl+F2

Terminate execution of the current statement or statements.

the Restore Default Layout button

Restore Default Layout

Restore default positions of visual elements in the tool window.

Context menu

Icon

Action and shortcut

Description

The Jump to Console button

Jump to Query Console Ctrl+Shift+F10

Open the Query Consoles popup. In the Query Consoles popup, you can select a query console that you want to open in the editor.

the Deactivate icon

Deactivate Ctrl+F2

Close the database connection for the selected data source or data sources. (The data sources with connected sessions are indicated with a green dot in the corner of their icon.)

Close All Sessions

Close all opened sessions to a data source.

Open in New Tab

Move the selected items to a separate tab.

Open Each in New Tab

Split the selected items into separate tabs.

Open Each Type in New Tab

Create separate tabs for each type of service.

Delete Delete

Close all opened sessions to a data source. Identical to Close All Sessions.

Icon

Action and shortcut

Description

Tx

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

Ctrl+F2

Terminate execution of the current statement or statements.

the Restore Default Layout button

Restore Default Layout

Restore default positions of visual elements in the tool window.

Rename Session Shift+F6

Display the Rename Session '<session_name>' dialog where you can specify a name for a session.

Close Session

Close the selected session.

Open in New Tab

Move the selected items to a separate tab.

Open Each in New Tab

Split the selected items into separate tabs.

Open Each Type in New Tab

Create separate tabs for each type of service.

Delete Delete

Close all opened sessions to a data source. Identical to Close All Sessions.

Icon

Action and shortcut

Description

Tx

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

Ctrl+F2

Terminate execution of the current statement or statements.

the Restore Default Layout button

Restore Default Layout

Restore default positions of visual elements in the tool window.

Attach Session

Attach the selected file to one of the available sessions. To detach the file from a session, open the file in the editor, click the <session> list and select Detach Session.

Open in New Tab

Move the selected items to a separate tab.

Open Each in New Tab

Split the selected items into separate tabs.

Open Each Type in New Tab

Create separate tabs for each type of service.

Delete Delete

Close all opened sessions to a data source. Identical to Close All Sessions.

the Jump to Source button

Jump to Source F4

Open the file in the editor.

Last modified: 23 May 2024