From c942d0a4467630dc5488a5238b04d02ec56cffc0 Mon Sep 17 00:00:00 2001 From: eelke Date: Tue, 6 Sep 2022 13:19:09 +0200 Subject: [PATCH] More documentation --- docs/assets/custom.css | 4 ++ docs/conf.py | 6 ++- docs/databasewindow/index.rst | 78 +++++++++++++++++++++++++++++++++++ docs/index.rst | 4 +- docs/preface.rst | 25 +++++++++++ 5 files changed, 115 insertions(+), 2 deletions(-) create mode 100644 docs/assets/custom.css create mode 100644 docs/databasewindow/index.rst create mode 100644 docs/preface.rst diff --git a/docs/assets/custom.css b/docs/assets/custom.css new file mode 100644 index 0000000..623e050 --- /dev/null +++ b/docs/assets/custom.css @@ -0,0 +1,4 @@ +.menuselection { + font-weight: 100 + +} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index ae3d2cb..9356f1f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,4 +53,8 @@ html_theme = 'furo' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [] +html_static_path = ['assets'] + +html_css_files = [ + 'custom.css' +] \ No newline at end of file diff --git a/docs/databasewindow/index.rst b/docs/databasewindow/index.rst new file mode 100644 index 0000000..cc98557 --- /dev/null +++ b/docs/databasewindow/index.rst @@ -0,0 +1,78 @@ +############### +Database Window +############### + +When opening a database connection the program will open a database window. +Within this window you can only work in a single database and with global +server objects like for instance roles. + +The window start with a single query tab. + +************* +The Query tab +************* + +In the query tab you can enter your queries and execute them with :kbd:`F5` or +:menuselection:`Query --> Execute query`. You can use postgresql's native query +parameters that consist of a `$` followed by a number. The values for these +parameters can be entered in the list to the right of the query editor. +Note that when using parameters postgresql will not accept multiple queries. + +A new query tab can be opened with :kbd:`Ctrl+N` or :menuselection:`File --> New query`. + +Queries can also be saved with :kbd:`Ctrl+S` or :menuselection:`File --> Save query` +and opened with :kbd:`Ctrl+O` or :menuselection:`File --> Open query`. You can also +drag and drop a bunch of files onto the window and they will be opened in +seperate query tabs. + +Explain +======= + +You can get a user friendly version of explain output with :kbd:`F7` or :menuselection:`Query --> Explain`. +If you want explain analyze use :kbd:`Shift+F7` or :menuselection:`Query --> Explain analyze`. + +Colors are used to highlight the explain nodes that take the most time. Also +keep an eye on the estimation error a high error can indicate stale statistics. + + +************ +Schema views +************ + +Schema views van be opened from the :menuselection:`View` menu. These views all work +in the same way and get their data from the postgres catalog. The only difference +is the filter used. + +User schema + Shows all objects that are not part of a system namespace like pg_catalog or + information schema. + +pg_catalog + This is the native postgresql catalog. + +information_schema + This is the SQL compatible catalog. + +The grids within the schema tabs should all be sortable. Click on the header of +a column to sort by the contents of that column. Click a second time to reverse +the sort order. + +Tables +====== + + +Note the sizes are retrieved in the background and can take some time to appear +on large databases. + +Columns +------- + +On the columns tab you can see ofcourse the columns of the table. Note that +this table has as its last columns a column for each index on the table. The +cells contain the position of the table column represented by that row in the +index. Hover over the header to see the name of the index. + +When a row is selected SQL for dropping or creating that column and also +to just fix the default or NULL constraint this is useful when inspecting +one database to correct another. When multiple rows are selected SQL for all +those rows is shown. diff --git a/docs/index.rst b/docs/index.rst index cf75cbd..aa39253 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,15 +4,17 @@ contain the root `toctree` directive. pgLab User Manual -==================================================== +================= .. toctree:: :maxdepth: 3 :caption: Contents: + preface releasenotes installation connectionmanager/index + databasewindow/index internals Indices and tables diff --git a/docs/preface.rst b/docs/preface.rst new file mode 100644 index 0000000..8bbca97 --- /dev/null +++ b/docs/preface.rst @@ -0,0 +1,25 @@ +####### +Preface +####### + +************* +What is pgLab +************* + +pgLab is a PostgreSQL database query tool that also has some views for inspecting +the database schema. It does not provide dialogs for creating new database objects +you can ofcourse execute DDL to create anything you like. +(Note adding dialogs for creating objects is a lot of work. I am not against it +but it has currently no priority for me.) + +The strong point of pgLab are: +* seperation of different databases into seperate windows. +* inspecting of database with subtabs in a single main tab so the list of toplevel tabs stays short. +* very fast processing of query results millions of rows are no problem. + +************** +What is it not +************** + +If you are unfamiliar with the SQL and need dialogs for doing anything this +is not the tool for you and you are much better of using pgAdmin.