pg-index-health is an embeddable schema linter for PostgreSQL that detects common anti-patterns and promotes best practices.
pg-index-health is a Java library designed to analyze PostgreSQL database schemas and help developers build efficient, reliable applications.
It scans database structures to identify common schema-level pitfalls that often go unnoticed until they cause problems in production.
By embedding pg-index-health into your CI/CD pipeline, you can proactively catch schema design flaws, enforce consistency, and adhere to PostgreSQL best practices before they impact performance or reliability.
A list of all available checks (rules/diagnostics) can be found here.
In code, you can get all checks through an instance of the StandardChecksOnHost or StandardChecksOnCluster class.
You can add your own database structure checks as shown in the link.
Using Gradle:
implementation("io.github.mfvanek:pg-index-health:0.30.0")Using Maven:
<dependency>
<groupId>io.github.mfvanek</groupId>
<artifactId>pg-index-health</artifactId>
<version>0.30.0</version>
</dependency>There are two main scenarios of using pg-index-health in your projects:
- unit\functional testing (see standard test in a section below) locally and in CI for compliance of the database structure with best practices;
- collecting indexes, tables and sequences health data and bloat monitoring in runtime on production.
All these cases are covered with examples in the pg-index-health-demo project.
There is a Spring Boot starter pg-index-health-test-starter
for unit/integration testing as well.
More examples you can find in the pg-index-health-demo project.
Using Gradle:
testImplementation("io.github.mfvanek:pg-index-health-test-starter:0.30.0")Using Maven:
<dependency>
<groupId>io.github.mfvanek</groupId>
<artifactId>pg-index-health-test-starter</artifactId>
<version>0.30.0</version>
<scope>test</scope>
</dependency>Add a standard test to your project as shown in the link. Ideally, all checks should pass and return an empty result.
| Spring Boot | Min JDK | pg-index-health-test-starter |
|---|---|---|
| 2.7.x | 11 | 0.8.x — 0.15.x |
| 3.3.x | 17 | 0.20.x |
| 3.4.x | 17 | 0.30.x |
- Starting from 0.9.0.1 added support for Spring Boot 3.0
- Starting from 0.10.2 added support for Spring Boot 3.2
Compatibility with previous PostgreSQL versions is no longer guaranteed, but it is very likely.
We focus only on the currently maintained versions of PostgreSQL.
For more information please see PostgreSQL Versioning Policy.
Supports Java 17 and above.
- For Java 11 compatible version take a look at release 0.15.0 and lower.
- pg-index-health – static analysis of the structure of PostgreSQL databases
- Index health in PostgreSQL through the eyes of a Java developer
- DBA: finding useless indexes
- The series of articles "Static analysis of the database structure"
- If you have any question or a problem with the library, please file an issue.
- Contributions are always welcome! Please see contributing guide for more details.
- We utilize Testcontainers for testing pg-index-health. So you need to have Docker installed on your machine.
- PostgreSQL Wiki - Don't Do This — a short list of common mistakes.
- db_verifier — scripts to check the database structure for errors or non-recommended practices.
- SchemaCrawler Linter — a free database schema linter.
- Squawk — a linter for Postgres migrations.
- schemalint — a Postgres databases schema linter.
- index-digest — a database linter for MySQL and MariaDB.
- Azimutt — a linter for database.