Skip to content

Latest commit

 

History

History
72 lines (47 loc) · 3.5 KB

CONTRIBUTING.md

File metadata and controls

72 lines (47 loc) · 3.5 KB
Raw

Building and testing

Java >= 11 is required.

  1. Clone the repository

    git clone --recursive https://github.com/mfvanek/pg-index-health.git
cd pg-index-health

  2. Build with Gradle

    • On Linux and macOS: ./gradlew build
    • On Windows: .\gradlew.bat build

    This will build the project and run tests.

By default, PostgreSQL 16.2 from Testcontainers is used to run tests.
Set TEST_PG_VERSION environment variable to use any of other available PostgreSQL version:

TEST_PG_VERSION=11.20-alpine

List of all available PostgreSQL versions can be found here.

Implementing a new check

Write a new SQL query

Each database structure check starts with an SQL query to the pg_catalog.

  1. SQL queries for checks are located in a separate repository https://github.com/mfvanek/pg-index-health-sql
  2. That repository is pulled into the current project as a git submodule
  3. SQLFluff is used as a linter for all sql queries
  4. All requests must be schema-aware (see example)

Extend domain model (if needed)

pg-index-health is a multimodule Gradle project.
Domain model is located in a pg-index-health-model. All domain classes should be minimalistic and well-defined. They should include enough information to generate corrective SQL migrations via pg-index-health-generator.

Add the code for the new check

All checks can be divided into 2 parts:

  1. Runtime checks (those that make sense to run only on a production database)
  2. Static checks (which can be run in tests on an empty database)

Runtime checks usually require aggregation of data from all nodes in the cluster. Because of this, it became necessary to create our own abstraction over the database connection.

Execution on a specific host

Implement a new class extending AbstractCheckOnHost.

Execution on the cluster

Implement a new class extending AbstractCheckOnCluster.

Write proper tests

  • Your code must be 100% covered.
  • Mutation tests via pitest should work.

Further steps

  1. Update readme and add information about the new check
  2. Update Spring Boot starter.
  3. Add sample code to the demo apps (first, second). Use a locally built pg-index-health version and send a draft PR.