@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)