amcheck: Fix checks of entry order for GIN indexes
authorTomas Vondra
Tue, 17 Jun 2025 12:55:27 +0000 (14:55 +0200)
committerTomas Vondra
Tue, 17 Jun 2025 12:55:29 +0000 (14:55 +0200)
This tightens a couple checks in checking GIN indexes, which might have
resulted in incorrect results (false positives/negatives).

* The code skipped ordering checks if the entries were for different
  attributes (for multi-column GIN indexes), possibly missing some cases
  of data corruption. But the attribute number is part of the ordering,
  so we can check that.

* The root page was skipped when checking entry order, but that is
  unnecessary. The root page is subject to the same ordering rules, we
  can process it just like any other page.

* The high key on the right-most page was not checked, but that is
  needed only for inner pages (we don't store the high key for those).
  For leaf pages we can check the high key just fine.

* Correct the detection of split pages. If the page gets split, the
  cached parent key is greater than the current child key (not less, as
  the code incorrectly expected).

Issues reported by Arseniy Mukhin, along with a proposed patch. Review
by Andrey M. Borodin, cleanup and improvements by me.

Author: Arseniy Mukhin 
Reviewed-by: Andrey M. Borodin
Discussion: https://postgr.es/m/CAE7r3MJ611B9TE=YqBBncewp7-k64VWs+sjk7XF6fJUX77uFBA@mail.gmail.com

contrib/amcheck/meson.build
contrib/amcheck/t/006_verify_gin.pl [new file with mode: 0644]
contrib/amcheck/verify_gin.c

index b33e8c9b062fe94473894419ecfd14b2fc5f150f..1f0c347ed5413003d39aaa5d25a1403499679ff2 100644 (file)
@@ -49,6 +49,7 @@ tests += {
       't/003_cic_2pc.pl',
       't/004_verify_nbtree_unique.pl',
       't/005_pitr.pl',
+      't/006_verify_gin.pl',
     ],
   },
 }
