Merge pull request #6750 from EnterpriseDB/DOCS-1258-pgd-document-function-bdr-galloc_chunk_info-

Porting galloc content to 5.8

Author: djw-m

product_docs/docs/pgd/5.8/reference/index.json

@@ -373,6 +373,7 @@ The reference section is a definitive listing of all functions, views, and comma
  * [`bdr.extract_nodeid_from_timeshard`](sequences#bdrextract_nodeid_from_timeshard)
  * [`bdr.extract_localseqid_from_timeshard`](sequences#bdrextract_localseqid_from_timeshard)
  * [`bdr.timestamp_to_timeshard`](sequences#bdrtimestamp_to_timeshard)
+ * [`bdr.galloc_chunk_info`](sequences#bdrgalloc_chunk_info)
 ### [KSUUID v2 functions](sequences#ksuuid-v2-functions)
  * [`bdr.gen_ksuuid_v2`](sequences#bdrgen_ksuuid_v2)
  * [`bdr.ksuuid_v2_cmp`](sequences#bdrksuuid_v2_cmp)

product_docs/docs/pgd/5.8/reference/index.mdx

@@ -224,6 +224,31 @@ bdr.timestamp_to_timeshard(ts timestamptz)
 
 This function executes only on the local node.
 
+
+### `bdr.galloc_chunk_info`
+
+This function retrieves the ranges allocated to a galloc sequence on the local
+node.
+
+An empty result set will be returned if the sequence has not yet been accessed
+on the local node.
+
+An ERROR will be raised if the provided sequence name is not a galloc sequence.
+
+#### Synopsis
+
+```sql
+bdr.galloc_chunk_info(seqname regclass)
+```
+
+#### Parameters
+
+- `seqname` - the name of the galloc sequence to query
+
+#### Notes
+
+This function executes only on the local node.
+
 ## KSUUID v2 functions
 
 Functions for working with `KSUUID` v2 data, K-Sortable UUID data. See also [KSUUID in the sequences documentation](../sequences/#ksuuids).

product_docs/docs/pgd/5.8/reference/sequences.mdx

@@ -13,12 +13,12 @@ EDB Postgres Distributed 5.8.0 includes a number of enhancements and bug fixes.
 
 ## Highlights
 
-None yet. 
+* Simpler sequence management with `bdr.galloc_chunk_info()`
 
-## Bug Fixes
+## Enhancements
 
 <table class="table w-100"><thead><tr><th>Component</th><th>Version</th><th>Description</th><th width="10%">Addresses</th></tr></thead><tbody>
-<tr><td>BDR</td><td>5.8.0</td><td>Release note here</td><td></td></tr>
+<tr><td>BDR</td><td>5.8.0</td><td>Added `bdr.galloc_chunk_info()` function to simplify sequences</td><td></td></tr>
 </tbody></table>
 
 

product_docs/docs/pgd/5.8/rel_notes/pgd_5.8.0_rel_notes.mdx

@@ -11,13 +11,16 @@ components:
 intro: |
  EDB Postgres Distributed 5.8.0 includes a number of enhancements and bug fixes.
 highlights: |
-  None yet. 
+  * Simpler sequence management with `bdr.galloc_chunk_info()`
 relnotes:
-- relnote: Release note here
+- relnote: Added `bdr.galloc_chunk_info()` function to simplify sequences
   description: |
-    This is a release note for the EDB Postgres Distributed 5.8.0 release.
-  type: Bug Fix
+    The `bdr.galloc_chunk_info()` function provides information about the chunk
+    allocation for a given sequence. This function returns the chunk ID, the
+    sequence ID, and the chunk size. This function is useful for debugging and
+    understanding how sequences are allocated in BDR.
   component: BDR
-  version: 5.8.0
-  impact: Lowest
-
+  impact: Medium
+  jira: BDR-6144
+  addresses: ""
+  type: Enhancement

product_docs/docs/pgd/5.8/rel_notes/src/relnote_5.8.0.yml

@@ -332,48 +332,32 @@ SELECT * FROM bdr.sequence_alloc
 (1 row)
 ```
 
-To see the ranges currently assigned to a given sequence on each node, use
-these queries:
+
+To see the ranges currently assigned to a given sequence on each node, execute the function
+[`bdr.galloc_chunk_info`](reference/sequences/#bdrgalloc_chunk_info).
 
 * Node `Node1` is using range from `333` to `2000333`.
 
 ```sql
-SELECT last_value AS range_start, log_cnt AS range_end
-    FROM categories_category_seq WHERE ctid = '(0,2)'; -- first range
- range_start | range_end
+SELECT * FROM bdr.galloc_chunk_info('categories_category_seq');
+ chunk_start | chunk_end
 -------------+-----------
          334 |   1000333
-(1 row)
-
-SELECT last_value AS range_start, log_cnt AS range_end
-    FROM categories_category_seq WHERE ctid = '(0,3)'; -- second range
- range_start | range_end
--------------+-----------
      1000334 |   2000333
-(1 row)
+(2 rows)
 ```
 
 * Node `Node2` is using range from `2000334` to `4000333`.
 
 ```sql
-SELECT last_value AS range_start, log_cnt AS range_end
-    FROM categories_category_seq WHERE ctid = '(0,2)'; -- first range
- range_start | range_end
--------------+-----------
-     2000334 |   3000333
-(1 row)
 
-SELECT last_value AS range_start, log_cnt AS range_end
-    FROM categories_category_seq WHERE ctid = '(0,3)'; -- second range
- range_start | range_end
+SELECT * FROM bdr.galloc_chunk_info('categories_category_seq');
+ chunk_start | chunk_end
 -------------+-----------
+     2000334 |   3000333
      3000334 |   4000333
 ```
 
-!!! NOTE 
-    You can't combine it to a single query (like `WHERE ctid IN ('(0,2)', '(0,3)')`),
-    as that still shows only the first range.
-
 When a node finishes a chunk, it asks a consensus for a new one and gets the
 first available. In the example, it's from 4000334 to 5000333. This is
 the new reserved chunk and starts to consume the old reserved chunk.