Thread
Commits
-
Synchronize guc_tables.c categories with vacuum docs categories
- 2ae98ea5ab8f 18.0 landed
-
Reorder vacuum GUCs in postgresql.conf.sample to match docs
- af2317652d5d 18.0 landed
-
Consolidate docs for vacuum-related GUCs in new subsection
- ca9c6a5680d7 18.0 cited
-
pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Melanie Plageman <melanieplageman@gmail.com> — 2025-01-10T23:22:56Z
Consolidate docs for vacuum-related GUCs in new subsection GUCs related to vacuum's freezing behavior were documented in a subsection of the Client Connection Defaults documentation. These GUCs don't belong there, as they affect the freezing behavior of all vacuums -- including autovacuums. There wasn't a clear alternative location, so this commit makes a new "Server Configuration" docs subsection, "Vacuuming", with a subsection for "Freezing". It also moves the "Automatic Vacuuming" subsection and the docs on GUCs controlling cost-based vacuum delay under the new "Vacuuming" subsection. The other vacuum-related GUCs under the "Resource Consumption" subsection have been left in their current location, as they seem to fit there. The GUCs' documentation was largely lifted and shifted. The only modification made was the addition of a few missing <literal> tags. Reviewed-by: Daniel Gustafsson <daniel@yesql.se> Discussion: https://postgr.es/m/flat/CAAKRu_aQUOaMYrcjNuXeSkJtaX9oRUzKP57bsYbC0gVVWS%2BcbA%40mail.gmail.com Branch ------ master Details ------- https://git.postgresql.org/pg/commitdiff/ca9c6a5680d7c7dece0f7209ee7ce20c9dfe0840 Modified Files -------------- doc/src/sgml/config.sgml | 1254 ++++++++++++++++++++++++---------------------- 1 file changed, 643 insertions(+), 611 deletions(-)
-
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Alvaro Herrera <alvherre@alvh.no-ip.org> — 2025-01-11T09:02:50Z
On 2025-Jan-10, Melanie Plageman wrote: > Consolidate docs for vacuum-related GUCs in new subsection Hmm, doesn't this need a corresponding rearrangement of the postgresql.conf.sample file and the GUC grouping in guc_tables.c/h? -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/ "Los cuentos de hadas no dan al niño su primera idea sobre los monstruos. Lo que le dan es su primera idea de la posible derrota del monstruo." (G. K. Chesterton) -
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Daniel Gustafsson <daniel@yesql.se> — 2025-01-12T19:07:21Z
> On 11 Jan 2025, at 10:02, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote: > > On 2025-Jan-10, Melanie Plageman wrote: > >> Consolidate docs for vacuum-related GUCs in new subsection > > Hmm, doesn't this need a corresponding rearrangement of the > postgresql.conf.sample file That's a good point. > and the GUC grouping in guc_tables.c/h? I don't know what our policy around this is, and maybe the backpatching hazard isn't too bad here, but it doesn't entirely seem worth the churn. -- Daniel Gustafsson
-
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Tom Lane <tgl@sss.pgh.pa.us> — 2025-01-12T19:21:07Z
Daniel Gustafsson <daniel@yesql.se> writes: > On 11 Jan 2025, at 10:02, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote: >> and the GUC grouping in guc_tables.c/h? > I don't know what our policy around this is, and maybe the backpatching hazard > isn't too bad here, but it doesn't entirely seem worth the churn. I think the entire point of that categorization is to line up with the docs, so our policy should be to fix this. regards, tom lane
-
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Melanie Plageman <melanieplageman@gmail.com> — 2025-01-13T15:22:15Z
Thanks to Álvaro for pointing this out. I didn't think of it. On Sun, Jan 12, 2025 at 2:21 PM Tom Lane <tgl@sss.pgh.pa.us> wrote: > > Daniel Gustafsson <daniel@yesql.se> writes: > > On 11 Jan 2025, at 10:02, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote: > >> and the GUC grouping in guc_tables.c/h? > > > I don't know what our policy around this is, and maybe the backpatching hazard > > isn't too bad here, but it doesn't entirely seem worth the churn. > > I think the entire point of that categorization is to line up with the > docs, so our policy should be to fix this. I wrote a patch to reorder postgresql.conf.sample. But when I started looking at guc_tables.c, it doesn't seem like those are grouped according to the current docs order. Part of this is because some of the GUCs have different data types. But this appears to be more than that. For example, in master guc_tables.c, autovacuum_vacuum_cost_limit and vacuum_cost_limit are together (in docs in master they were in different sub-sections). Is guc_tables.c meant to be consistent with the ordering in the docs? - Melanie
-
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Melanie Plageman <melanieplageman@gmail.com> — 2025-01-13T19:57:02Z
On Mon, Jan 13, 2025 at 10:22 AM Melanie Plageman <melanieplageman@gmail.com> wrote: > > Thanks to Álvaro for pointing this out. I didn't think of it. > > On Sun, Jan 12, 2025 at 2:21 PM Tom Lane <tgl@sss.pgh.pa.us> wrote: > > > > Daniel Gustafsson <daniel@yesql.se> writes: > > > On 11 Jan 2025, at 10:02, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote: > > >> and the GUC grouping in guc_tables.c/h? > > > > > I don't know what our policy around this is, and maybe the backpatching hazard > > > isn't too bad here, but it doesn't entirely seem worth the churn. > > > > I think the entire point of that categorization is to line up with the > > docs, so our policy should be to fix this. > > I wrote a patch to reorder postgresql.conf.sample. But when I started > looking at guc_tables.c, it doesn't seem like those are grouped > according to the current docs order. Part of this is because some of > the GUCs have different data types. But this appears to be more than > that. For example, in master guc_tables.c, > autovacuum_vacuum_cost_limit and vacuum_cost_limit are together (in > docs in master they were in different sub-sections). Is guc_tables.c > meant to be consistent with the ordering in the docs? Since I didn't hear back about this and I don't see an obvious alternative reorganization in guc_tables.c, I plan to just push the attached patch that updates only postgresql.conf.sample. - Melanie
-
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Alvaro Herrera <alvherre@alvh.no-ip.org> — 2025-01-13T20:46:40Z
On 2025-Jan-13, Melanie Plageman wrote: > Since I didn't hear back about this and I don't see an obvious > alternative reorganization in guc_tables.c, I plan to just push the > attached patch that updates only postgresql.conf.sample. Apologies, I was very unclear -- I didn't want to talk about the ordering of entries in the code, but the categorization. See the config_group_names list in guc_tables.c, which defines some groups. Each setting belongs into a group, and those groups correspond to what the sample config file lists as section/subsection titles and to the grouping in the docs. Also, this categorization affects how the entries are listed in the pg_settings view and in "postgres --describe-config", which feed from the same tables. Perhaps with your changes (assuming I read your commit message right), we need new groups: VACUUMING VACUUMING_FREEZING VACUUMING_AUTOVACUUM Thanks -- Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/ "Doing what he did amounts to sticking his fingers under the hood of the implementation; if he gets his fingers burnt, it's his problem." (Tom Lane)
-
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Melanie Plageman <melanieplageman@gmail.com> — 2025-01-13T22:35:26Z
On Mon, Jan 13, 2025 at 3:46 PM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote: > > On 2025-Jan-13, Melanie Plageman wrote: > > > Since I didn't hear back about this and I don't see an obvious > > alternative reorganization in guc_tables.c, I plan to just push the > > attached patch that updates only postgresql.conf.sample. > > Apologies, I was very unclear -- I didn't want to talk about the > ordering of entries in the code, but the categorization. See the > config_group_names list in guc_tables.c, which defines some groups. > Each setting belongs into a group, and those groups correspond to what > the sample config file lists as section/subsection titles and to the > grouping in the docs. Also, this categorization affects how the entries > are listed in the pg_settings view and in "postgres --describe-config", > which feed from the same tables. Oh dear, I had no idea that these categories existed. I suppose I never paid attention to the category column in pg_settings nor used --describe-config. Attached is a patch to fix this. I checked both pg_settings and --describe-config output, and it seems to work. I'm quite sorry about the extra noise this is causing (especially for people with patch sets requiring rebasing). > Perhaps with your changes (assuming I read your commit message right), > we need new groups: > VACUUMING > VACUUMING_FREEZING > VACUUMING_AUTOVACUUM I've gone with VACUUM_AUTOVACUUM, VACUUM_COST_DELAY, and VACUUM_FREEZING, but I am open to feedback. - Melanie
-
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Alena Rybakina <a.rybakina@postgrespro.ru> — 2025-01-13T23:51:47Z
Hi! On 14.01.2025 01:35, Melanie Plageman wrote: > On Mon, Jan 13, 2025 at 3:46 PM Alvaro Herrera<alvherre@alvh.no-ip.org> wrote: >> On 2025-Jan-13, Melanie Plageman wrote: >> >>> Since I didn't hear back about this and I don't see an obvious >>> alternative reorganization in guc_tables.c, I plan to just push the >>> attached patch that updates only postgresql.conf.sample. >> Apologies, I was very unclear -- I didn't want to talk about the >> ordering of entries in the code, but the categorization. See the >> config_group_names list in guc_tables.c, which defines some groups. >> Each setting belongs into a group, and those groups correspond to what >> the sample config file lists as section/subsection titles and to the >> grouping in the docs. Also, this categorization affects how the entries >> are listed in the pg_settings view and in "postgres --describe-config", >> which feed from the same tables. > Oh dear, I had no idea that these categories existed. I suppose I > never paid attention to the category column in pg_settings nor used > --describe-config. Attached is a patch to fix this. I checked both > pg_settings and --describe-config output, and it seems to work. > > I'm quite sorry about the extra noise this is causing (especially for > people with patch sets requiring rebasing). > >> Perhaps with your changes (assuming I read your commit message right), >> we need new groups: >> VACUUMING >> VACUUMING_FREEZING >> VACUUMING_AUTOVACUUM > I've gone with VACUUM_AUTOVACUUM, VACUUM_COST_DELAY, and > VACUUM_FREEZING, but I am open to feedback. Looks good and convenient, thanks for the patch! I noticed another guc autovacuum_work_mem, which belongs more to the autovacuum category in my opinion, although it belongs to RESOURCES_MEM, but in fact, only autovacuum uses it. -- Regards, Alena Rybakina Postgres Professional
-
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Alvaro Herrera <alvherre@alvh.no-ip.org> — 2025-01-14T18:21:22Z
On 2025-Jan-13, Melanie Plageman wrote: > I've gone with VACUUM_AUTOVACUUM, VACUUM_COST_DELAY, and > VACUUM_FREEZING, but I am open to feedback. Looks good to me. I checked these two queries, whose results appear correct: 55432 18devel 560655=# select name, category from pg_settings where category ilike '%vacuum%'; name │ category ───────────────────────────────────────┼───────────────────────────────────── autovacuum │ Vacuuming / Automatic Vacuuming autovacuum_analyze_scale_factor │ Vacuuming / Automatic Vacuuming autovacuum_analyze_threshold │ Vacuuming / Automatic Vacuuming autovacuum_freeze_max_age │ Vacuuming / Automatic Vacuuming autovacuum_max_workers │ Vacuuming / Automatic Vacuuming autovacuum_multixact_freeze_max_age │ Vacuuming / Automatic Vacuuming autovacuum_naptime │ Vacuuming / Automatic Vacuuming autovacuum_vacuum_cost_delay │ Vacuuming / Automatic Vacuuming autovacuum_vacuum_cost_limit │ Vacuuming / Automatic Vacuuming autovacuum_vacuum_insert_scale_factor │ Vacuuming / Automatic Vacuuming autovacuum_vacuum_insert_threshold │ Vacuuming / Automatic Vacuuming autovacuum_vacuum_scale_factor │ Vacuuming / Automatic Vacuuming autovacuum_vacuum_threshold │ Vacuuming / Automatic Vacuuming autovacuum_worker_slots │ Vacuuming / Automatic Vacuuming vacuum_cost_delay │ Vacuuming / Cost-Based Vacuum Delay vacuum_cost_limit │ Vacuuming / Cost-Based Vacuum Delay vacuum_cost_page_dirty │ Vacuuming / Cost-Based Vacuum Delay vacuum_cost_page_hit │ Vacuuming / Cost-Based Vacuum Delay vacuum_cost_page_miss │ Vacuuming / Cost-Based Vacuum Delay vacuum_failsafe_age │ Vacuuming / Freezing vacuum_freeze_min_age │ Vacuuming / Freezing vacuum_freeze_table_age │ Vacuuming / Freezing vacuum_multixact_failsafe_age │ Vacuuming / Freezing vacuum_multixact_freeze_min_age │ Vacuuming / Freezing vacuum_multixact_freeze_table_age │ Vacuuming / Freezing 55432 18devel 560655=# select name, category from pg_settings where (short_desc ilike '%vacuum%' or extra_desc ilike '%vacuum%') and category not ilike '%vacuum%'; name │ category ─────────────────────────────┼───────────────────────────────────── autovacuum_work_mem │ Resource Usage / Memory log_autovacuum_min_duration │ Reporting and Logging / What to Log maintenance_work_mem │ Resource Usage / Memory vacuum_buffer_usage_limit │ Resource Usage / Memory -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/ "That sort of implies that there are Emacs keystrokes which aren't obscure. I've been using it daily for 2 years now and have yet to discover any key sequence which makes any sense." (Paul Thomas) -
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Melanie Plageman <melanieplageman@gmail.com> — 2025-01-14T19:01:13Z
On Tue, Jan 14, 2025 at 1:21 PM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote: > > On 2025-Jan-13, Melanie Plageman wrote: > > > I've gone with VACUUM_AUTOVACUUM, VACUUM_COST_DELAY, and > > VACUUM_FREEZING, but I am open to feedback. > > Looks good to me. I checked these two queries, whose results appear > correct: > > 55432 18devel 560655=# select name, category from pg_settings where category ilike '%vacuum%'; > name │ category > ───────────────────────────────────────┼───────────────────────────────────── > autovacuum │ Vacuuming / Automatic Vacuuming > autovacuum_analyze_scale_factor │ Vacuuming / Automatic Vacuuming > autovacuum_analyze_threshold │ Vacuuming / Automatic Vacuuming > autovacuum_freeze_max_age │ Vacuuming / Automatic Vacuuming > autovacuum_max_workers │ Vacuuming / Automatic Vacuuming > autovacuum_multixact_freeze_max_age │ Vacuuming / Automatic Vacuuming > autovacuum_naptime │ Vacuuming / Automatic Vacuuming > autovacuum_vacuum_cost_delay │ Vacuuming / Automatic Vacuuming > autovacuum_vacuum_cost_limit │ Vacuuming / Automatic Vacuuming > autovacuum_vacuum_insert_scale_factor │ Vacuuming / Automatic Vacuuming > autovacuum_vacuum_insert_threshold │ Vacuuming / Automatic Vacuuming > autovacuum_vacuum_scale_factor │ Vacuuming / Automatic Vacuuming > autovacuum_vacuum_threshold │ Vacuuming / Automatic Vacuuming > autovacuum_worker_slots │ Vacuuming / Automatic Vacuuming > vacuum_cost_delay │ Vacuuming / Cost-Based Vacuum Delay > vacuum_cost_limit │ Vacuuming / Cost-Based Vacuum Delay > vacuum_cost_page_dirty │ Vacuuming / Cost-Based Vacuum Delay > vacuum_cost_page_hit │ Vacuuming / Cost-Based Vacuum Delay > vacuum_cost_page_miss │ Vacuuming / Cost-Based Vacuum Delay > vacuum_failsafe_age │ Vacuuming / Freezing > vacuum_freeze_min_age │ Vacuuming / Freezing > vacuum_freeze_table_age │ Vacuuming / Freezing > vacuum_multixact_failsafe_age │ Vacuuming / Freezing > vacuum_multixact_freeze_min_age │ Vacuuming / Freezing > vacuum_multixact_freeze_table_age │ Vacuuming / Freezing > > > 55432 18devel 560655=# select name, category from pg_settings where (short_desc ilike '%vacuum%' or extra_desc ilike '%vacuum%') and category not ilike '%vacuum%'; > name │ category > ─────────────────────────────┼───────────────────────────────────── > autovacuum_work_mem │ Resource Usage / Memory > log_autovacuum_min_duration │ Reporting and Logging / What to Log > maintenance_work_mem │ Resource Usage / Memory > vacuum_buffer_usage_limit │ Resource Usage / Memory Yea, Alena also mentioned these GUCs that are in different groups. I think it is okay for these four to remain in their current locations as their current groupings seem descriptive enough. - Melanie
-
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Alvaro Herrera <alvherre@alvh.no-ip.org> — 2025-01-14T19:28:36Z
On 2025-Jan-14, Melanie Plageman wrote: > On Tue, Jan 14, 2025 at 1:21 PM Alvaro Herrera <alvherre@alvh.no-ip.org> wrote: > > 55432 18devel 560655=# select name, category from pg_settings where (short_desc ilike '%vacuum%' or extra_desc ilike '%vacuum%') and category not ilike '%vacuum%'; > > name │ category > > ─────────────────────────────┼───────────────────────────────────── > > autovacuum_work_mem │ Resource Usage / Memory > > log_autovacuum_min_duration │ Reporting and Logging / What to Log > > maintenance_work_mem │ Resource Usage / Memory > > vacuum_buffer_usage_limit │ Resource Usage / Memory > > Yea, Alena also mentioned these GUCs that are in different groups. I > think it is okay for these four to remain in their current locations > as their current groupings seem descriptive enough. I agree. -- Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/ "No hay ausente sin culpa ni presente sin disculpa" (Prov. francés)
-
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Alena Rybakina <a.rybakina@postgrespro.ru> — 2025-01-14T19:29:59Z
On 14.01.2025 22:01, Melanie Plageman wrote: > On Tue, Jan 14, 2025 at 1:21 PM Alvaro Herrera<alvherre@alvh.no-ip.org> wrote: >> On 2025-Jan-13, Melanie Plageman wrote: >> >>> I've gone with VACUUM_AUTOVACUUM, VACUUM_COST_DELAY, and >>> VACUUM_FREEZING, but I am open to feedback. >> Looks good to me. I checked these two queries, whose results appear >> correct: >> >> 55432 18devel 560655=# select name, category from pg_settings where category ilike '%vacuum%'; >> name │ category >> ───────────────────────────────────────┼───────────────────────────────────── >> autovacuum │ Vacuuming / Automatic Vacuuming >> autovacuum_analyze_scale_factor │ Vacuuming / Automatic Vacuuming >> autovacuum_analyze_threshold │ Vacuuming / Automatic Vacuuming >> autovacuum_freeze_max_age │ Vacuuming / Automatic Vacuuming >> autovacuum_max_workers │ Vacuuming / Automatic Vacuuming >> autovacuum_multixact_freeze_max_age │ Vacuuming / Automatic Vacuuming >> autovacuum_naptime │ Vacuuming / Automatic Vacuuming >> autovacuum_vacuum_cost_delay │ Vacuuming / Automatic Vacuuming >> autovacuum_vacuum_cost_limit │ Vacuuming / Automatic Vacuuming >> autovacuum_vacuum_insert_scale_factor │ Vacuuming / Automatic Vacuuming >> autovacuum_vacuum_insert_threshold │ Vacuuming / Automatic Vacuuming >> autovacuum_vacuum_scale_factor │ Vacuuming / Automatic Vacuuming >> autovacuum_vacuum_threshold │ Vacuuming / Automatic Vacuuming >> autovacuum_worker_slots │ Vacuuming / Automatic Vacuuming >> vacuum_cost_delay │ Vacuuming / Cost-Based Vacuum Delay >> vacuum_cost_limit │ Vacuuming / Cost-Based Vacuum Delay >> vacuum_cost_page_dirty │ Vacuuming / Cost-Based Vacuum Delay >> vacuum_cost_page_hit │ Vacuuming / Cost-Based Vacuum Delay >> vacuum_cost_page_miss │ Vacuuming / Cost-Based Vacuum Delay >> vacuum_failsafe_age │ Vacuuming / Freezing >> vacuum_freeze_min_age │ Vacuuming / Freezing >> vacuum_freeze_table_age │ Vacuuming / Freezing >> vacuum_multixact_failsafe_age │ Vacuuming / Freezing >> vacuum_multixact_freeze_min_age │ Vacuuming / Freezing >> vacuum_multixact_freeze_table_age │ Vacuuming / Freezing >> >> >> 55432 18devel 560655=# select name, category from pg_settings where (short_desc ilike '%vacuum%' or extra_desc ilike '%vacuum%') and category not ilike '%vacuum%'; >> name │ category >> ─────────────────────────────┼───────────────────────────────────── >> autovacuum_work_mem │ Resource Usage / Memory >> log_autovacuum_min_duration │ Reporting and Logging / What to Log >> maintenance_work_mem │ Resource Usage / Memory >> vacuum_buffer_usage_limit │ Resource Usage / Memory > Yea, Alena also mentioned these GUCs that are in different groups. I > think it is okay for these four to remain in their current locations > as their current groupings seem descriptive enough. > Looking at them, I am willing to agree with you -- Regards, Alena Rybakina Postgres Professional
-
Re: pgsql: Consolidate docs for vacuum-related GUCs in new subsection
Melanie Plageman <melanieplageman@gmail.com> — 2025-01-14T20:35:39Z
On Tue, Jan 14, 2025 at 2:30 PM Alena Rybakina <a.rybakina@postgrespro.ru> wrote: > > Looking at them, I am willing to agree with you Cool. Thanks to everyone for the review. I've pushed it. - Melanie