-- pg_isok  A query centered monitoring tool for PostgreSQL
-- Copyright (C) 2025 The Meme Factory, Inc.  http://www.karlpinc.com/
--
--  This program is free software: you can redistribute it and/or modify
--  it under the terms of the GNU Affero General Public License as published
--  by the Free Software Foundation, either version 3 of the License, or
--  (at your option) any later version.
--
--  This program is distributed in the hope that it will be useful,
--  but WITHOUT ANY WARRANTY; without even the implied warranty of
--  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
--  GNU Affero General Public License for more details.
--
--  You should have received a copy of the GNU Affero General Public License
--  along with this program.  If not, see <https://www.gnu.org/licenses/>.
--
-- Karl O. Pinc <kop@karlpinc.com>
--
-- Remarks:
--   Hand-written comments.
--   Note that comments extracted from the documentation are appended
--   to this file.
--
--   Line breaks at 50 columns, since that's what format_comments.gawk does.

--
-- Support table columns.
--

-- IQ_TYPES
COMMENT ON COLUMN iq_types.iqtype IS
  'A classification code attached to a query in the
ISOK_QUERIES table.';
  
COMMENT ON COLUMN iq_types.description IS
  'A description of the IQType code.';

-- IRTypes
COMMENT ON COLUMN ir_types.irtype IS
  'A classification code attached to a query result
row in the ISOK_RESULTS table.';

COMMENT ON COLUMN ir_types.description IS
  'A description of the IRType code.';

--
-- Comment the functions used by people
--

-- run_isok_queries()

COMMENT ON FUNCTION run_isok_queries() IS
  'Execute all the queries in the ISOK_QUERIES table and
return a table of the results.';

COMMENT ON FUNCTION run_isok_queries(query TEXT) IS
  'Execute the supplied query, which produces a single
column of ISOK_QUERIES.IQName values, and then
execute all the queries in the ISOK_QUERIES table
with those IQName values, returning a table of the
result of the executed queries.';

--
-- Comment the functions used by triggers
--

COMMENT ON FUNCTION isok_queries_update_func() IS
  'Internal function: Implements an AFTER UPDATE FOR EACH
ROW trigger on ISOK_QUERIES';

COMMENT ON FUNCTION isok_results_func() IS
  'Internal function: Implements an AFTER INSERT OR UPDATE
FOR EACH ROW trigger on ISOK_RESULTS';

--
-- Everything that follows is extracted from the documentation.
--
COMMENT ON TABLE ISOK_QUERIES IS
$isok_comment$The ISOK_QUERIES table contains one row for every
query used to search for database integrity
issues.$isok_comment$;

COMMENT ON COLUMN ISOK_QUERIES.IQName IS
$isok_comment$A unique name for the query.$isok_comment$;

COMMENT ON COLUMN ISOK_QUERIES.Error IS
$isok_comment$TRUE when the query finds conditions that are
errors, FALSE when the query finds conditions that
are warnings.$isok_comment$;

COMMENT ON COLUMN ISOK_QUERIES.Type IS
$isok_comment$Code classifying the query. The legal values for
this column are defined by the IQ_TYPES support
table.$isok_comment$;

COMMENT ON COLUMN ISOK_QUERIES.First_Run IS
$isok_comment$Date and time the query was first run by Isok.$isok_comment$;

COMMENT ON COLUMN ISOK_QUERIES.Last_Run IS
$isok_comment$Date and time the query was most recently run by
Isok.$isok_comment$;

COMMENT ON COLUMN ISOK_QUERIES.Keep IS
$isok_comment$This column controls the value placed in the
ISOK_RESULTS.Keep_Until column when
run_isok_queries() inserts new rows in
ISOK_RESULTS.$isok_comment$;

COMMENT ON COLUMN ISOK_QUERIES.Role IS
$isok_comment$The PostgreSQL role to use to run the query.$isok_comment$;

COMMENT ON COLUMN ISOK_QUERIES.Search_Path IS
$isok_comment$The PostgreSQL schema search_path to have in
effect when the query is run.$isok_comment$;

COMMENT ON COLUMN ISOK_QUERIES.Query IS
$isok_comment$A query which checks for database integrity
violations.$isok_comment$;

COMMENT ON COLUMN ISOK_QUERIES.Comment IS
$isok_comment$A comment on the query.$isok_comment$;

COMMENT ON TABLE ISOK_RESULTS IS
$isok_comment$The ISOK_RESULTS table contains one row for every
database integrity problem discovered by the
queries in ISOK_QUERIES.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.IRID IS
$isok_comment$This column uniquely identifies the row containing
the$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.IQName IS
$isok_comment$The ISOK_QUERIES.IQName value identifying the
query which produced the result.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.First_Seen IS
$isok_comment$Date and time the query result was first produced
by Isok.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.Last_Seen IS
$isok_comment$Date and time the query result was most recently
produced by Isok.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.Last_Role IS
$isok_comment$The role (user) which was the current role when
the query was last executed.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.Last_Schemas IS
$isok_comment$All schemas that were, implicitly or not, in the
search_path, and also available to the Last_Role,
when the result was returned.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.Resolved IS
$isok_comment$Date and time the query result was resolved; that
is, marked not a concern.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.Deferred_To IS
$isok_comment$Isok suppresses display of the result when the
current time is before this time.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.Type IS
$isok_comment$Code classifying the query result. The legal
values for this column are defined by the IR_TYPES
support table.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.Keep_Until IS
$isok_comment$This column controls whether or not
run_isok_queries() deletes the row when the
ISOK_QUERIES.Query is re-run and the query does
not return the row's QR_ID.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.QR_ID IS
$isok_comment$This is a unique, unique per query that is,
identifier for the query result.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.QR_Message IS
$isok_comment$This is the message, the second column, produced
by the most recent execution of the
ISOK_QUERIES.Query.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.QR_Extra IS
$isok_comment$The value of the third, optional, column returned
by most recent execution of the query. This may
contain any JSON deemed useful.$isok_comment$;

COMMENT ON COLUMN ISOK_RESULTS.Notes IS
$isok_comment$Any notes regarding this particular query result.$isok_comment$;

COMMENT ON TABLE IQ_TYPES IS
$isok_comment$IQ_TYPES contains one row for every code used to
classify database integrity queries.$isok_comment$;

COMMENT ON TABLE IR_TYPES IS
$isok_comment$IR_TYPES contains one row for every code used to
classify or explain sets of database integrity
problems, problems discovered by Isok's queries.$isok_comment$;

