README

A compiled PHP extension for PostgreSQL query parsing using libpg_query.

Features

Parse PostgreSQL SQL queries into JSON AST
Generate query fingerprints for query grouping
Normalize SQL queries (replace literals with placeholders)
Parse PL/pgSQL functions
Split multiple SQL statements
Scan SQL into tokens

Installation

Using PIE (Recommended)

PIE is the modern PHP extension installer.

Prerequisites: Install protobuf-c library on your system:

# Ubuntu/Debian
sudo apt-get install libprotobuf-c-dev git make gcc

# macOS with Homebrew
brew install protobuf-c

# Fedora/RHEL
sudo dnf install protobuf-c-devel git make gcc

Install the extension:

# Simple installation (auto-downloads libpg_query for PostgreSQL 17)
pie install flow-php/pg-query-ext

# Install with a specific PostgreSQL grammar version (15, 16, or 17)
pie install flow-php/pg-query-ext --with-pg-version=16

# Or with a pre-installed libpg_query
pie install flow-php/pg-query-ext --with-pg-query=/usr/local

The extension will automatically download and build the appropriate libpg_query version if not found on your system.

Supported PostgreSQL versions:

PostgreSQL	libpg_query version
17	17-6.1.0 (default)
16	16-5.2.0
15	15-4.2.4

Requirements

PHP 8.2+
C compiler (gcc/clang)
git (for auto-downloading libpg_query)
make
protobuf-c library

Manual Build

cd src/extension/pg-query-ext

# This will download and build libpg_query, then build the extension
make build

# Run extension tests
make test

# Install to system PHP (optional)
make install

Using Nix

From the Flow PHP monorepo root:

# Enter Nix shell with pg_query extension loaded and build tools available
nix-shell --arg with-pg-query-ext true

# Navigate to extension directory
cd src/extension/pg-query-ext

# Build and test
make test

Usage

// Parse SQL and return JSON AST
$json = pg_query_parse('SELECT * FROM users WHERE id = 1');
$ast = json_decode($json, true);

// Generate fingerprint (same for structurally equivalent queries)
$fp = pg_query_fingerprint('SELECT * FROM users WHERE id = 1');
// Returns same fingerprint for: SELECT * FROM users WHERE id = 2

// Normalize query (replace literals with $N placeholders)
$normalized = pg_query_normalize("SELECT * FROM users WHERE name = 'John'");
// Returns: SELECT * FROM users WHERE name = $1

// Split multiple statements
$statements = pg_query_split('SELECT 1; SELECT 2; SELECT 3');
// Returns: ['SELECT 1', ' SELECT 2', ' SELECT 3']

// Scan SQL into tokens (returns protobuf data)
$protobuf = pg_query_scan('SELECT 1');

Loading the Extension

During Development

php -d extension=./ext/modules/pg_query.so your_script.php

In php.ini

extension=pg_query

Functions Reference

Function	Description	Returns
`pg_query_parse(string $sql)`	Parse SQL to JSON AST	`string` (JSON)
`pg_query_fingerprint(string $sql)`	Generate query fingerprint	`string\|false`
`pg_query_normalize(string $sql)`	Normalize query with placeholders	`string\|false`
`pg_query_parse_plpgsql(string $sql)`	Parse PL/pgSQL function	`string` (JSON)
`pg_query_split(string $sql)`	Split multiple statements	`array<string>`
`pg_query_scan(string $sql)`	Scan SQL into tokens	`string` (protobuf)

Development

# Build and run tests
make test

# Rebuild extension only (without rebuilding libpg_query)
make rebuild

# Clean build artifacts
make clean

# Remove everything including libpg_query
make distclean

License

MIT

flow-php / pg-query-ext

Maintainers

Details