@pgsql/cli 1.30.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +64 -0
- package/LICENSE +21 -0
- package/README.md +268 -0
- package/dist/LICENSE +21 -0
- package/dist/README.md +268 -0
- package/dist/commands/deparse.d.ts +1 -0
- package/dist/commands/deparse.js +66 -0
- package/dist/commands/parse.d.ts +1 -0
- package/dist/commands/parse.js +60 -0
- package/dist/commands/proto-fetch/cli.d.ts +14 -0
- package/dist/commands/proto-fetch/cli.js +41 -0
- package/dist/commands/proto-fetch/helpers.d.ts +3 -0
- package/dist/commands/proto-fetch/helpers.js +73 -0
- package/dist/commands/proto-fetch.d.ts +1 -0
- package/dist/commands/proto-fetch.js +42 -0
- package/dist/commands/proto-gen.d.ts +1 -0
- package/dist/commands/proto-gen.js +59 -0
- package/dist/commands/runtime-schema.d.ts +1 -0
- package/dist/commands/runtime-schema.js +70 -0
- package/dist/esm/commands/deparse.js +60 -0
- package/dist/esm/commands/parse.js +54 -0
- package/dist/esm/commands/proto-fetch/cli.js +37 -0
- package/dist/esm/commands/proto-fetch/helpers.js +64 -0
- package/dist/esm/commands/proto-fetch.js +36 -0
- package/dist/esm/commands/proto-gen.js +53 -0
- package/dist/esm/commands/runtime-schema.js +64 -0
- package/dist/esm/index.js +56 -0
- package/dist/esm/package.js +26 -0
- package/dist/esm/utils/help.js +190 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +61 -0
- package/dist/package.d.ts +1 -0
- package/dist/package.js +29 -0
- package/dist/package.json +60 -0
- package/dist/utils/help.d.ts +2 -0
- package/dist/utils/help.js +197 -0
- package/jest.config.js +18 -0
- package/package.json +60 -0
- package/src/commands/deparse.ts +60 -0
- package/src/commands/parse.ts +60 -0
- package/src/commands/proto-fetch/cli.ts +52 -0
- package/src/commands/proto-fetch/helpers.ts +72 -0
- package/src/commands/proto-fetch.ts +42 -0
- package/src/commands/proto-gen.ts +49 -0
- package/src/commands/runtime-schema.ts +74 -0
- package/src/index.ts +69 -0
- package/src/package.ts +33 -0
- package/src/utils/help.ts +198 -0
- package/tsconfig.esm.json +9 -0
- package/tsconfig.json +9 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Change Log
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
|
5
|
+
|
|
6
|
+
# 1.30.0 (2025-06-23)
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
### Features
|
|
10
|
+
|
|
11
|
+
* implement unified @pgsql/cli package ([b009a17](https://github.com/launchql/pgsql-parser/commit/b009a172c3c93033573745e80354a7dac973e2bf))
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
### BREAKING CHANGES
|
|
15
|
+
|
|
16
|
+
* Binary renamed from pg-proto-parser to pgsql. Command structure changed from subcommands to main commands.
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
## [1.29.2](https://github.com/launchql/pgsql-parser/compare/@launchql/proto-cli@1.29.1...@launchql/proto-cli@1.29.2) (2025-06-22)
|
|
23
|
+
|
|
24
|
+
**Note:** Version bump only for package @launchql/proto-cli
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
## [1.29.1](https://github.com/launchql/pgsql-parser/compare/@launchql/proto-cli@1.29.0...@launchql/proto-cli@1.29.1) (2025-06-22)
|
|
31
|
+
|
|
32
|
+
**Note:** Version bump only for package @launchql/proto-cli
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
# [1.29.0](https://github.com/launchql/pgsql-parser/compare/@launchql/proto-cli@1.28.1...@launchql/proto-cli@1.29.0) (2025-06-22)
|
|
39
|
+
|
|
40
|
+
**Note:** Version bump only for package @launchql/proto-cli
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
## [1.28.1](https://github.com/launchql/pgsql-parser/compare/@launchql/proto-cli@1.28.0...@launchql/proto-cli@1.28.1) (2025-06-21)
|
|
47
|
+
|
|
48
|
+
**Note:** Version bump only for package @launchql/proto-cli
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
# [1.28.0](https://github.com/launchql/pgsql-parser/compare/@launchql/proto-cli@1.27.0...@launchql/proto-cli@1.28.0) (2025-06-21)
|
|
55
|
+
|
|
56
|
+
**Note:** Version bump only for package @launchql/proto-cli
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
# [1.27.0](https://github.com/launchql/pgsql-parser/compare/@launchql/proto-cli@1.26.0...@launchql/proto-cli@1.27.0) (2025-06-21)
|
|
63
|
+
|
|
64
|
+
**Note:** Version bump only for package @launchql/proto-cli
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2020 Dan Lynch <pyramation@gmail.com>
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
# @pgsql/cli
|
|
2
|
+
|
|
3
|
+
<p align="center" width="100%">
|
|
4
|
+
<img height="120" src="https://github.com/launchql/pgsql-parser/assets/545047/6440fa7d-918b-4a3b-8d1b-755d85de8bea" />
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center" width="100%">
|
|
8
|
+
<a href="https://github.com/launchql/pgsql-parser/actions/workflows/run-tests.yaml">
|
|
9
|
+
<img height="20" src="https://github.com/launchql/pgsql-parser/actions/workflows/run-tests.yaml/badge.svg" />
|
|
10
|
+
</a>
|
|
11
|
+
<a href="https://github.com/launchql/pgsql-parser/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
`@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.
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install -g @pgsql/cli
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Features
|
|
23
|
+
|
|
24
|
+
- **Parse SQL to AST**: Convert PostgreSQL queries into Abstract Syntax Trees
|
|
25
|
+
- **Deparse AST to SQL**: Convert AST back into SQL queries
|
|
26
|
+
- **Generate TypeScript from Protobuf**: Create type-safe TypeScript definitions from PostgreSQL protobuf files
|
|
27
|
+
- **Download and Process Proto Files**: Fetch proto files from URLs and generate JavaScript
|
|
28
|
+
- **Runtime Schema Generation**: Generate runtime schemas for AST nodes
|
|
29
|
+
- **Unified Interface**: Single CLI tool for all PostgreSQL AST operations
|
|
30
|
+
|
|
31
|
+
## Quick Start
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# Parse SQL to AST
|
|
35
|
+
pgsql parse query.sql
|
|
36
|
+
|
|
37
|
+
# Deparse AST back to SQL
|
|
38
|
+
pgsql deparse ast.json
|
|
39
|
+
|
|
40
|
+
# Generate TypeScript from protobuf
|
|
41
|
+
pgsql proto-gen --inFile pg_query.proto --outDir out --types --enums
|
|
42
|
+
|
|
43
|
+
# Download and process proto file
|
|
44
|
+
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
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Commands
|
|
48
|
+
|
|
49
|
+
### `pgsql parse`
|
|
50
|
+
|
|
51
|
+
Parse SQL files into Abstract Syntax Trees (AST).
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pgsql parse <sqlfile> [options]
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
#### Options
|
|
58
|
+
|
|
59
|
+
| Option | Description | Default |
|
|
60
|
+
|---------------------|------------------------------------------------------|------------|
|
|
61
|
+
| `-o, --output` | Output to file instead of stdout | |
|
|
62
|
+
| `-f, --format` | Output format: `json`, `pretty` | `pretty` |
|
|
63
|
+
| `--pl` | Parse as PL/pgSQL function only | `false` |
|
|
64
|
+
| `--clean` | Clean the AST tree (remove location info) | `false` |
|
|
65
|
+
| `-h, --help` | Show help | |
|
|
66
|
+
|
|
67
|
+
#### Examples
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
# Parse SQL and output to console
|
|
71
|
+
pgsql parse query.sql
|
|
72
|
+
|
|
73
|
+
# Parse SQL and save to file
|
|
74
|
+
pgsql parse query.sql -o ast.json
|
|
75
|
+
|
|
76
|
+
# Parse PL/pgSQL function
|
|
77
|
+
pgsql parse function.sql --pl
|
|
78
|
+
|
|
79
|
+
# Parse and output compact JSON
|
|
80
|
+
pgsql parse query.sql --format json
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### `pgsql deparse`
|
|
84
|
+
|
|
85
|
+
Convert AST back to SQL.
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
pgsql deparse [options]
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
#### Options
|
|
92
|
+
|
|
93
|
+
| Option | Description | Default |
|
|
94
|
+
|---------------------|------------------------------------------------------|------------|
|
|
95
|
+
| `-i, --input` | Input JSON file (or use stdin) | |
|
|
96
|
+
| `-o, --output` | Output to file instead of stdout | |
|
|
97
|
+
| `-h, --help` | Show help | |
|
|
98
|
+
|
|
99
|
+
#### Examples
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
# Deparse from file
|
|
103
|
+
pgsql deparse -i ast.json
|
|
104
|
+
|
|
105
|
+
# Deparse from stdin
|
|
106
|
+
cat ast.json | pgsql deparse
|
|
107
|
+
|
|
108
|
+
# Parse and deparse in one line
|
|
109
|
+
pgsql parse query.sql | pgsql deparse
|
|
110
|
+
|
|
111
|
+
# Deparse to file
|
|
112
|
+
pgsql deparse -i ast.json -o query.sql
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### `pgsql proto-gen`
|
|
116
|
+
|
|
117
|
+
Generate TypeScript definitions from PostgreSQL protobuf files.
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
pgsql proto-gen --inFile <proto> --outDir <dir> [options]
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
#### Options
|
|
124
|
+
|
|
125
|
+
| Option | Description | Default |
|
|
126
|
+
|-----------------------|------------------------------------------------------|------------|
|
|
127
|
+
| `--inFile` | Input .proto file | *Required* |
|
|
128
|
+
| `--outDir` | Output directory | *Required* |
|
|
129
|
+
| `--enums` | Generate TypeScript enums | `false` |
|
|
130
|
+
| `--enums-json` | Generate JSON enum mappings | `false` |
|
|
131
|
+
| `--types` | Generate TypeScript interfaces | `false` |
|
|
132
|
+
| `--utils` | Generate utility functions | `false` |
|
|
133
|
+
| `--ast-helpers` | Generate AST helper methods | `false` |
|
|
134
|
+
| `--wrapped-helpers` | Generate wrapped AST helpers | `false` |
|
|
135
|
+
| `--optional` | Make all fields optional | `false` |
|
|
136
|
+
| `--keep-case` | Keep original field casing | `false` |
|
|
137
|
+
| `--remove-undefined` | Remove UNDEFINED enum at position 0 | `false` |
|
|
138
|
+
| `-h, --help` | Show help | |
|
|
139
|
+
|
|
140
|
+
#### Examples
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
# Generate types and enums
|
|
144
|
+
pgsql proto-gen --inFile pg_query.proto --outDir out --types --enums
|
|
145
|
+
|
|
146
|
+
# Generate everything
|
|
147
|
+
pgsql proto-gen --inFile pg_query.proto --outDir out --types --enums --utils --ast-helpers
|
|
148
|
+
|
|
149
|
+
# Generate with optional fields
|
|
150
|
+
pgsql proto-gen --inFile pg_query.proto --outDir out --types --optional
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### `pgsql proto-fetch`
|
|
154
|
+
|
|
155
|
+
Download and process proto files.
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
pgsql proto-fetch [options]
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
#### Options
|
|
162
|
+
|
|
163
|
+
| Option | Description | Default |
|
|
164
|
+
|---------------------|------------------------------------------------------|--------------------------------|
|
|
165
|
+
| `--url` | Proto file URL to download | |
|
|
166
|
+
| `--inFile` | Where to save the proto file | *Required* |
|
|
167
|
+
| `--outFile` | Generated JS output file | *Required* |
|
|
168
|
+
| `--replace-pkg` | Original package name to replace | `protobufjs/minimal` |
|
|
169
|
+
| `--with-pkg` | New package name | `@launchql/protobufjs/minimal` |
|
|
170
|
+
| `-h, --help` | Show help | |
|
|
171
|
+
|
|
172
|
+
#### Examples
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
# Download and process proto file
|
|
176
|
+
pgsql proto-fetch \
|
|
177
|
+
--url https://raw.githubusercontent.com/pganalyze/libpg_query/16-latest/protobuf/pg_query.proto \
|
|
178
|
+
--inFile pg_query.proto \
|
|
179
|
+
--outFile pg_query.js
|
|
180
|
+
|
|
181
|
+
# Process existing proto file
|
|
182
|
+
pgsql proto-fetch \
|
|
183
|
+
--inFile pg_query.proto \
|
|
184
|
+
--outFile pg_query.js \
|
|
185
|
+
--replace-pkg "protobufjs/minimal" \
|
|
186
|
+
--with-pkg "@custom/protobufjs"
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### `pgsql runtime-schema`
|
|
190
|
+
|
|
191
|
+
Generate runtime schema for AST nodes.
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
pgsql runtime-schema --inFile <proto> --outDir <dir> [options]
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
#### Options
|
|
198
|
+
|
|
199
|
+
| Option | Description | Default |
|
|
200
|
+
|---------------------|------------------------------------------------------|-------------------|
|
|
201
|
+
| `--inFile` | Input .proto file | *Required* |
|
|
202
|
+
| `--outDir` | Output directory | *Required* |
|
|
203
|
+
| `--format` | Output format: `json`, `typescript` | `json` |
|
|
204
|
+
| `--filename` | Output filename (without extension) | `runtime-schema` |
|
|
205
|
+
| `-h, --help` | Show help | |
|
|
206
|
+
|
|
207
|
+
#### Examples
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
# Generate JSON schema
|
|
211
|
+
pgsql runtime-schema --inFile pg_query.proto --outDir out
|
|
212
|
+
|
|
213
|
+
# Generate TypeScript schema
|
|
214
|
+
pgsql runtime-schema --inFile pg_query.proto --outDir out --format typescript
|
|
215
|
+
|
|
216
|
+
# Custom filename
|
|
217
|
+
pgsql runtime-schema --inFile pg_query.proto --outDir out --filename ast-schema
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
## Migration Guide
|
|
221
|
+
|
|
222
|
+
### Migrating from `pgsql-parser` CLI
|
|
223
|
+
|
|
224
|
+
If you were using the `pgsql-parser` command-line tool:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
# Old
|
|
228
|
+
pgsql-parser file.sql
|
|
229
|
+
pgsql-parser file.sql --pl
|
|
230
|
+
|
|
231
|
+
# New
|
|
232
|
+
pgsql parse file.sql
|
|
233
|
+
pgsql parse file.sql --pl
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### Migrating from `pg-proto-parser`
|
|
237
|
+
|
|
238
|
+
If you were using the `pg-proto-parser` command-line tool:
|
|
239
|
+
|
|
240
|
+
```bash
|
|
241
|
+
# Old
|
|
242
|
+
pg-proto-parser codegen --inFile pg_query.proto --outDir out
|
|
243
|
+
|
|
244
|
+
# New
|
|
245
|
+
pgsql proto-gen --inFile pg_query.proto --outDir out
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
The command options remain largely the same, with some improvements:
|
|
249
|
+
- `codegen` → `proto-gen`
|
|
250
|
+
- `protogen` → `proto-fetch`
|
|
251
|
+
- Boolean flags now use kebab-case (e.g., `--enumsJSON` → `--enums-json`)
|
|
252
|
+
|
|
253
|
+
## Related
|
|
254
|
+
|
|
255
|
+
* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.
|
|
256
|
+
* [pgsql-deparser](https://www.npmjs.com/package/pgsql-deparser): A streamlined tool designed for converting PostgreSQL ASTs back into SQL queries, focusing solely on deparser functionality to complement `pgsql-parser`.
|
|
257
|
+
* [@pgsql/parser](https://www.npmjs.com/package/@pgsql/parser): Multi-version PostgreSQL parser with dynamic version selection at runtime, supporting PostgreSQL 15, 16, and 17 in a single package.
|
|
258
|
+
* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): Offers TypeScript type definitions for PostgreSQL AST nodes, facilitating type-safe construction, analysis, and manipulation of ASTs.
|
|
259
|
+
* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): Provides TypeScript enum definitions for PostgreSQL constants, enabling type-safe usage of PostgreSQL enums and constants in your applications.
|
|
260
|
+
* [@pgsql/utils](https://www.npmjs.com/package/@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.
|
|
261
|
+
* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): A TypeScript tool that parses PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
|
|
262
|
+
* [libpg-query](https://github.com/launchql/libpg-query-node): The real PostgreSQL parser exposed for Node.js, used primarily in `pgsql-parser` for parsing and deparsing SQL queries.
|
|
263
|
+
|
|
264
|
+
## Disclaimer
|
|
265
|
+
|
|
266
|
+
AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
|
|
267
|
+
|
|
268
|
+
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.
|
package/dist/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2020 Dan Lynch <pyramation@gmail.com>
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/dist/README.md
ADDED
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
# @pgsql/cli
|
|
2
|
+
|
|
3
|
+
<p align="center" width="100%">
|
|
4
|
+
<img height="120" src="https://github.com/launchql/pgsql-parser/assets/545047/6440fa7d-918b-4a3b-8d1b-755d85de8bea" />
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center" width="100%">
|
|
8
|
+
<a href="https://github.com/launchql/pgsql-parser/actions/workflows/run-tests.yaml">
|
|
9
|
+
<img height="20" src="https://github.com/launchql/pgsql-parser/actions/workflows/run-tests.yaml/badge.svg" />
|
|
10
|
+
</a>
|
|
11
|
+
<a href="https://github.com/launchql/pgsql-parser/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
`@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.
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install -g @pgsql/cli
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Features
|
|
23
|
+
|
|
24
|
+
- **Parse SQL to AST**: Convert PostgreSQL queries into Abstract Syntax Trees
|
|
25
|
+
- **Deparse AST to SQL**: Convert AST back into SQL queries
|
|
26
|
+
- **Generate TypeScript from Protobuf**: Create type-safe TypeScript definitions from PostgreSQL protobuf files
|
|
27
|
+
- **Download and Process Proto Files**: Fetch proto files from URLs and generate JavaScript
|
|
28
|
+
- **Runtime Schema Generation**: Generate runtime schemas for AST nodes
|
|
29
|
+
- **Unified Interface**: Single CLI tool for all PostgreSQL AST operations
|
|
30
|
+
|
|
31
|
+
## Quick Start
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# Parse SQL to AST
|
|
35
|
+
pgsql parse query.sql
|
|
36
|
+
|
|
37
|
+
# Deparse AST back to SQL
|
|
38
|
+
pgsql deparse ast.json
|
|
39
|
+
|
|
40
|
+
# Generate TypeScript from protobuf
|
|
41
|
+
pgsql proto-gen --inFile pg_query.proto --outDir out --types --enums
|
|
42
|
+
|
|
43
|
+
# Download and process proto file
|
|
44
|
+
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
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Commands
|
|
48
|
+
|
|
49
|
+
### `pgsql parse`
|
|
50
|
+
|
|
51
|
+
Parse SQL files into Abstract Syntax Trees (AST).
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pgsql parse <sqlfile> [options]
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
#### Options
|
|
58
|
+
|
|
59
|
+
| Option | Description | Default |
|
|
60
|
+
|---------------------|------------------------------------------------------|------------|
|
|
61
|
+
| `-o, --output` | Output to file instead of stdout | |
|
|
62
|
+
| `-f, --format` | Output format: `json`, `pretty` | `pretty` |
|
|
63
|
+
| `--pl` | Parse as PL/pgSQL function only | `false` |
|
|
64
|
+
| `--clean` | Clean the AST tree (remove location info) | `false` |
|
|
65
|
+
| `-h, --help` | Show help | |
|
|
66
|
+
|
|
67
|
+
#### Examples
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
# Parse SQL and output to console
|
|
71
|
+
pgsql parse query.sql
|
|
72
|
+
|
|
73
|
+
# Parse SQL and save to file
|
|
74
|
+
pgsql parse query.sql -o ast.json
|
|
75
|
+
|
|
76
|
+
# Parse PL/pgSQL function
|
|
77
|
+
pgsql parse function.sql --pl
|
|
78
|
+
|
|
79
|
+
# Parse and output compact JSON
|
|
80
|
+
pgsql parse query.sql --format json
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### `pgsql deparse`
|
|
84
|
+
|
|
85
|
+
Convert AST back to SQL.
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
pgsql deparse [options]
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
#### Options
|
|
92
|
+
|
|
93
|
+
| Option | Description | Default |
|
|
94
|
+
|---------------------|------------------------------------------------------|------------|
|
|
95
|
+
| `-i, --input` | Input JSON file (or use stdin) | |
|
|
96
|
+
| `-o, --output` | Output to file instead of stdout | |
|
|
97
|
+
| `-h, --help` | Show help | |
|
|
98
|
+
|
|
99
|
+
#### Examples
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
# Deparse from file
|
|
103
|
+
pgsql deparse -i ast.json
|
|
104
|
+
|
|
105
|
+
# Deparse from stdin
|
|
106
|
+
cat ast.json | pgsql deparse
|
|
107
|
+
|
|
108
|
+
# Parse and deparse in one line
|
|
109
|
+
pgsql parse query.sql | pgsql deparse
|
|
110
|
+
|
|
111
|
+
# Deparse to file
|
|
112
|
+
pgsql deparse -i ast.json -o query.sql
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### `pgsql proto-gen`
|
|
116
|
+
|
|
117
|
+
Generate TypeScript definitions from PostgreSQL protobuf files.
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
pgsql proto-gen --inFile <proto> --outDir <dir> [options]
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
#### Options
|
|
124
|
+
|
|
125
|
+
| Option | Description | Default |
|
|
126
|
+
|-----------------------|------------------------------------------------------|------------|
|
|
127
|
+
| `--inFile` | Input .proto file | *Required* |
|
|
128
|
+
| `--outDir` | Output directory | *Required* |
|
|
129
|
+
| `--enums` | Generate TypeScript enums | `false` |
|
|
130
|
+
| `--enums-json` | Generate JSON enum mappings | `false` |
|
|
131
|
+
| `--types` | Generate TypeScript interfaces | `false` |
|
|
132
|
+
| `--utils` | Generate utility functions | `false` |
|
|
133
|
+
| `--ast-helpers` | Generate AST helper methods | `false` |
|
|
134
|
+
| `--wrapped-helpers` | Generate wrapped AST helpers | `false` |
|
|
135
|
+
| `--optional` | Make all fields optional | `false` |
|
|
136
|
+
| `--keep-case` | Keep original field casing | `false` |
|
|
137
|
+
| `--remove-undefined` | Remove UNDEFINED enum at position 0 | `false` |
|
|
138
|
+
| `-h, --help` | Show help | |
|
|
139
|
+
|
|
140
|
+
#### Examples
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
# Generate types and enums
|
|
144
|
+
pgsql proto-gen --inFile pg_query.proto --outDir out --types --enums
|
|
145
|
+
|
|
146
|
+
# Generate everything
|
|
147
|
+
pgsql proto-gen --inFile pg_query.proto --outDir out --types --enums --utils --ast-helpers
|
|
148
|
+
|
|
149
|
+
# Generate with optional fields
|
|
150
|
+
pgsql proto-gen --inFile pg_query.proto --outDir out --types --optional
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### `pgsql proto-fetch`
|
|
154
|
+
|
|
155
|
+
Download and process proto files.
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
pgsql proto-fetch [options]
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
#### Options
|
|
162
|
+
|
|
163
|
+
| Option | Description | Default |
|
|
164
|
+
|---------------------|------------------------------------------------------|--------------------------------|
|
|
165
|
+
| `--url` | Proto file URL to download | |
|
|
166
|
+
| `--inFile` | Where to save the proto file | *Required* |
|
|
167
|
+
| `--outFile` | Generated JS output file | *Required* |
|
|
168
|
+
| `--replace-pkg` | Original package name to replace | `protobufjs/minimal` |
|
|
169
|
+
| `--with-pkg` | New package name | `@launchql/protobufjs/minimal` |
|
|
170
|
+
| `-h, --help` | Show help | |
|
|
171
|
+
|
|
172
|
+
#### Examples
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
# Download and process proto file
|
|
176
|
+
pgsql proto-fetch \
|
|
177
|
+
--url https://raw.githubusercontent.com/pganalyze/libpg_query/16-latest/protobuf/pg_query.proto \
|
|
178
|
+
--inFile pg_query.proto \
|
|
179
|
+
--outFile pg_query.js
|
|
180
|
+
|
|
181
|
+
# Process existing proto file
|
|
182
|
+
pgsql proto-fetch \
|
|
183
|
+
--inFile pg_query.proto \
|
|
184
|
+
--outFile pg_query.js \
|
|
185
|
+
--replace-pkg "protobufjs/minimal" \
|
|
186
|
+
--with-pkg "@custom/protobufjs"
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### `pgsql runtime-schema`
|
|
190
|
+
|
|
191
|
+
Generate runtime schema for AST nodes.
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
pgsql runtime-schema --inFile <proto> --outDir <dir> [options]
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
#### Options
|
|
198
|
+
|
|
199
|
+
| Option | Description | Default |
|
|
200
|
+
|---------------------|------------------------------------------------------|-------------------|
|
|
201
|
+
| `--inFile` | Input .proto file | *Required* |
|
|
202
|
+
| `--outDir` | Output directory | *Required* |
|
|
203
|
+
| `--format` | Output format: `json`, `typescript` | `json` |
|
|
204
|
+
| `--filename` | Output filename (without extension) | `runtime-schema` |
|
|
205
|
+
| `-h, --help` | Show help | |
|
|
206
|
+
|
|
207
|
+
#### Examples
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
# Generate JSON schema
|
|
211
|
+
pgsql runtime-schema --inFile pg_query.proto --outDir out
|
|
212
|
+
|
|
213
|
+
# Generate TypeScript schema
|
|
214
|
+
pgsql runtime-schema --inFile pg_query.proto --outDir out --format typescript
|
|
215
|
+
|
|
216
|
+
# Custom filename
|
|
217
|
+
pgsql runtime-schema --inFile pg_query.proto --outDir out --filename ast-schema
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
## Migration Guide
|
|
221
|
+
|
|
222
|
+
### Migrating from `pgsql-parser` CLI
|
|
223
|
+
|
|
224
|
+
If you were using the `pgsql-parser` command-line tool:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
# Old
|
|
228
|
+
pgsql-parser file.sql
|
|
229
|
+
pgsql-parser file.sql --pl
|
|
230
|
+
|
|
231
|
+
# New
|
|
232
|
+
pgsql parse file.sql
|
|
233
|
+
pgsql parse file.sql --pl
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### Migrating from `pg-proto-parser`
|
|
237
|
+
|
|
238
|
+
If you were using the `pg-proto-parser` command-line tool:
|
|
239
|
+
|
|
240
|
+
```bash
|
|
241
|
+
# Old
|
|
242
|
+
pg-proto-parser codegen --inFile pg_query.proto --outDir out
|
|
243
|
+
|
|
244
|
+
# New
|
|
245
|
+
pgsql proto-gen --inFile pg_query.proto --outDir out
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
The command options remain largely the same, with some improvements:
|
|
249
|
+
- `codegen` → `proto-gen`
|
|
250
|
+
- `protogen` → `proto-fetch`
|
|
251
|
+
- Boolean flags now use kebab-case (e.g., `--enumsJSON` → `--enums-json`)
|
|
252
|
+
|
|
253
|
+
## Related
|
|
254
|
+
|
|
255
|
+
* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.
|
|
256
|
+
* [pgsql-deparser](https://www.npmjs.com/package/pgsql-deparser): A streamlined tool designed for converting PostgreSQL ASTs back into SQL queries, focusing solely on deparser functionality to complement `pgsql-parser`.
|
|
257
|
+
* [@pgsql/parser](https://www.npmjs.com/package/@pgsql/parser): Multi-version PostgreSQL parser with dynamic version selection at runtime, supporting PostgreSQL 15, 16, and 17 in a single package.
|
|
258
|
+
* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): Offers TypeScript type definitions for PostgreSQL AST nodes, facilitating type-safe construction, analysis, and manipulation of ASTs.
|
|
259
|
+
* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): Provides TypeScript enum definitions for PostgreSQL constants, enabling type-safe usage of PostgreSQL enums and constants in your applications.
|
|
260
|
+
* [@pgsql/utils](https://www.npmjs.com/package/@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.
|
|
261
|
+
* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): A TypeScript tool that parses PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
|
|
262
|
+
* [libpg-query](https://github.com/launchql/libpg-query-node): The real PostgreSQL parser exposed for Node.js, used primarily in `pgsql-parser` for parsing and deparsing SQL queries.
|
|
263
|
+
|
|
264
|
+
## Disclaimer
|
|
265
|
+
|
|
266
|
+
AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
|
|
267
|
+
|
|
268
|
+
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.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function deparseCommand(argv: any): Promise<void>;
|