pganalyze/libpg_query
FreeC library for accessing the PostgreSQL parser outside of the server environment
FreeFree tier
About pganalyze/libpg_query
libpg_query is a C library that leverages the actual PostgreSQL server source code to parse SQL queries and return the internal PostgreSQL parse tree. It is designed primarily as a foundational library for language-specific wrappers, including pg_query (Ruby), pg_query.go (Go), pg_query.rs (Rust), pgsql-parser (Node), psqlparse (Python), and pglast (Python 3). The library also exposes the PostgreSQL scanner/lexer for tokenizing queries, which can be used for syntax highlighting and other preprocessing tasks. Installation requires cloning the repository and running make, which includes compiling parts of PostgreSQL and can take up to 3 minutes.
Key Features
Parses SQL queries using the actual PostgreSQL server parser, returning the internal parse tree as JSON
Provides a scanner/lexer to tokenize queries for syntax highlighting and token-level analysis
Serves as the base library for multiple language-specific wrappers: Ruby, Go, Rust, Node.js, Python
Exposes a simple C API with functions like pg_query_parse and pg_query_scan
Uses protobuf for structured scan result output
Pros & Cons
Pros
- Uses the actual PostgreSQL parser, ensuring correctness and compatibility with PostgreSQL syntax
- Supports multiple high-level languages through dedicated wrappers, reducing integration effort
- Open source and free to use, with active maintenance by pganalyze
- Provides both full parse tree and token scanning capabilities for different use cases
Cons
- Compilation from source requires building parts of PostgreSQL, leading to a longer build time (up to 3 minutes)
- Limited to parsing PostgreSQL SQL syntax; not suitable for other SQL dialects
- C library requires integration efforts for projects not using C or the supported language bindings
Best For
Building SQL analysis and linting tools that require accurate PostgreSQL parsingImplementing syntax highlighting for PostgreSQL queries in editors or IDEsCreating database migration tools that need to understand query structureDeveloping static analysis or security scanning tools for PostgreSQL schemas and queries
FAQ
What is libpg_query?
libpg_query is a C library that uses the actual PostgreSQL server source code to parse SQL queries and return the internal PostgreSQL parse tree. It also provides a scanner/lexer for tokenizing queries.
What language bindings are available?
The library is intended as a base for multiple wrappers: pg_query (Ruby), pg_query.go (Go), pg_query.rs (Rust), pgsql-parser (Node), psqlparse (Python), and pglast (Python 3).
How do I install libpg_query?
Clone the repository (e.g., git clone -b 18-latest git://github.com/pganalyze/libpg_query), then run 'make' in the directory. On Windows with Visual Studio, use 'nmake /F Makefile.msvc'.
How can I parse a query?
Include pg_query.h, call pg_query_parse() with a query string, then access the result's parse_tree field. Free the result with pg_query_free_parse_result().