diff --git a/docs/en_US/query_tool.rst b/docs/en_US/query_tool.rst index cdd8b7ce8..d0662701b 100644 --- a/docs/en_US/query_tool.rst +++ b/docs/en_US/query_tool.rst @@ -1,10 +1,14 @@ .. _query_tool: ******************* -`Query tool`:index: +`Query Tool`:index: ******************* -The Query tool is a powerful, feature-rich environment that allows you to execute arbitrary SQL commands and review the result set. You can access the Query tool via the *Query Tool* menu option on the *Tools* menu, or through the context menu of select nodes of the Browser tree control. The Query Tool allows you to: +The Query Tool is a powerful, feature-rich environment that allows you to +execute arbitrary SQL commands and review the result set. You can access the +Query Tool via the *Query Tool* menu option on the *Tools* menu, or through the +context menu of select nodes of the Browser tree control. The Query Tool +allows you to: * Issue ad-hoc SQL queries. * Execute arbitrary SQL commands. @@ -16,16 +20,29 @@ The Query tool is a powerful, feature-rich environment that allows you to execut .. image:: images/query_tool.png :alt: Query tool window -You can open multiple copies of the Query tool in individual tabs simultaneously. To close a copy of the Query tool, click the *X* in the upper-right hand corner of the tab bar. +You can open multiple copies of the Query tool in individual tabs +simultaneously. To close a copy of the Query tool, click the *X* in the +upper-right hand corner of the tab bar. The Query Tool features two panels: -* The upper panel displays the *SQL Editor*. You can use the panel to enter, edit, or execute a query. -* The lower panel displays the *Data Output* panel. The tabbed panel displays the result set returned by a query, information about a query's execution plan, server messages related to the query's execution, and a history of the queries invoked in the SQL Editor. +* The upper panel displays the *SQL Editor*. You can use the panel to enter, + edit, or execute a query. It also shows the *History* tab which can be used + to view the queries that have been executed in the session, and a *Scratch Pad* + which can be used to hold text snippets during editing. If the Scratch Pad is + closed, it can be re-opened (or additional ones opened) by right-clicking in + the SQL Editor and other panels and adding a new panel. +* The lower panel displays the *Data Output* panel. The tabbed panel displays + the result set returned by a query, information about a query's execution plan, + server messages related to the query's execution and any asynchronous + notifications received from the server. **The Query Tool Toolbar** -The *Query Tool* toolbar uses context-sensitive icons that provide shortcuts to frequently performed tasks. If an icon is highlighted, the option is enabled; if the icon is grayed-out, the task is disabled. Please note that disabled icons may support functionality accessed via the :ref:`data editor `. +The *Query Tool* toolbar uses context-sensitive icons that provide shortcuts to +frequently performed tasks. If an icon is highlighted, the option is enabled; +if the icon is grayed-out, the task is disabled. Please note that disabled +icons may support functionality accessed via the :ref:`data editor `. .. image:: images/query_toolbar.png :alt: Query tool toolbar @@ -129,69 +146,102 @@ Hover over an icon to display a tooltip that describes the icon's functionality: **The SQL Editor Panel** -The *SQL editor* panel is a workspace where you can manually provide a query, copy a query from another source, or read a query from a file. The SQL editor features syntax coloring and autocompletion. +The *SQL editor* panel is a workspace where you can manually provide a query, +copy a query from another source, or read a query from a file. The SQL editor +features syntax coloring and autocompletion. .. image:: images/query_sql_editor.png :alt: Query tool editor -To use autocomplete, begin typing your query; when you would like the Query editor to suggest object names or commands that might be next in your query, press the Control+Space key combination. For example, type "\*SELECT \* FROM\* " (without quotes, but with a trailing space), and then press the Control+Space key combination to select from a popup menu of autocomplete options. +To use autocomplete, begin typing your query; when you would like the Query +editor to suggest object names or commands that might be next in your query, +press the Control+Space key combination. For example, type "\*SELECT \* FROM\* " +(without quotes, but with a trailing space), and then press the Control+Space +key combination to select from a popup menu of autocomplete options. .. image:: images/query_autocomplete.png :alt: Query tool autocomplete feature -After entering a query, select the *Execute/Refresh* icon from the toolbar. The complete contents of the SQL editor panel will be sent to the database server for execution. To execute only a section of the code that is displayed in the SQL editor, highlight the text that you want the server to execute, and click the *Execute/Refresh* icon. +After entering a query, select the *Execute/Refresh* icon from the toolbar. The +complete contents of the SQL editor panel will be sent to the database server +for execution. To execute only a section of the code that is displayed in the +SQL editor, highlight the text that you want the server to execute, and click +the *Execute/Refresh* icon. .. image:: images/query_execute_section.png :alt: Query tool execute query section -The message returned by the server when a command executes is displayed on the *Messages* tab. If the command is successful, the *Messages* tab displays execution details. +The message returned by the server when a command executes is displayed on the +*Messages* tab. If the command is successful, the *Messages* tab displays +execution details. .. image:: images/query_tool_message.png :alt: Query tool message panel -Options on the *Edit* menu offer functionality that helps with code formatting and commenting: +Options on the *Edit* menu offer functionality that helps with code formatting +and commenting: -* The auto-indent feature will automatically indent text to the same depth as the previous line when you press the Return key. +* The auto-indent feature will automatically indent text to the same depth as + the previous line when you press the Return key. * Block indent text by selecting two or more lines and pressing the Tab key. -* Implement or remove SQL style or toggle C style comment notation within your code. +* Implement or remove SQL style or toggle C style comment notation within your + code. **The Data Output Panel** -The *Data Output* panel displays data and statistics generated by the most recently executed query. +The *Data Output* panel displays data and statistics generated by the most +recently executed query. .. image:: images/query_output_data.png :alt: Query tool output panel -The *Data Output* tab displays the result set of the query in a table format. You can: +The *Data Output* tab displays the result set of the query in a table format. +You can: * Select and copy from the displayed result set. -* Use the *Execute/Refresh* options to retrieve query execution information and set query execution options. -* Use the *Download as CSV* icon to download the content of the *Data Output* tab as a comma-delimited file. +* Use the *Execute/Refresh* options to retrieve query execution information and + set query execution options. +* Use the *Download as CSV* icon to download the content of the *Data Output* + tab as a comma-delimited file. -All rowsets from previous queries or commands that are displayed in the *Data Output* panel will be discarded when you invoke another query; open another query tool browser tab to keep your previous results available. +All rowsets from previous queries or commands that are displayed in the *Data +Output* panel will be discarded when you invoke another query; open another +query tool browser tab to keep your previous results available. Use the *Explain* tab to view a graphical representation of a query: .. image:: images/query_output_explain.png :alt: Query tool explain panel -To generate a graphical explain diagram, open the *Explain* tab, and select *Explain*, *Explain Analyze*, or one or more options from the *Explain options* menu on the *Execute/Refresh* drop-down. Please note that *EXPLAIN VERBOSE* cannot be displayed graphically. Hover over an icon on the *Explain* tab to review information about that item; a popup window will display information about the selected object: +To generate a graphical explain diagram, open the *Explain* tab, and select +*Explain*, *Explain Analyze*, or one or more options from the *Explain options* +menu on the *Execute/Refresh* drop-down. Please note that *EXPLAIN VERBOSE* +cannot be displayed graphically. Hover over an icon on the *Explain* tab to +review information about that item; a popup window will display information +about the selected object: + +Use the download button on top left corner of the *Explain* canvas to download +the plan as an SVG file. -Use the download button on top left corner of the *Explain* canvas to download the plan as an SVG file. **Note:** Download as SVG is not supported on Internet Explorer. .. image:: images/query_output_explain_details.png :alt: Query tool graphical explain plan -Note that the query plan that accompanies the *Explain analyze* is available on the *Data Output* tab. +Note that the query plan that accompanies the *Explain analyze* is available on +the *Data Output* tab. -Use the *Messages* tab to view information about the most recently executed query: +Use the *Messages* tab to view information about the most recently executed +query: .. image:: images/query_output_error.png :alt: Query tool output messages -If the server returns an error, the error message will be displayed on the *Messages* tab, and the syntax that caused the error will be underlined in the SQL editor. If a query succeeds, the *Messages* tab displays how long the query took to complete and how many rows were retrieved: +If the server returns an error, the error message will be displayed on the +*Messages* tab, and the syntax that caused the error will be underlined in the +SQL editor. If a query succeeds, the *Messages* tab displays how long the +query took to complete and how many rows were retrieved: .. image:: images/query_output_messages.png :alt: Query tool output information @@ -206,12 +256,15 @@ The Query History tab displays information about recent commands: * The date and time that a query was invoked. * The text of the query. * The number of rows returned by the query. -* The amount of time it took the server to process the query and return a result set. +* The amount of time it took the server to process the query and return a + result set. * Messages returned by the server (not noted on the *Messages* tab). -To erase the content of the *Query History* tab, select *Clear history* from the *Clear* drop-down menu. +To erase the content of the *Query History* tab, select *Clear history* from +the *Clear* drop-down menu. -Use the *Connection status* feature to view the current connection and transaction status by clicking on the status icon in query tool: +Use the *Connection status* feature to view the current connection and +transaction status by clicking on the status icon in query tool: .. image:: images/query_tool_connection_status.png :alt: Query tool connection and transaction statuses \ No newline at end of file diff --git a/docs/en_US/release_notes_4_3.rst b/docs/en_US/release_notes_4_3.rst index 1117b7144..1f3a3bd53 100644 --- a/docs/en_US/release_notes_4_3.rst +++ b/docs/en_US/release_notes_4_3.rst @@ -10,6 +10,7 @@ Features ******** | `Feature #1825 `_ - Install a script to start pgAdmin (pgadmin4) from the command line when installed from the Python wheel. +| `Feature #2233 `_ - Add a "scratch pad" to the Query Tool to hold text snippets whilst editing. | `Feature #3439 `_ - Allow X-FRAME-OPTIONS to be set for security. Default to SAMEORIGIN. | `Feature #3559 `_ - Automatically expand child nodes as well as the selected node on the treeview if there is only one. | `Feature #3991 `_ - Update Alpine Linux version in the docker container. This also updates the PG utilities to v11. diff --git a/web/pgadmin/tools/sqleditor/static/css/sqleditor.css b/web/pgadmin/tools/sqleditor/static/css/sqleditor.css index 337c6582c..81e63c338 100644 --- a/web/pgadmin/tools/sqleditor/static/css/sqleditor.css +++ b/web/pgadmin/tools/sqleditor/static/css/sqleditor.css @@ -14,6 +14,21 @@ bottom: 0; } +.sql-scratch { + width: 100%; + height: 100%; + box-sizing: border-box; + overflow-y: hidden; +} + +.sql-scratch textarea { + width: 100%; + height: 100%; + box-sizing: border-box; + border: none; + resize: none; +} + .sql-editor-grid-container { height: 100%; overflow: auto; diff --git a/web/pgadmin/tools/sqleditor/static/js/sqleditor.js b/web/pgadmin/tools/sqleditor/static/js/sqleditor.js index 97a8e1859..65ea1629b 100644 --- a/web/pgadmin/tools/sqleditor/static/js/sqleditor.js +++ b/web/pgadmin/tools/sqleditor/static/js/sqleditor.js @@ -8,8 +8,8 @@ ////////////////////////////////////////////////////////////// define('tools.querytool', [ - 'babel-polyfill', 'sources/gettext', 'sources/url_for', 'jquery', - 'underscore', 'underscore.string', 'pgadmin.alertifyjs', + 'babel-polyfill', 'sources/gettext', 'sources/url_for', 'jquery', 'jquery.ui', + 'jqueryui.position', 'underscore', 'underscore.string', 'pgadmin.alertifyjs', 'sources/pgadmin', 'backbone', 'sources/../bundle/codemirror', 'pgadmin.misc.explain', 'sources/selection/grid_selector', @@ -44,7 +44,7 @@ define('tools.querytool', [ 'pgadmin.browser', 'pgadmin.tools.user_management', ], function( - babelPollyfill, gettext, url_for, $, _, S, alertify, pgAdmin, Backbone, codemirror, + babelPollyfill, gettext, url_for, $, jqueryui, jqueryui_position, _, S, alertify, pgAdmin, Backbone, codemirror, pgExplain, GridSelector, ActiveCellCapture, clipboard, copyData, RangeSelectionHelper, handleQueryOutputKeyboardEvent, XCellSelectionModel, setStagedRows, SqlEditorUtils, ExecuteQuery, httpErrorHandler, FilterHandler, GeometryViewer, HistoryBundle, queryHistory, React, ReactDOM, @@ -168,7 +168,7 @@ define('tools.querytool', [ // Create main wcDocker instance var main_docker = new wcDocker( '#editor-panel', { - allowContextMenu: false, + allowContextMenu: true, allowCollapse: false, loadingClass: 'pg-sp-icon', themePath: url_for('static', { @@ -182,8 +182,8 @@ define('tools.querytool', [ var sql_panel = new pgAdmin.Browser.Panel({ name: 'sql_panel', title: gettext('Query Editor'), - width: '100%', - height: '50%', + width: '75%', + height: '33%', isCloseable: false, isPrivate: true, }); @@ -267,6 +267,16 @@ define('tools.querytool', [ content: '
', }); + var scratch = new pgAdmin.Browser.Panel({ + name: 'scratch', + title: gettext('Scratch Pad'), + width: '25%', + height: '100%', + isCloseable: true, + isPrivate: false, + content: '
', + }); + var notifications = new pgAdmin.Browser.Panel({ name: 'notifications', title: gettext('Notifications'), @@ -292,6 +302,7 @@ define('tools.querytool', [ explain.load(main_docker); messages.load(main_docker); history.load(main_docker); + scratch.load(main_docker); notifications.load(main_docker); geometry_viewer.load(main_docker); @@ -301,6 +312,7 @@ define('tools.querytool', [ self.messages_panel = main_docker.addPanel('messages', wcDocker.DOCK.STACKED, self.data_output_panel); self.notifications_panel = main_docker.addPanel('notifications', wcDocker.DOCK.STACKED, self.data_output_panel); self.history_panel = main_docker.addPanel('history', wcDocker.DOCK.STACKED, sql_panel_obj); + self.scratch_panel = main_docker.addPanel('scratch', wcDocker.DOCK.RIGHT, sql_panel_obj); self.render_history_grid(); queryToolNotifications.renderNotificationsGrid(self.notifications_panel);