diff --git a/contrib/amcheck/t/006_verify_gin.pl b/contrib/amcheck/t/006_verify_gin.pl
new file mode 100644 (file)
index 0000000..7fdde17
--- /dev/null
@@ -0,0 +1,199 @@
+
+# Copyright (c) 2021-2025, PostgreSQL Global Development Group
+
+use strict;
+use warnings FATAL => 'all';
+
+use PostgreSQL::Test::Cluster;
+use PostgreSQL::Test::Utils;
+
+use Test::More;
+
+my $node;
+my $blksize;
+
+# to get the split fast, we want tuples to be as large as possible, but the same time we don't want them to be toasted.
+my $filler_size = 1900;
+
+#
+# Test set-up
+#
+$node = PostgreSQL::Test::Cluster->new('test');
+$node->init(no_data_checksums => 1);
+$node->append_conf('postgresql.conf', 'autovacuum=off');
+$node->start;
+$blksize = int($node->safe_psql('postgres', 'SHOW block_size;'));
+$node->safe_psql('postgres', q(CREATE EXTENSION amcheck));
+$node->safe_psql(
+   'postgres', q(
+       CREATE OR REPLACE FUNCTION  random_string( INT ) RETURNS text AS $$
+       SELECT string_agg(substring('0123456789abcdefghijklmnopqrstuvwxyz', ceil(random() * 36)::integer, 1), '') from generate_series(1, $1);
+       $$ LANGUAGE SQL;));
+
+# Tests
+invalid_entry_order_leaf_page_test();
+invalid_entry_order_inner_page_test();
+invalid_entry_columns_order_test();
+
+sub invalid_entry_order_leaf_page_test
+{
+   my $relname = "test";
+   my $indexname = "test_gin_idx";
+
+   $node->safe_psql(
+       'postgres', qq(
+       DROP TABLE IF EXISTS $relname;
+       CREATE TABLE $relname (a text[]);
+       INSERT INTO $relname (a) VALUES ('{aaaaa,bbbbb}');
+       CREATE INDEX $indexname ON $relname USING gin (a);
+    ));
+   my $relpath = relation_filepath($indexname);
+
+   $node->stop;
+
+   my $blkno = 1;  # root
+
+   # produce wrong order by replacing aaaaa with ccccc
+   string_replace_block(
+       $relpath,
+       'aaaaa',
+       'ccccc',
+       $blkno
+   );
+
+   $node->start;
+
+   my ($result, $stdout, $stderr) = $node->psql('postgres', qq(SELECT gin_index_check('$indexname')));
+   my $expected = "index \"$indexname\" has wrong tuple order on entry tree page, block 1, offset 2, rightlink 4294967295";
+   like($stderr, qr/$expected/);
+}
+
+sub invalid_entry_order_inner_page_test
+{
+   my $relname = "test";
+   my $indexname = "test_gin_idx";
+
+   # to break the order in the inner page we need at least 3 items (rightmost key in the inner level is not checked for the order)
+   # so fill table until we have 2 splits
+   $node->safe_psql(
+       'postgres', qq(
+       DROP TABLE IF EXISTS $relname;
+       CREATE TABLE $relname (a text[]);
+       INSERT INTO $relname (a) VALUES (('{' || 'pppppppppp' || random_string($filler_size) ||'}')::text[]);
+       INSERT INTO $relname (a) VALUES (('{' || 'qqqqqqqqqq' || random_string($filler_size) ||'}')::text[]);
+       INSERT INTO $relname (a) VALUES (('{' || 'rrrrrrrrrr' || random_string($filler_size) ||'}')::text[]);
+       INSERT INTO $relname (a) VALUES (('{' || 'ssssssssss' || random_string($filler_size) ||'}')::text[]);
+       INSERT INTO $relname (a) VALUES (('{' || 'tttttttttt' || random_string($filler_size) ||'}')::text[]);
+       INSERT INTO $relname (a) VALUES (('{' || 'uuuuuuuuuu' || random_string($filler_size) ||'}')::text[]);
+       INSERT INTO $relname (a) VALUES (('{' || 'vvvvvvvvvv' || random_string($filler_size) ||'}')::text[]);
+       INSERT INTO $relname (a) VALUES (('{' || 'wwwwwwwwww' || random_string($filler_size) ||'}')::text[]);
+       CREATE INDEX $indexname ON $relname USING gin (a);
+   ));
+   my $relpath = relation_filepath($indexname);
+
+   $node->stop;
+
+   my $blkno = 1;  # root
+
+   # we have rrrrrrrrr... and tttttttttt... as keys in the root, so produce wrong order by replacing rrrrrrrrrr....
+   string_replace_block(
+       $relpath,
+       'rrrrrrrrrr',
+       'zzzzzzzzzz',
+       $blkno
+   );
+
+   $node->start;
+
+   my ($result, $stdout, $stderr) = $node->psql('postgres', qq(SELECT gin_index_check('$indexname')));
+   my $expected = "index \"$indexname\" has wrong tuple order on entry tree page, block 1, offset 2, rightlink 4294967295";
+   like($stderr, qr/$expected/);
+}
+
+sub invalid_entry_columns_order_test
+{
+   my $relname = "test";
+   my $indexname = "test_gin_idx";
+
+   $node->safe_psql(
+       'postgres', qq(
+       DROP TABLE IF EXISTS $relname;
+       CREATE TABLE $relname (a text[],b text[]);
+       INSERT INTO $relname (a,b) VALUES ('{aaa}','{bbb}');
+       CREATE INDEX $indexname ON $relname USING gin (a,b);
+   ));
+   my $relpath = relation_filepath($indexname);
+
+   $node->stop;
+
+   my $blkno = 1;  # root
+
+   # mess column numbers
+   # root items order before: (1,aaa), (2,bbb)
+   # root items order after:  (2,aaa), (1,bbb)
+   my $attrno_1 = pack('s', 1);
+   my $attrno_2 = pack('s', 2);
+
+   my $find = qr/($attrno_1)(.)(aaa)/s;
+   my $replace = $attrno_2 . '$2$3';
+   string_replace_block(
+       $relpath,
+       $find,
+       $replace,
+       $blkno
+   );
+
+   $find = qr/($attrno_2)(.)(bbb)/s;
+   $replace = $attrno_1 . '$2$3';
+   string_replace_block(
+       $relpath,
+       $find,
+       $replace,
+       $blkno
+   );
+
+   $node->start;
+
+   my ($result, $stdout, $stderr) = $node->psql('postgres', qq(SELECT gin_index_check('$indexname')));
+   my $expected = "index \"$indexname\" has wrong tuple order on entry tree page, block 1, offset 2, rightlink 4294967295";
+   like($stderr, qr/$expected/);
+}
+
+# Returns the filesystem path for the named relation.
+sub relation_filepath
+{
+   my ($relname) = @_;
+
+   my $pgdata = $node->data_dir;
+   my $rel = $node->safe_psql('postgres',
+       qq(SELECT pg_relation_filepath('$relname')));
+   die "path not found for relation $relname" unless defined $rel;
+   return "$pgdata/$rel";
+}
+
+# substitute pattern 'find' with 'replace' within the block with number 'blkno' in the file 'filename'
+sub string_replace_block
+{
+   my ($filename, $find, $replace, $blkno) = @_;
+
+   my $fh;
+   open($fh, '+<', $filename) or BAIL_OUT("open failed: $!");
+   binmode $fh;
+
+   my $offset = $blkno * $blksize;
+   my $buffer;
+
+   sysseek($fh, $offset, 0) or BAIL_OUT("seek failed: $!");
+   sysread($fh, $buffer, $blksize) or BAIL_OUT("read failed: $!");
+
+   $buffer =~ s/$find/'"' . $replace . '"'/gee;
+
+   sysseek($fh, $offset, 0) or BAIL_OUT("seek failed: $!");
+   syswrite($fh, $buffer) or BAIL_OUT("write failed: $!");
+
+   close($fh) or BAIL_OUT("close failed: $!");
+
+   return;
+}
+
+done_testing();
index 3f81a8a81d291250044a90d534cbe94861f5f8d7..3f7994a6bc698d366ea7c97939df26342fe7c662 100644 (file)
@@ -459,17 +459,18 @@ gin_check_parent_keys_consistency(Relation rel,
            Datum       parent_key = gintuple_get_key(&state,
                                                      stack->parenttup,
                                                      &parent_key_category);
+           OffsetNumber parent_key_attnum = gintuple_get_attrnum(&state, stack->parenttup);
            ItemId      iid = PageGetItemIdCareful(rel, stack->blkno,
                                                   page, maxoff);
            IndexTuple  idxtuple = (IndexTuple) PageGetItem(page, iid);
-           OffsetNumber attnum = gintuple_get_attrnum(&state, idxtuple);
+           OffsetNumber page_max_key_attnum = gintuple_get_attrnum(&state, idxtuple);
            GinNullCategory page_max_key_category;
            Datum       page_max_key = gintuple_get_key(&state, idxtuple, &page_max_key_category);
 
            if (rightlink != InvalidBlockNumber &&
-               ginCompareEntries(&state, attnum, page_max_key,
-                                 page_max_key_category, parent_key,
-                                 parent_key_category) > 0)
+               ginCompareAttEntries(&state, page_max_key_attnum, page_max_key,
+                                    page_max_key_category, parent_key_attnum,
+                                    parent_key, parent_key_category) < 0)
            {
                /* split page detected, install right link to the stack */
                GinScanItem *ptr;
@@ -508,9 +509,7 @@ gin_check_parent_keys_consistency(Relation rel,
        {
            ItemId      iid = PageGetItemIdCareful(rel, stack->blkno, page, i);
            IndexTuple  idxtuple = (IndexTuple) PageGetItem(page, iid);
-           OffsetNumber attnum = gintuple_get_attrnum(&state, idxtuple);
-           GinNullCategory prev_key_category;
-           Datum       prev_key;
+           OffsetNumber current_attnum = gintuple_get_attrnum(&state, idxtuple);
            GinNullCategory current_key_category;
            Datum       current_key;
 
@@ -523,20 +522,24 @@ gin_check_parent_keys_consistency(Relation rel,
            current_key = gintuple_get_key(&state, idxtuple, ¤t_key_category);
 
            /*
-            * First block is metadata, skip order check. Also, never check
-            * for high key on rightmost page, as this key is not really
-            * stored explicitly.
+            * Compare the entry to the preceding one.
             *
-            * Also make sure to not compare entries for different attnums,
-            * which may be stored on the same page.
+            * Don't check for high key on the rightmost inner page, as this
+            * key is not really stored explicitly.
+            *
+            * The entries may be for different attributes, so make sure to
+            * use ginCompareAttEntries for comparison.
             */
-           if (i != FirstOffsetNumber && attnum == prev_attnum && stack->blkno != GIN_ROOT_BLKNO &&
-               !(i == maxoff && rightlink == InvalidBlockNumber))
+           if ((i != FirstOffsetNumber) &&
+               !(i == maxoff && rightlink == InvalidBlockNumber && !GinPageIsLeaf(page)))
            {
+               Datum       prev_key;
+               GinNullCategory prev_key_category;
+
                prev_key = gintuple_get_key(&state, prev_tuple, &prev_key_category);
-               if (ginCompareEntries(&state, attnum, prev_key,
-                                     prev_key_category, current_key,
-                                     current_key_category) >= 0)
+               if (ginCompareAttEntries(&state, prev_attnum, prev_key,
+                                        prev_key_category, current_attnum,
+                                        current_key, current_key_category) >= 0)
                    ereport(ERROR,
                            (errcode(ERRCODE_INDEX_CORRUPTED),
                             errmsg("index \"%s\" has wrong tuple order on entry tree page, block %u, offset %u, rightlink %u",
@@ -551,13 +554,14 @@ gin_check_parent_keys_consistency(Relation rel,
                i == maxoff)
            {
                GinNullCategory parent_key_category;
+               OffsetNumber parent_key_attnum = gintuple_get_attrnum(&state, stack->parenttup);
                Datum       parent_key = gintuple_get_key(&state,
                                                          stack->parenttup,
                                                          &parent_key_category);
 
-               if (ginCompareEntries(&state, attnum, current_key,
-                                     current_key_category, parent_key,
-                                     parent_key_category) > 0)
+               if (ginCompareAttEntries(&state, current_attnum, current_key,
+                                        current_key_category, parent_key_attnum,
+                                        parent_key, parent_key_category) > 0)
                {
                    /*
                     * There was a discrepancy between parent and child
@@ -576,6 +580,7 @@ gin_check_parent_keys_consistency(Relation rel,
                             stack->blkno, stack->parentblk);
                    else
                    {
+                       parent_key_attnum = gintuple_get_attrnum(&state, stack->parenttup);
                        parent_key = gintuple_get_key(&state,
                                                      stack->parenttup,
                                                      &parent_key_category);
@@ -584,9 +589,9 @@ gin_check_parent_keys_consistency(Relation rel,
                         * Check if it is properly adjusted. If succeed,
                         * proceed to the next key.
                         */
-                       if (ginCompareEntries(&state, attnum, current_key,
-                                             current_key_category, parent_key,
-                                             parent_key_category) > 0)
+                       if (ginCompareAttEntries(&state, current_attnum, current_key,
+                                                current_key_category, parent_key_attnum,
+                                                parent_key, parent_key_category) > 0)
                            ereport(ERROR,
                                    (errcode(ERRCODE_INDEX_CORRUPTED),
                                     errmsg("index \"%s\" has inconsistent records on page %u offset %u",
@@ -638,7 +643,7 @@ gin_check_parent_keys_consistency(Relation rel,
            }
 
            prev_tuple = CopyIndexTuple(idxtuple);
-           prev_attnum = attnum;
+           prev_attnum = current_attnum;
        }
 
        LockBuffer(buffer, GIN_UNLOCK);