From bdf43f23022268166c74714cc9889c5753748fc1 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 23 Mar 2026 13:22:45 -0400 Subject: [PATCH v8 2/2] Improve comment headers for generated SQL inside psql. Label generated queries as "INTERNAL QUERY", reserving the plain "QUERY" label for user-entered commands. Fix a few generated queries in command.c to follow the labeling convention we're establishing. (I looked through the other uses of PSQLexec(), but the rest all issue quite trivial commands that don't seem to need a gloss, such as BEGIN or COMMIT.) Copy-edit some of Greg's proposed headers to improve uniformity. Also add headers to a couple of queries that were missed. If I've not messed up, every PSQLexec() in describe.c now has a header comment. --- src/bin/psql/command.c | 14 ++++--- src/bin/psql/common.c | 4 +- src/bin/psql/describe.c | 84 +++++++++++++++++++++++++++-------------- 3 files changed, 66 insertions(+), 36 deletions(-) diff --git a/src/bin/psql/command.c b/src/bin/psql/command.c index 37e2241edf6..493400f9090 100644 --- a/src/bin/psql/command.c +++ b/src/bin/psql/command.c @@ -6158,14 +6158,14 @@ echo_hidden_command(const char *query) { if (pset.echo_hidden != PSQL_ECHO_HIDDEN_OFF) { - printf(_("/******** QUERY *********/\n" + printf(_("/**** INTERNAL QUERY ****/\n" "%s\n" "/************************/\n\n"), query); fflush(stdout); if (pset.logfile) { fprintf(pset.logfile, - _("/******** QUERY *********/\n" + _("/**** INTERNAL QUERY ****/\n" "%s\n" "/************************/\n\n"), query); fflush(pset.logfile); @@ -6202,6 +6202,7 @@ lookup_object_oid(EditableObjectType obj_type, const char *desc, * query to retrieve the function's OID using a cast to regproc or * regprocedure (as appropriate). */ + printfPQExpBuffer(query, "/* %s */\n", _("Get function's OID")); appendPQExpBufferStr(query, "SELECT "); appendStringLiteralConn(query, desc, pset.db); appendPQExpBuffer(query, "::pg_catalog.%s::pg_catalog.oid", @@ -6215,6 +6216,7 @@ lookup_object_oid(EditableObjectType obj_type, const char *desc, * this code doesn't check if the relation is actually a view. * We'll detect that in get_create_object_cmd(). */ + printfPQExpBuffer(query, "/* %s */\n", _("Get view's OID")); appendPQExpBufferStr(query, "SELECT "); appendStringLiteralConn(query, desc, pset.db); appendPQExpBufferStr(query, "::pg_catalog.regclass::pg_catalog.oid"); @@ -6256,7 +6258,8 @@ get_create_object_cmd(EditableObjectType obj_type, Oid oid, switch (obj_type) { case EditableFunction: - printfPQExpBuffer(query, + printfPQExpBuffer(query, "/* %s */\n", _("Get function's definition")); + appendPQExpBuffer(query, "SELECT pg_catalog.pg_get_functiondef(%u)", oid); break; @@ -6275,9 +6278,10 @@ get_create_object_cmd(EditableObjectType obj_type, Oid oid, * separately. Materialized views (introduced in 9.3) may have * arbitrary storage parameter reloptions. */ + printfPQExpBuffer(query, "/* %s */\n", _("Get view's definition and details")); if (pset.sversion >= 90400) { - printfPQExpBuffer(query, + appendPQExpBuffer(query, "SELECT nspname, relname, relkind, " "pg_catalog.pg_get_viewdef(c.oid, true), " "pg_catalog.array_remove(pg_catalog.array_remove(c.reloptions,'check_option=local'),'check_option=cascaded') AS reloptions, " @@ -6290,7 +6294,7 @@ get_create_object_cmd(EditableObjectType obj_type, Oid oid, } else { - printfPQExpBuffer(query, + appendPQExpBuffer(query, "SELECT nspname, relname, relkind, " "pg_catalog.pg_get_viewdef(c.oid, true), " "c.reloptions AS reloptions, " diff --git a/src/bin/psql/common.c b/src/bin/psql/common.c index 2eadd391a9c..476e7fe6737 100644 --- a/src/bin/psql/common.c +++ b/src/bin/psql/common.c @@ -664,14 +664,14 @@ PSQLexec(const char *query) if (pset.echo_hidden != PSQL_ECHO_HIDDEN_OFF) { - printf(_("/******** QUERY *********/\n" + printf(_("/**** INTERNAL QUERY ****/\n" "%s\n" "/************************/\n\n"), query); fflush(stdout); if (pset.logfile) { fprintf(pset.logfile, - _("/******** QUERY *********/\n" + _("/**** INTERNAL QUERY ****/\n" "%s\n" "/************************/\n\n"), query); fflush(pset.logfile); diff --git a/src/bin/psql/describe.c b/src/bin/psql/describe.c index f09cd49850c..b9f43daf0bc 100644 --- a/src/bin/psql/describe.c +++ b/src/bin/psql/describe.c @@ -1067,7 +1067,8 @@ permissionsList(const char *pattern, bool showSystem) /* * we ignore indexes and toast tables since they have no meaningful rights */ - printfPQExpBuffer(&buf, "/* %s */\n", _("Get matching access privileges")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get access privileges of matching tables")); appendPQExpBuffer(&buf, "SELECT n.nspname as \"%s\",\n" " c.relname as \"%s\",\n" @@ -1507,7 +1508,7 @@ describeTableDetails(const char *pattern, bool verbose, bool showSystem) initPQExpBuffer(&buf); - printfPQExpBuffer(&buf, "/* %s */\n", _("Get matching relations to describe")); + printfPQExpBuffer(&buf, "/* %s */\n", _("Get matching tables to describe")); appendPQExpBuffer(&buf, "SELECT c.oid,\n" " n.nspname,\n" @@ -1644,7 +1645,8 @@ describeOneTableDetails(const char *schemaname, initPQExpBuffer(&tmpbuf); /* Get general table info */ - printfPQExpBuffer(&buf, "/* %s */\n", _("Get general relation information")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get general information about one table")); if (pset.sversion >= 120000) { appendPQExpBuffer(&buf, @@ -1971,7 +1973,8 @@ describeOneTableDetails(const char *schemaname, { PGresult *result; - printfPQExpBuffer(&buf, + printfPQExpBuffer(&buf, "/* %s */\n", _("Get property graph definition")); + appendPQExpBuffer(&buf, "SELECT pg_catalog.pg_get_propgraphdef('%s'::pg_catalog.oid);", oid); result = PSQLexec(buf.data); @@ -2019,7 +2022,8 @@ describeOneTableDetails(const char *schemaname, * duplicative test logic below. */ cols = 0; - printfPQExpBuffer(&buf, "/* %s */\n", _("Get columns for this relation")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get per-column information for one table")); appendPQExpBuffer(&buf, "SELECT a.attname"); attname_col = cols++; appendPQExpBufferStr(&buf, ",\n pg_catalog.format_type(a.atttypid, a.atttypmod)"); @@ -2322,7 +2326,8 @@ describeOneTableDetails(const char *schemaname, /* Footer information for a partition child table */ PGresult *result; - printfPQExpBuffer(&buf, "/* %s */\n", _("Get partition information for this table")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get partitioning information for this partition")); appendPQExpBuffer(&buf, "SELECT inhparent::pg_catalog.regclass,\n" " pg_catalog.pg_get_expr(c.relpartbound, c.oid),\n "); @@ -2378,7 +2383,9 @@ describeOneTableDetails(const char *schemaname, /* Footer information for a partitioned table (partitioning parent) */ PGresult *result; - printfPQExpBuffer(&buf, + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get partitioning information for this table")); + appendPQExpBuffer(&buf, "SELECT pg_catalog.pg_get_partkeydef('%s'::pg_catalog.oid);", oid); result = PSQLexec(buf.data); @@ -2400,7 +2407,8 @@ describeOneTableDetails(const char *schemaname, /* For a TOAST table, print name of owning table */ PGresult *result; - printfPQExpBuffer(&buf, "/* %s */\n", _("Get the table which owns this TOAST table")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get the table that owns this TOAST table")); appendPQExpBuffer(&buf, "SELECT n.nspname, c.relname\n" "FROM pg_catalog.pg_class c" @@ -2656,8 +2664,8 @@ describeOneTableDetails(const char *schemaname, /* print table (and column) check constraints */ if (tableinfo.checks) { - - printfPQExpBuffer(&buf, "/* %s */\n", _("Get check constraints")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get check constraints for this table")); appendPQExpBuffer(&buf, "SELECT r.conname, " "pg_catalog.pg_get_constraintdef(r.oid, true)\n" @@ -2689,7 +2697,8 @@ describeOneTableDetails(const char *schemaname, } /* Print foreign-key constraints */ - printfPQExpBuffer(&buf, "/* %s */\n", _("Get foreign key constraints")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get foreign key constraints for this table")); if (pset.sversion >= 120000 && (tableinfo.ispartition || tableinfo.relkind == RELKIND_PARTITIONED_TABLE)) { @@ -2760,7 +2769,8 @@ describeOneTableDetails(const char *schemaname, PQclear(result); /* print incoming foreign-key references */ - printfPQExpBuffer(&buf, "/* %s */\n", _("Get foreign keys referencing this table")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get foreign keys referencing this table")); if (pset.sversion >= 120000) { appendPQExpBuffer(&buf, @@ -2812,7 +2822,8 @@ describeOneTableDetails(const char *schemaname, /* print any row-level policies */ if (pset.sversion >= 90500) { - printfPQExpBuffer(&buf, "/* %s */\n", _("Get row-level policies for this table")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get row-level policies for this table")); appendPQExpBuffer(&buf, "SELECT pol.polname,"); if (pset.sversion >= 100000) appendPQExpBufferStr(&buf, @@ -2893,9 +2904,10 @@ describeOneTableDetails(const char *schemaname, } /* print any extended statistics */ - printfPQExpBuffer(&buf, "/* %s */\n", _("Get extended statistics for this table")); if (pset.sversion >= 140000) { + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get extended statistics for this table")); appendPQExpBuffer(&buf, "SELECT oid, " "stxrelid::pg_catalog.regclass, " @@ -2994,6 +3006,8 @@ describeOneTableDetails(const char *schemaname, } else if (pset.sversion >= 100000) { + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get extended statistics for this table")); appendPQExpBuffer(&buf, "SELECT oid, " "stxrelid::pg_catalog.regclass, " @@ -3157,7 +3171,8 @@ describeOneTableDetails(const char *schemaname, /* print any publications */ if (pset.sversion >= 100000) { - printfPQExpBuffer(&buf, "/* %s */\n", _("Get publications that use this table")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get publications that publish this table")); if (pset.sversion >= 150000) { appendPQExpBuffer(&buf, @@ -3303,7 +3318,8 @@ describeOneTableDetails(const char *schemaname, */ if (verbose) { - printfPQExpBuffer(&buf, "/* %s */\n", _("Get not null constraints for this table")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get not-null constraints for this table")); appendPQExpBuffer(&buf, "SELECT c.conname, a.attname, c.connoinherit,\n" " c.conislocal, c.coninhcount <> 0,\n" @@ -3353,7 +3369,8 @@ describeOneTableDetails(const char *schemaname, { PGresult *result; - printfPQExpBuffer(&buf, + printfPQExpBuffer(&buf, "/* %s */\n", _("Get view's definition")); + appendPQExpBuffer(&buf, "SELECT pg_catalog.pg_get_viewdef('%s'::pg_catalog.oid, true);", oid); result = PSQLexec(buf.data); @@ -3599,7 +3616,8 @@ describeOneTableDetails(const char *schemaname, char *ftoptions; /* Footer information about foreign table */ - printfPQExpBuffer(&buf, "/* %s */\n", _("Get foreign server")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get foreign server for this table")); appendPQExpBuffer(&buf, "SELECT s.srvname,\n" " pg_catalog.array_to_string(ARRAY(\n" @@ -3635,7 +3653,8 @@ describeOneTableDetails(const char *schemaname, } /* print tables inherited from (exclude partitioned parents) */ - printfPQExpBuffer(&buf, "/* %s */\n", _("Get parent tables")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get inheritance parent tables")); appendPQExpBuffer(&buf, "SELECT c.oid::pg_catalog.regclass\n" "FROM pg_catalog.pg_class c, pg_catalog.pg_inherits i\n" @@ -3869,7 +3888,9 @@ add_tablespace_footer(printTableContent *const cont, char relkind, PQExpBufferData buf; initPQExpBuffer(&buf); - printfPQExpBuffer(&buf, + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get tablespace information for this table")); + appendPQExpBuffer(&buf, "SELECT spcname FROM pg_catalog.pg_tablespace\n" "WHERE oid = '%u';", tablespace); result = PSQLexec(buf.data); @@ -4238,7 +4259,7 @@ listTables(const char *tabtypes, const char *pattern, bool verbose, bool showSys initPQExpBuffer(&buf); - printfPQExpBuffer(&buf, "/* %s */\n", _("Get matching relations")); + printfPQExpBuffer(&buf, "/* %s */\n", _("Get matching tables")); appendPQExpBuffer(&buf, "SELECT n.nspname as \"%s\",\n" " c.relname as \"%s\",\n" @@ -4698,7 +4719,7 @@ listLanguages(const char *pattern, bool verbose, bool showSystem) initPQExpBuffer(&buf); - printfPQExpBuffer(&buf, "/* %s */\n", _("Get matching languages")); + printfPQExpBuffer(&buf, "/* %s */\n", _("Get matching procedural languages")); appendPQExpBuffer(&buf, "SELECT l.lanname AS \"%s\",\n" " pg_catalog.pg_get_userbyid(l.lanowner) as \"%s\",\n" @@ -5489,7 +5510,8 @@ listSchemas(const char *pattern, bool verbose, bool showSystem) PGresult *result; int i; - printfPQExpBuffer(&buf, "/* %s */\n", _("Get publications that use this schema")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get publications that publish this schema")); appendPQExpBuffer(&buf, "SELECT pubname \n" "FROM pg_catalog.pg_publication p\n" @@ -6439,7 +6461,7 @@ listExtensions(const char *pattern) initPQExpBuffer(&buf); - printfPQExpBuffer(&buf, "/* %s */\n", _("Get matching extensions")); + printfPQExpBuffer(&buf, "/* %s */\n", _("Get matching installed extensions")); appendPQExpBuffer(&buf, "SELECT e.extname AS \"%s\", " "e.extversion AS \"%s\", ae.default_version AS \"%s\"," @@ -6565,7 +6587,7 @@ listOneExtensionContents(const char *extname, const char *oid) initPQExpBuffer(&buf); - printfPQExpBuffer(&buf, "/* %s */\n", _("Get installed extension details")); + printfPQExpBuffer(&buf, "/* %s */\n", _("Get installed extension's contents")); appendPQExpBuffer(&buf, "SELECT pg_catalog.pg_describe_object(classid, objid, 0) AS \"%s\"\n" "FROM pg_catalog.pg_depend\n" @@ -6963,7 +6985,8 @@ describePublications(const char *pattern) if (!puballtables) { /* Get the tables for the specified publication */ - printfPQExpBuffer(&buf, "/* %s */\n", _("Get tables used by this publication")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get tables published by this publication")); appendPQExpBuffer(&buf, "SELECT n.nspname, c.relname"); if (pset.sversion >= 150000) { @@ -7000,7 +7023,8 @@ describePublications(const char *pattern) if (pset.sversion >= 150000) { /* Get the schemas for the specified publication */ - printfPQExpBuffer(&buf, "/* %s */\n", _("Get schemas used by this publication")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get schemas published by this publication")); appendPQExpBuffer(&buf, "SELECT n.nspname\n" "FROM pg_catalog.pg_namespace n\n" @@ -7017,7 +7041,8 @@ describePublications(const char *pattern) if (pset.sversion >= 190000) { /* Get tables in the EXCEPT clause for this publication */ - printfPQExpBuffer(&buf, "/* %s */\n", _("Get tables excluded by this publication")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get tables excluded by this publication")); appendPQExpBuffer(&buf, "SELECT n.nspname || '.' || c.relname\n" "FROM pg_catalog.pg_class c\n" @@ -7548,7 +7573,8 @@ listOpFamilyFunctions(const char *access_method_pattern, initPQExpBuffer(&buf); - printfPQExpBuffer(&buf, "/* %s */\n", _("Get matching support functions of operator families")); + printfPQExpBuffer(&buf, "/* %s */\n", + _("Get support functions of matching operator families")); appendPQExpBuffer(&buf, "SELECT\n" " am.amname AS \"%s\",\n" -- 2.43.7