pg_query_java

Java bindings for libpg_query — PostgreSQL's parser exposed as a standalone C library.

This project is an inofficial port, and not affiliated with pganalyze, the authors of libpg_query, or the PostgreSQL project itself.

Supports parsing SQL to protobuf or JSON, normalizing queries, and computing stable fingerprints.

The native library is bundled inside the JAR and extracted automatically at runtime.

Add JitPack to your repositories and declare the dependency:

Gradle (Kotlin DSL)

repositories {
    maven { url = uri("https://jitpack.io") }
}

dependencies {
    implementation("com.github.groestl:pg_query_java:v5.2.0")
}

Gradle (Groovy DSL)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.groestl:pg_query_java:v5.2.0'
}

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.groestl</groupId>
    <artifactId>pg_query_java</artifactId>
    <version>v5.2.0</version>
</dependency>

import com.pganalyze.pg_query.PgQuery;
import com.pganalyze.pg_query.ParseResult;

ParseResult result = PgQuery.parseProtobuf("SELECT 1");
byte[] bytes = result.getProtobufBytes(); // pg_query.ParseResult proto bytes

To decode the protobuf, add com.google.protobuf:protobuf-java to your dependencies and use the pg_query.proto schema shipped with libpg_query.

String json = PgQuery.parseToJson("SELECT a, b FROM t WHERE id = 1");
// {"version":160001,"stmts":[{"stmt":{"SelectStmt": ...}}]}

Replace all literal values with numbered parameter placeholders:

String norm = PgQuery.normalize("SELECT * FROM t WHERE id = 42 AND name = 'alice'");
// "SELECT * FROM t WHERE id = $1 AND name = $2"

Compute a stable fingerprint that is insensitive to whitespace and literal values:

String fp1 = PgQuery.fingerprint("SELECT * FROM t WHERE id = 1");
String fp2 = PgQuery.fingerprint("SELECT * FROM t WHERE id = 99");
// fp1.equals(fp2) == true

All methods throw PgQueryException on syntax errors:

try {
    PgQuery.parseToJson("SELECT FROM FROM");
} catch (PgQueryException e) {
    System.out.println(e.getMessage());        // human-readable error
    System.out.println(e.getCursorPosition()); // byte offset into the query
    System.out.println(e.getContext());        // additional context (may be null)
}

PgQueryException fields:

Requires: gcc, make, git, JDK 11+.

./gradlew build

This will clone and compile libpg_query 16-5.2.0, compile the JNI shared library, and produce a JAR with the native library bundled under /native/<platform>/.

./gradlew test

Tests are skipped automatically on unsupported platforms.

This binding is MIT licenced — see LICENSE.

libpg_query is copyright © pganalyze, Inc. and contributors, released under the BSD-3-Clause license.