@pgsql/cli is a unified command-line interface for PostgreSQL AST operations, including parsing SQL to AST, deparsing AST back to SQL, and generating TypeScript definitions from PostgreSQL protobufs. It consolidates functionality from multiple packages into a single, easy-to-use CLI tool.
Installation
npm install -g @pgsql/cli
Features
- Parse SQL to AST: Convert PostgreSQL queries into Abstract Syntax Trees
- Deparse AST to SQL: Convert AST back into SQL queries
- Generate TypeScript from Protobuf: Create type-safe TypeScript definitions from PostgreSQL protobuf files
- Download and Process Proto Files: Fetch proto files from URLs and generate JavaScript
- Runtime Schema Generation: Generate runtime schemas for AST nodes
- Unified Interface: Single CLI tool for all PostgreSQL AST operations
Quick Start
# Parse SQL to AST pgsql parse query.sql # Deparse AST back to SQL pgsql deparse ast.json # Generate TypeScript from protobuf pgsql proto-gen --inFile pg_query.proto --outDir out --types --enums # Download and process proto file pgsql proto-fetch --url https://raw.githubusercontent.com/pganalyze/libpg_query/16-latest/protobuf/pg_query.proto --inFile pg_query.proto --outFile pg_query.js
Commands
pgsql parse
Parse SQL files into Abstract Syntax Trees (AST).
pgsql parse <sqlfile> [options]
Options
| Option | Description | Default |
|---|---|---|
-o, --output |
Output to file instead of stdout | |
-f, --format |
Output format: json, pretty |
pretty |
--pl |
Parse as PL/pgSQL function only | false |
--clean |
Clean the AST tree (remove location info) | false |
-h, --help |
Show help |
Examples
# Parse SQL and output to console pgsql parse query.sql # Parse SQL and save to file pgsql parse query.sql -o ast.json # Parse PL/pgSQL function pgsql parse function.sql --pl # Parse and output compact JSON pgsql parse query.sql --format json
pgsql deparse
Convert AST back to SQL.
Options
| Option | Description | Default |
|---|---|---|
-i, --input |
Input JSON file (or use stdin) | |
-o, --output |
Output to file instead of stdout | |
-h, --help |
Show help |
Examples
# Deparse from file pgsql deparse -i ast.json # Deparse from stdin cat ast.json | pgsql deparse # Parse and deparse in one line pgsql parse query.sql | pgsql deparse # Deparse to file pgsql deparse -i ast.json -o query.sql
pgsql proto-gen
Generate TypeScript definitions from PostgreSQL protobuf files.
pgsql proto-gen --inFile <proto> --outDir <dir> [options]
Options
| Option | Description | Default |
|---|---|---|
--inFile |
Input .proto file | Required |
--outDir |
Output directory | Required |
--enums |
Generate TypeScript enums | false |
--enums-json |
Generate JSON enum mappings | false |
--types |
Generate TypeScript interfaces | false |
--utils |
Generate utility functions | false |
--ast-helpers |
Generate AST helper methods | false |
--wrapped-helpers |
Generate wrapped AST helpers | false |
--optional |
Make all fields optional | false |
--keep-case |
Keep original field casing | false |
--remove-undefined |
Remove UNDEFINED enum at position 0 | false |
-h, --help |
Show help |
Examples
# Generate types and enums pgsql proto-gen --inFile pg_query.proto --outDir out --types --enums # Generate everything pgsql proto-gen --inFile pg_query.proto --outDir out --types --enums --utils --ast-helpers # Generate with optional fields pgsql proto-gen --inFile pg_query.proto --outDir out --types --optional
pgsql proto-fetch
Download and process proto files.
pgsql proto-fetch [options]
Options
| Option | Description | Default |
|---|---|---|
--url |
Proto file URL to download | |
--inFile |
Where to save the proto file | Required |
--outFile |
Generated JS output file | Required |
--replace-pkg |
Original package name to replace | protobufjs/minimal |
--with-pkg |
New package name | @launchql/protobufjs/minimal |
-h, --help |
Show help |
Examples
# Download and process proto file pgsql proto-fetch \ --url https://raw.githubusercontent.com/pganalyze/libpg_query/16-latest/protobuf/pg_query.proto \ --inFile pg_query.proto \ --outFile pg_query.js # Process existing proto file pgsql proto-fetch \ --inFile pg_query.proto \ --outFile pg_query.js \ --replace-pkg "protobufjs/minimal" \ --with-pkg "@custom/protobufjs"
pgsql runtime-schema
Generate runtime schema for AST nodes.
pgsql runtime-schema --inFile <proto> --outDir <dir> [options]
Options
| Option | Description | Default |
|---|---|---|
--inFile |
Input .proto file | Required |
--outDir |
Output directory | Required |
--format |
Output format: json, typescript |
json |
--filename |
Output filename (without extension) | runtime-schema |
-h, --help |
Show help |
Examples
# Generate JSON schema pgsql runtime-schema --inFile pg_query.proto --outDir out # Generate TypeScript schema pgsql runtime-schema --inFile pg_query.proto --outDir out --format typescript # Custom filename pgsql runtime-schema --inFile pg_query.proto --outDir out --filename ast-schema
Migration Guide
Migrating from pgsql-parser CLI
If you were using the pgsql-parser command-line tool:
# Old pgsql-parser file.sql pgsql-parser file.sql --pl # New pgsql parse file.sql pgsql parse file.sql --pl
Migrating from pg-proto-parser
If you were using the pg-proto-parser command-line tool:
# Old pg-proto-parser codegen --inFile pg_query.proto --outDir out # New pgsql proto-gen --inFile pg_query.proto --outDir out
The command options remain largely the same, with some improvements:
codegen→proto-genprotogen→proto-fetch- Boolean flags now use kebab-case (e.g.,
--enumsJSON→--enums-json)
Related
- pgsql-parser: The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.
- pgsql-deparser: A streamlined tool designed for converting PostgreSQL ASTs back into SQL queries, focusing solely on deparser functionality to complement
pgsql-parser. - @pgsql/parser: Multi-version PostgreSQL parser with dynamic version selection at runtime, supporting PostgreSQL 15, 16, and 17 in a single package.
- @pgsql/types: Offers TypeScript type definitions for PostgreSQL AST nodes, facilitating type-safe construction, analysis, and manipulation of ASTs.
- @pgsql/enums: Provides TypeScript enum definitions for PostgreSQL constants, enabling type-safe usage of PostgreSQL enums and constants in your applications.
- @pgsql/utils: A comprehensive utility library for PostgreSQL, offering type-safe AST node creation and enum value conversions, simplifying the construction and manipulation of PostgreSQL ASTs.
- @pgsql/traverse: PostgreSQL AST traversal utilities for pgsql-parser, providing a visitor pattern for traversing PostgreSQL Abstract Syntax Tree nodes, similar to Babel's traverse functionality but specifically designed for PostgreSQL AST structures.
- pg-proto-parser: A TypeScript tool that parses PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
- libpg-query: The real PostgreSQL parser exposed for Node.js, used primarily in
pgsql-parserfor parsing and deparsing SQL queries.
Disclaimer
AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
No developer or entity involved in creating Software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the Software code or Software CLI, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.