Crate pg_query 

Rust pg_query  

This Rust library uses the actual PostgreSQL server source to parse SQL queries and return the internal PostgreSQL parse tree.

It also allows you to normalize queries (replacing constant values with $1, etc.) and parse these normalized queries into a parse tree again.

When you build this library, it builds parts of the PostgreSQL server source (see libpg_query), and then statically links it into this library.

You can find further examples and a longer rationale for the original Ruby implementation here. The Rust version tries to have a very similar API.

Getting started

Add the following to your Cargo.toml

[dependencies]
pg_query = "6.1"

Example: Parsing a query

use pg_query::NodeRef;

let result = pg_query::parse("SELECT * FROM contacts");
assert!(result.is_ok());
let result = result.unwrap();
assert_eq!(result.tables(), vec!["contacts"]);
assert!(matches!(result.protobuf.nodes()[0].0, NodeRef::SelectStmt(_)));

Re-exports

pub use protobuf::Node;

pub use protobuf::node::Node as NodeEnum;

Modules

protobuf

Structs

Diagnostic

PostgreSQL ErrorData fields copied while the parser owns their backing storage.

FilterColumn

Fingerprint

Represents the resulting fingerprint containing both the raw integer form as well as the corresponding 16 character hex value.

Function

ParseOptions

Scanner settings captured when a complete SQL message is parsed. PostgreSQL’s safe_encoding and on values for backslash_quote are equivalent for UTF-8.

ParseOutcome

Notices are retained in parser order, including notices emitted before an error.

ParseResult

Result from calling parse

PlpgsqlCatalog

An immutable catalog snapshot for one parse. search_path is the caller’s effective namespace order, including pg_catalog where appropriate. Built-in types remain available through PostgreSQL’s own fallback catalog.

PlpgsqlType

The pg_type attributes needed to distinguish scalar, domain, array, and composite declarations.

SummaryResult

Result from calling summary. Where possible, this is API-compatible with ParseResult.

Table

Enums

Context

Error

Error structure representing the basic error scenarios for pg_query.

LockMode

NodeMut

NodeRef

ParseMode

PostgreSQL raw-parser entry mode.

PlpgsqlCompileMode

Whether a PL/pgSQL structure is checked at definition or compiled for execution. Runtime compilation keeps embedded SQL text for its first reached preparation.

TriggerType

Functions

deparse

Converts a parsed tree back into a string.

fingerprint

Fingerprints the given SQL statement. Useful for comparing parse trees across different implementations of libpg_query.

normalize

Normalizes the given SQL statement, returning a parametized version.

parse

Parses the given SQL statement into the given abstract syntax tree.

parse_plpgsql

An experimental API which parses a PLPGSQL function. This currently returns the raw JSON structure.

parse_plpgsql_with_catalog

Parse PL/pgSQL with the caller’s catalog types instead of treating every unknown type as a record. The snapshot and callback storage remain local to this synchronous parse; no pointers or callback state escape it.

parse_plpgsql_with_mode

Compile a PL/pgSQL structure with the caller-selected validator/runtime boundary. This changes only PostgreSQL’s own validator checks, not warning delivery.

parse_plpgsql_with_options

Parse PL/pgSQL with a synchronous catalog snapshot, per-call scanner settings and structured diagnostics. A missing catalog uses PostgreSQL’s builtin types.

parse_with_mode

Parses input using one of PostgreSQL’s raw-parser modes.

parse_with_options

Parse with per-call scanner settings and original SQLSTATE, DETAIL, HINT and warning fields. Settings and callback state are restored even after errors.

scan

Scan a sql query into a its component of tokens.

scan_with_options

Scan with explicit string-literal settings, preserving token source offsets. No parse mode is used; options.mode is ignored.

split_with_parser

Split a well-formed query into separate statements.

split_with_scanner

Split a potentially-malformed query into separate statements. Note that invalid tokens will be skipped

summary

Parses the given SQL statement and provides a summary of it.

truncate

Type Aliases

Result

Convenient Result alias for returning pg_query::Error.