pgsql-cli

@pgsql/cli

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

pgsql deparse [options]

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-gen
• protogen → proto-fetch
• Boolean flags now use kebab-case (e.g., --enumsJSON → --enums-json)