diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml index caf1ea4cef..5af53dee0f 100644 --- a/doc/src/sgml/brin.sgml +++ b/doc/src/sgml/brin.sgml @@ -16,9 +16,13 @@ BRIN is designed for handling very large tables in which certain columns have some natural correlation with their physical location within the table. + + A block range is a group of pages that are physically adjacent in the table; for each block range, some summary info is stored by the index. + + For example, a table storing a store's sale orders might have a date column on which each order was placed, and most of the time the entries for earlier orders will appear earlier in the table as well; @@ -31,6 +35,8 @@ index scans, and will return all tuples in all pages within each range if the summary info stored by the index is consistent with the query conditions. + + The query executor is in charge of rechecking these tuples and discarding those that do not match the query conditions — in other words, these indexes are lossy. @@ -69,35 +75,88 @@ As new pages are filled with data, page ranges that are already summarized will cause the summary information to be updated with data from the new tuples. + + When a new page is created that does not fall within the last summarized range, that range does not automatically acquire a summary tuple; those tuples remain unsummarized until a summarization run is invoked later, creating initial summaries. - This process can be invoked manually using the - brin_summarize_range(regclass, bigint) or - brin_summarize_new_values(regclass) functions; - automatically when VACUUM processes the table; - or by automatic summarization executed by autovacuum, as insertions - occur. (This last trigger is disabled by default and can be enabled - with the autosummarize parameter.) - Conversely, a range can be de-summarized using the - brin_desummarize_range(regclass, bigint) function, - which is useful when the index tuple is no longer a very good - representation because the existing values have changed. + + This summarization process can happen automatically or be invoked + manually. Manually it is done by calling the following + functions (see for more): + + + + + brin_summarize_range(regclass, bigint) + + + + + brin_summarize_new_values(regclass) + + + + + + Automatically, the process can happen under two circunstances: + + + + + VACUUM + + + When is run manually, it processes the table + and summarization is performed. + + + + + autovacuum + + + The autovacuum process can perform automatic + summarization but that is NOT the default behavior, which is controlled by + the parameter, by + default set to off. + + + In order for the autovacuum process to execute + automatic summarization as insertions occur, the index must have + been created with (or altered to have) the + parameter set to + on. See , + and + for details. + + + + When autosummarization is enabled, each time a page range is filled a - request is sent to autovacuum for it to execute a targeted summarization - for that range, to be fulfilled at the end of the next worker run on the - same database. If the request queue is full, the request is not recorded - and a message is sent to the server log: + request is sent to autovacuum for it to execute a targeted + summarization for that range, to be fulfilled at the end of the next + autovacuum worker run on the same database. If the request queue is full, the + request is not recorded and a message is sent to the server log: LOG: request for BRIN range summarization for index "brin_wi_idx" page 128 was not recorded When this happens, the range will be summarized normally during the next regular vacuum of the table. + + + Conversely, a range can be de-summarized using the + brin_desummarize_range(regclass, bigint) function, + which is useful when the index tuple is no longer a very good + representation because the existing values have changed. + See for details. + + diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index 9ffcdc629e..83b5e82dfb 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -579,7 +579,10 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] Defines whether a summarization run is invoked for the previous page - range whenever an insertion is detected on the next one. + range whenever an insertion is detected on the next one. This also + controls whether the autovacuum process will execute + summarizations. The default is off (see + ). diff --git a/doc/src/sgml/release-15.sgml b/doc/src/sgml/release-15.sgml index 47ac329e79..6da3f89d08 100644 --- a/doc/src/sgml/release-15.sgml +++ b/doc/src/sgml/release-15.sgml @@ -63,11 +63,13 @@ Author: Noah Misch permissions on the public schema has not been changed. Databases restored from previous Postgres releases will be restored with their current permissions. Users wishing - to have the former permissions will need to grant + to have the old permissions on new objects will need to grant CREATE permission for PUBLIC on the public schema; this change can be made on template1 to cause all new databases - to have these permissions. + to have these permissions. template1 + permissions for pg_dumpall and + pg_upgrade? @@ -83,7 +85,7 @@ Author: Noah Misch - Previously it was the literal user name of the bootstrap superuser. + Previously it was the literal user name of the database owner. Databases restored from previous Postgres releases will be restored with their current owner specification.