Add a check for tables with incrementing column names [schemacrawler] (#852)

* Add a check for tables with incrementing column names [schemacrawler]

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Implement check for tables with incrementing column names [schemacrawler]

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Fix lint violations in DatabaseStructureChecksAutoConfiguration

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Fix imports

* Fix tests

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mfvanek

.claude/rules/javadoc.md

@@ -0,0 +1,27 @@
+# Rules for Javadoc
+
+Applies to: all Java source files in `src/main/java/`
+
+## @since tag must reflect the current project version (JAVADOC_SINCE_MUST_MATCH_PROJECT_VERSION)
+
+Every new public class and every new public method added to an existing class must carry a `@since` Javadoc tag.
+
+**Determining the version:**
+
+1. Open the root `build.gradle.kts` file.
+2. Read the value of the `version` property (e.g., `version = "0.41.1"`).
+3. Use that exact string as the `@since` value.
+
+Example — if `build.gradle.kts` contains `version = "0.41.1"`:
+
+```java
+/**
+ * Check for tables with incrementing column names on a specific host.
+ *
+ * @author Ivan Vakhrushev
+ * @since 0.41.1
+ */
+public class TablesWithIncrementingColumnsCheckOnHost extends AbstractCheckOnHost<TableWithColumns> {
+```
+
+Do **not** hardcode a version from memory or a previous session. Always read `build.gradle.kts` at the time of writing to get the current value.

doc/available_checks.md

@@ -55,6 +55,7 @@ All checks can be divided into two groups:
 | 41 | Tables with no data                                                                                                                | **runtime**        | yes                   | [sql](https://github.com/mfvanek/pg-index-health-sql/blob/master/sql/tables_with_no_data.sql)                         |
 | 42 | Self-referenced foreign keys without `ON DELETE CASCADE` or `ON DELETE SET NULL`                                                   | static             | yes                   | [sql](https://github.com/mfvanek/pg-index-health-sql/blob/master/sql/self_referenced_foreign_keys.sql)                |
 | 43 | Columns that use [large object types (BLOB/CLOB)](https://www.postgresql.org/docs/current/largeobjects.html)                       | static             | yes                   | [sql](https://github.com/mfvanek/pg-index-health-sql/blob/master/sql/columns_with_blob_type.sql)                      |
+| 44 | Tables with incrementing column names                                                                                              | static             | yes                   | [sql](https://github.com/mfvanek/pg-index-health-sql/blob/master/sql/tables_with_incrementing_columns.sql)            |
 
 ### Raw SQL queries to use with other languages
 

doc/eng/tables_with_incrementing_columns.md

@@ -0,0 +1,78 @@
+# Check for tables with incrementing column names
+
+Tables that contain groups of columns sharing a common base name followed by a sequential integer
+suffix (for example, `phone1`, `phone2`, `phone3` or `address1`, `address2`, `address3`) are a sign
+of de-normalization: multiple values of the same concept are stored as separate columns instead of
+being extracted into a dedicated child table linked by a foreign key.
+
+This pattern is often called a **repeating group** and violates the First Normal Form (1NF).
+It creates several practical problems:
+
+- Adding a new value (e.g., `phone4`) requires a schema migration.
+- Querying all values requires enumerating column names explicitly.
+- Constraints (uniqueness, not-null, references) must be repeated for each numbered column.
+- Searching across all values requires `OR` or `UNION` constructs instead of a simple index lookup.
+
+The check reports any table where two or more columns share the same non-numeric prefix.
+
+Similar to [SchemaCrawler's `LinterTableWithIncrementingColumns`](https://www.schemacrawler.com/lint.html).
+
+## SQL query
+
+- [tables_with_incrementing_columns.sql](https://github.com/mfvanek/pg-index-health-sql/blob/master/sql/tables_with_incrementing_columns.sql)
+
+## Check type
+
+- **static** (can be performed on an empty database in component/integration tests)
+
+## Support for partitioned tables
+
+Supports partitioned tables.
+The check is performed on the partitioned table itself (the parent one). Individual sections (descendants) are ignored.
+
+## Reproduction script
+
+```sql
+create schema if not exists demo;
+
+create table if not exists demo.orders (
+    id       bigint generated always as identity primary key,
+    phone1   text,
+    phone2   text,
+    address1 text,
+    address2 text,
+    address3 text,
+    created_at timestamptz,
+    created_by text,
+    sku1 text,
+    "updatedAt" timestamptz,
+    "updatedBy" text
+);
+
+create table if not exists demo.events (
+    id         bigint    not null,
+    event_date date      not null,
+    tag1       text,
+    tag2       text
+) partition by range (event_date);
+
+create table if not exists demo.events_2024
+    partition of demo.events
+        for values from ('2024-01-01') to ('2025-01-01');
+```
+
+## How to fix
+
+Extract the repeating group into a separate child table and link it back with a foreign key.
+
+```sql
+-- Before: repeating columns in the parent table
+-- orders.phone1, orders.phone2, ...
+
+-- After: a dedicated child table
+create table demo.order_phones (
+    id       bigint generated always as identity primary key,
+    order_id bigint not null references demo.orders (id) on delete cascade,
+    phone    text   not null
+);
+```

doc/rus/tables_with_incrementing_columns.md

@@ -0,0 +1,78 @@
+# Проверка наличия таблиц с нумерованными именами колонок
+
+Таблицы, в которых есть группы колонок с одинаковым базовым именем и числовым суффиксом
+(например, `phone1`, `phone2`, `phone3` или `address1`, `address2`, `address3`) — признак денормализации:
+несколько значений одного и того же понятия хранятся в виде отдельных колонок вместо того,
+чтобы быть вынесенными в отдельную дочернюю таблицу, связанную внешним ключом.
+
+Такой паттерн часто называют **повторяющейся группой** (repeating group), и он нарушает Первую нормальную форму (1НФ).
+Это порождает ряд практических проблем:
+
+- Добавление нового значения (например, `phone4`) требует миграции схемы.
+- Для получения всех значений необходимо явно перечислять имена колонок.
+- Ограничения (уникальность, NOT NULL, ссылки) приходится повторять для каждой нумерованной колонки.
+- Поиск по всем значениям требует конструкций `OR` или `UNION` вместо простого поиска по индексу.
+
+Проверка выявляет таблицы, в которых две и более колонок имеют одинаковый нечисловой префикс.
+
+Аналог [SchemaCrawler `LinterTableWithIncrementingColumns`](https://www.schemacrawler.com/lint.html).
+
+## SQL запрос
+
+- [tables_with_incrementing_columns.sql](https://github.com/mfvanek/pg-index-health-sql/blob/master/sql/tables_with_incrementing_columns.sql)
+
+## Тип проверки
+
+- **static** (может выполняться на пустой БД в компонентных\интеграционных тестах)
+
+## Поддержка секционированных таблиц
+
+Поддерживает секционированные таблицы.
+Проверка выполняется на самой секционированной таблице (родительской). Отдельные секции (потомки) игнорируются.
+
+## Скрипт для воспроизведения
+
+```sql
+create schema if not exists demo;
+
+create table if not exists demo.orders (
+    id       bigint generated always as identity primary key,
+    phone1   text,
+    phone2   text,
+    address1 text,
+    address2 text,
+    address3 text,
+    created_at timestamptz,
+    created_by text,
+    sku1 text,
+    "updatedAt" timestamptz,
+    "updatedBy" text
+);
+
+create table if not exists demo.events (
+    id         bigint    not null,
+    event_date date      not null,
+    tag1       text,
+    tag2       text
+) partition by range (event_date);
+
+create table if not exists demo.events_2024
+    partition of demo.events
+        for values from ('2024-01-01') to ('2025-01-01');
+```
+
+## Как исправить
+
+Вынесите повторяющуюся группу в отдельную дочернюю таблицу и свяжите её внешним ключом.
+
+```sql
+-- До: повторяющиеся колонки в родительской таблице
+-- orders.phone1, orders.phone2, ...
+
+-- После: отдельная дочерняя таблица
+create table demo.order_phones (
+    id       bigint generated always as identity primary key,
+    order_id bigint not null references demo.orders (id) on delete cascade,
+    phone    text   not null
+);
+```

pg-index-health-core/src/main/java/io/github/mfvanek/pg/core/checks/common/Diagnostic.java

@@ -196,7 +196,11 @@ public enum Diagnostic implements CheckInfo {
     /**
      * Check for columns with {@code oid} or {@code lo} blob type.
      */
-    COLUMNS_WITH_BLOB_TYPE;
+    COLUMNS_WITH_BLOB_TYPE,
+    /**
+     * Check for tables with incrementing column names (e.g., {@code phone1}, {@code phone2}) indicating de-normalization.
+     */
+    TABLES_WITH_INCREMENTING_COLUMNS;
 
     private final CheckInfo inner;
 

pg-index-health-core/src/main/java/io/github/mfvanek/pg/core/checks/host/StandardChecksOnHost.java

@@ -85,7 +85,8 @@ public List<DatabaseCheckOnHost<? extends DbObject>> apply(final PgConnection pg
             new ForeignKeysWithNullValuesCheckOnHost(pgConnection),
             new TablesWithNoDataCheckOnHost(pgConnection),
             new SelfReferencedForeignKeysCheckOnHost(pgConnection),
-            new ColumnsWithBlobTypeCheckOnHost(pgConnection)
+            new ColumnsWithBlobTypeCheckOnHost(pgConnection),
+            new TablesWithIncrementingColumnsCheckOnHost(pgConnection)
         );
     }
 }

pg-index-health-core/src/main/java/io/github/mfvanek/pg/core/checks/host/TablesWithIncrementingColumnsCheckOnHost.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2019-2026. Ivan Vakhrushev and others.
+ * https://github.com/mfvanek/pg-index-health
+ *
+ * This file is a part of "pg-index-health" - an embeddable schema linter for PostgreSQL
+ * that detects common anti-patterns and promotes best practices.
+ *
+ * Licensed under the Apache License 2.0
+ */
+
+package io.github.mfvanek.pg.core.checks.host;
+
+import io.github.mfvanek.pg.connection.PgConnection;
+import io.github.mfvanek.pg.core.checks.common.Diagnostic;
+import io.github.mfvanek.pg.core.checks.extractors.TableWithColumnsExtractor;
+import io.github.mfvanek.pg.model.table.TableWithColumns;
+
+/**
+ * Check for tables with incrementing column names (e.g., {@code phone1}, {@code phone2}) on a specific host.
+ * Such columns indicate de-normalization that could be replaced with a separate child table and a foreign key.
+ *
+ * @author Ivan Vakhrushev
+ * @see <a href="https://www.schemacrawler.com/lint.html">SchemaCrawler LinterTableWithIncrementingColumns</a>
+ * @since 0.41.1
+ */
+public class TablesWithIncrementingColumnsCheckOnHost extends AbstractCheckOnHost<TableWithColumns> {
+
+    /**
+     * Constructs a new instance of {@code TablesWithIncrementingColumnsCheckOnHost}.
+     *
+     * @param pgConnection the connection to the PostgreSQL database; must not be null
+     */
+    public TablesWithIncrementingColumnsCheckOnHost(final PgConnection pgConnection) {
+        super(TableWithColumns.class, pgConnection, Diagnostic.TABLES_WITH_INCREMENTING_COLUMNS, TableWithColumnsExtractor.of());
+    }
+}

pg-index-health-core/src/main/resources

@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2019-2026. Ivan Vakhrushev and others.
+ * https://github.com/mfvanek/pg-index-health
+ *
+ * This file is a part of "pg-index-health" - an embeddable schema linter for PostgreSQL
+ * that detects common anti-patterns and promotes best practices.
+ *
+ * Licensed under the Apache License 2.0
+ */
+
+package io.github.mfvanek.pg.core.checks.host;
+
+import io.github.mfvanek.pg.core.checks.common.DatabaseCheckOnHost;
+import io.github.mfvanek.pg.core.checks.common.Diagnostic;
+import io.github.mfvanek.pg.core.fixtures.support.DatabaseAwareTestBase;
+import io.github.mfvanek.pg.core.fixtures.support.DatabasePopulator;
+import io.github.mfvanek.pg.model.column.Column;
+import io.github.mfvanek.pg.model.context.PgContext;
+import io.github.mfvanek.pg.model.table.Table;
+import io.github.mfvanek.pg.model.table.TableWithColumns;
+import org.jspecify.annotations.NonNull;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import java.util.List;
+
+import static io.github.mfvanek.pg.core.support.AbstractCheckOnHostAssert.assertThat;
+
+class TablesWithIncrementingColumnsCheckOnHostTest extends DatabaseAwareTestBase {
+
+    private final DatabaseCheckOnHost<@NonNull TableWithColumns> check = new TablesWithIncrementingColumnsCheckOnHost(getPgConnection());
+
+    @Test
+    void shouldSatisfyContract() {
+        assertThat(check)
+            .hasType(TableWithColumns.class)
+            .hasDiagnostic(Diagnostic.TABLES_WITH_INCREMENTING_COLUMNS)
+            .hasHost(getHost())
+            .isStatic();
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = {PgContext.DEFAULT_SCHEMA_NAME, "custom"})
+    void onDatabaseWithThem(final String schemaName) {
+        executeTestOnDatabase(schemaName, DatabasePopulator::withIncrementingColumns, ctx ->
+            assertThat(check)
+                .executing(ctx)
+                .hasSize(1)
+                .usingRecursiveFieldByFieldElementComparator()
+                .containsExactly(
+                    TableWithColumns.of(
+                        Table.of(ctx, "orders", 8_192L),
+                        List.of(
+                            Column.ofNullable(ctx, "orders", "phone1"),
+                            Column.ofNullable(ctx, "orders", "phone2"),
+                            Column.ofNullable(ctx, "orders", "address1"),
+                            Column.ofNullable(ctx, "orders", "address2"),
+                            Column.ofNullable(ctx, "orders", "address3")
+                        )
+                    )
+                ));
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = {PgContext.DEFAULT_SCHEMA_NAME, "custom"})
+    void shouldWorkWithPartitionedTables(final String schemaName) {
+        executeTestOnDatabase(schemaName, DatabasePopulator::withIncrementingColumnsInPartitionedTable, ctx ->
+            assertThat(check)
+                .executing(ctx)
+                .hasSize(1)
+                .usingRecursiveFieldByFieldElementComparator()
+                .containsExactly(
+                    TableWithColumns.of(
+                        Table.of(ctx, "events"),
+                        List.of(
+                            Column.ofNullable(ctx, "events", "tag1"),
+                            Column.ofNullable(ctx, "events", "tag2")
+                        )
+                    )
+                ));
+    }
+}

pg-index-health-core/src/test/java/io/github/mfvanek/pg/core/checks/host/TablesWithIncrementingColumnsCheckOnHostTest.java

@@ -57,6 +57,7 @@
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreatePartitionedTableForBloatStatement;
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreatePartitionedTableWithBlobTypeColumnStatement;
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreatePartitionedTableWithDroppedColumnStatement;
+import io.github.mfvanek.pg.core.fixtures.support.statements.CreatePartitionedTableWithIncrementingColumnsStatement;
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreatePartitionedTableWithJsonAndSerialColumnsStatement;
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreatePartitionedTableWithNoDataStatement;
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreatePartitionedTableWithNullableFieldsStatement;
@@ -75,6 +76,7 @@
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreateTableWithColumnOfBigSerialTypeStatement;
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreateTableWithFixedLengthVarcharStatement;
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreateTableWithIdentityPrimaryKeyStatement;
+import io.github.mfvanek.pg.core.fixtures.support.statements.CreateTableWithIncrementingColumnsStatement;
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreateTableWithInheritanceStatement;
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreateTableWithNaturalKeyStatement;
 import io.github.mfvanek.pg.core.fixtures.support.statements.CreateTableWithSerialPrimaryKeyReferencesToAnotherTableStatement;
@@ -425,6 +427,14 @@ public DatabasePopulator withBlobTypeColumnInPartitionedTable() {
         return register(154, new CreatePartitionedTableWithBlobTypeColumnStatement());
     }
 
+    public DatabasePopulator withIncrementingColumns() {
+        return register(155, new CreateTableWithIncrementingColumnsStatement());
+    }
+
+    public DatabasePopulator withIncrementingColumnsInPartitionedTable() {
+        return register(156, new CreatePartitionedTableWithIncrementingColumnsStatement());
+    }
+
     public void populate() {
         try (SchemaNameHolder ignored = SchemaNameHolder.with(schemaName)) {
             ExecuteUtils.executeInTransaction(dataSource, statementsToExecuteInSameTransaction.values());