Add progress bar during query execution to track progress. (#63)

Progress bar is run-time SQL-query progress indicator.

Function pg_progress_bar(pid) extracts the current query state from backend with specified 'pid'. Then gets the
numerical values of the actual rows and total rows and count progress for the whole query tree. Function returns
numeric value from 0 to 1 describing the measure of query fulfillment. This function can be used to be embedded
in the PostgreSQL GUI.

To intuitively track progress without using a graphical client, you can use the additionally implemented function
pg_progress_bar_visual(pid, delay). It prints state every period specified by 'delay' (in seconds).

Increase version to 1.2 due to init.sql change.

Author: sokolcati

Makefile

@@ -4,18 +4,20 @@
 MODULE_big = pg_query_state
 OBJS = pg_query_state.o signal_handler.o $(WIN32RES)
 EXTENSION = pg_query_state
-EXTVERSION = 1.1
-DATA = pg_query_state--1.0--1.1.sql
+EXTVERSION = 1.2
+DATA = pg_query_state--1.0--1.1.sql \
+	   pg_query_state--1.1--1.2.sql
 DATA_built = $(EXTENSION)--$(EXTVERSION).sql
 PGFILEDESC = "pg_query_state - facility to track progress of plan execution"
 
 EXTRA_CLEAN = ./isolation_output $(EXTENSION)--$(EXTVERSION).sql \
 	Dockerfile ./tests/*.pyc ./tmp_stress
 
 ISOLATION = corner_cases
-
 ISOLATION_OPTS = --load-extension=pg_query_state
 
+TAP_TESTS = 1
+
 ifdef USE_PGXS
 PG_CONFIG ?= pg_config
 PGXS := $(shell $(PG_CONFIG) --pgxs)

README.md

@@ -321,3 +321,117 @@ Do not hesitate to post your issues, questions and new ideas at the [issues](htt
 ## Authors
 [Maksim Milyutin](https://github.com/maksm90)  
 Alexey Kondratov <a.kondratov@postgrespro.ru> Postgres Professional Ltd., Russia
+
+## Function progress\_bar
+```plpgsql
+pg_progress_bar(
+        integer     pid
+) returns FLOAT
+```
+extracts the current query state from backend with specified 'pid'. Then gets the numerical values of the actual rows and total rows and count progress for the whole query tree. Function returns numeric value from 0 to 1 describing the measure of query fulfillment. If there is no information about current state of the query, or the impossibility of counting, the corresponding messages will be displayed.
+
+## Function progress\_bar\_visual
+```plpgsql
+pg_progress_bar_visual(
+        integer     pid,
+        integer     delay
+) returns VOID
+```
+cyclically extracts and print the current query state in numeric value from backend with specified 'pid' every period specified by 'delay' in seconds. This is the looping version of the progress\_bar function that returns void value.
+
+**_Warning_**: Calling role have to be superuser or member of the role whose backend is being called. Otherwise function prints ERROR message `permission denied`.
+
+## Examples
+Assume first backend executes some function:
+```sql
+postgres=# insert into table_name select generate_series(1,10000000);
+```
+Other backend can get the follow output:
+```sql
+postgres=# SELECT pid FROM pg_stat_activity where query like 'insert%';
+  pid
+-------
+ 23877
+(1 row)
+
+postgres=# SELECT pg_progress_bar(23877);
+ pg_progress_bar
+-----------------
+       0.6087927
+(1 row)
+```
+Or continuous version:
+```sql
+postgres=# SELECT pg_progress_bar_visual(23877, 1);
+Progress = 0.043510
+Progress = 0.085242
+Progress = 0.124921
+Progress = 0.168168
+Progress = 0.213803
+Progress = 0.250362
+Progress = 0.292632
+Progress = 0.331454
+Progress = 0.367509
+Progress = 0.407450
+Progress = 0.448646
+Progress = 0.488171
+Progress = 0.530559
+Progress = 0.565558
+Progress = 0.608039
+Progress = 0.645778
+Progress = 0.654842
+Progress = 0.699006
+Progress = 0.735760
+Progress = 0.787641
+Progress = 0.832160
+Progress = 0.871077
+Progress = 0.911858
+Progress = 0.956362
+Progress = 0.995097
+Progress = 1.000000
+ pg_progress_bar_visual
+------------------------
+                      1
+(1 row)
+```
+Also uncountable queries exist. Assume first backend executes some function:
+```sql
+DELETE from table_name;
+```
+Other backend can get the follow output:
+```sql
+postgres=# SELECT pid FROM pg_stat_activity where query like 'delete%';
+  pid
+-------
+ 23877
+(1 row)
+
+postgres=# SELECT pg_progress_bar(23877);
+INFO:  Counting Progress doesn't available
+ pg_progress_bar
+-----------------
+              -1
+(1 row)
+
+postgres=# SELECT pg_progress_bar_visual(23877, 5);
+INFO:  Counting Progress doesn't available
+ pg_progress_bar_visual
+------------------------
+                      -1
+(1 row)
+```
+
+## Reinstallation
+If you already have a module 'pg_query_state' without progress bar functions installed, execute this in the module's directory:
+```
+make install USE_PGXS=1
+```
+It is essential to restart the PostgreSQL instance. After that, execute the following queries in psql:
+```sql
+DROP EXTENSION IF EXISTS pg_query_state;
+CREATE EXTENSION pg_query_state;
+```
+
+## Authors
+Ekaterina Sokolova <e.sokolova@postgrespro.ru> Postgres Professional Ltd., Russia
+Vyacheslav Makarov <v.makarov@postgrespro.ru> Postgres Professional Ltd., Russia

init.sql

@@ -15,3 +15,14 @@ CREATE FUNCTION pg_query_state(pid 		integer
 				 , leader_pid integer)
 	AS 'MODULE_PATHNAME'
 	LANGUAGE C STRICT VOLATILE;
+
+CREATE FUNCTION pg_progress_bar(pid integer)
+	RETURNS FLOAT
+	AS 'MODULE_PATHNAME'
+	LANGUAGE C STRICT VOLATILE;
+
+CREATE FUNCTION pg_progress_bar_visual(pid		integer
+								  , delay	integer = 1)
+	RETURNS FLOAT
+	AS 'MODULE_PATHNAME', 'pg_progress_bar'
+	LANGUAGE C STRICT VOLATILE;

meson.build

@@ -20,12 +20,11 @@ pg_query_state = shared_module('pg_query_state',
 )
 contrib_targets += pg_query_state
 
-extversion = '1.1'
-output_name = 'pg_query_state--' + extversion + '.sql'
+extversion = '1.2'
 
 configure_file(
   input: 'init.sql',
-  output: output_name,
+  output: 'pg_query_state--' + extversion + '.sql',
   copy: true,
   install: true,
   install_dir: contrib_data_args['install_dir'],
@@ -34,6 +33,7 @@ configure_file(
 install_data(
   'pg_query_state.control',
   'pg_query_state--1.0--1.1.sql',
+  'pg_query_state--1.1--1.2.sql',
   kwargs: contrib_data_args,
 )
 
@@ -50,4 +50,10 @@ tests += {
       '--load-extension=pg_query_state',
     ],
   },
+  'tap': {
+    'tests': [
+      't/001_bad_progress_bar.pl',
+    ],
+    'test_kwargs': {'timeout': 3000},
+  },
 }

pg_query_state--1.1--1.2.sql

@@ -0,0 +1,14 @@
+-- complain if script is sourced in psql, rather than via CREATE EXTENSION
+\echo Use "ALTER EXTENSION pg_query_state UPDATE TO '1.2'" to load this file. \quit
+
+CREATE FUNCTION pg_progress_bar(pid integer)
+	RETURNS FLOAT
+	AS 'MODULE_PATHNAME'
+	LANGUAGE C STRICT VOLATILE;
+
+CREATE FUNCTION pg_progress_bar_visual(pid		integer
+								  , delay	integer = 1)
+	RETURNS FLOAT
+	AS 'MODULE_PATHNAME', 'pg_progress_bar'
+	LANGUAGE C STRICT VOLATILE;
+