pgplan 0.0.2 → 0.2.1
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/README.md +200 -47
- package/bin/pgplan +58 -0
- package/package.json +29 -7
- package/DESIGN.md +0 -169
- package/LICENSE +0 -21
- package/cmd/analyze.go +0 -39
- package/cmd/compare.go +0 -39
- package/cmd/init.go +0 -39
- package/cmd/root.go +0 -46
- package/go.mod +0 -9
- package/go.sum +0 -11
- package/main.go +0 -10
package/README.md
CHANGED
|
@@ -1,47 +1,200 @@
|
|
|
1
|
-
# pgplan
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
#
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
1
|
+
# pgplan
|
|
2
|
+
|
|
3
|
+
A command-line tool for analyzing and comparing PostgreSQL query execution plans. Get optimization insights and track performance regressions without leaving your terminal.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **Plan Analysis** - Run 15+ intelligent rules against a query plan to surface performance issues with actionable fix suggestions
|
|
8
|
+
- **Plan Comparison** - Semantically diff two plans side-by-side to understand what changed and whether it got better or worse
|
|
9
|
+
- **Flexible Input** - Accept JSON EXPLAIN output, raw SQL files, stdin, or paste plans interactively
|
|
10
|
+
- **Connection Profiles** - Save and manage named PostgreSQL connection strings for quick reuse
|
|
11
|
+
- **Multiple Output Formats** - Human-readable colored terminal output or structured JSON for tooling integration
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
### [Go](https://pkg.go.dev/github.com/jacobarthurs/pgplan)
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
go install github.com/jacobarthurs/pgplan@latest
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
### [NPM](https://www.npmjs.com/package/pgplan)
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm i -g pgplan
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### Binary
|
|
28
|
+
|
|
29
|
+
Download the latest release for your platform from the [releases page](https://github.com/JacobArthurs/pgplan/releases/latest).
|
|
30
|
+
|
|
31
|
+
## Quick Start
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# Analyze a query plan from a JSON EXPLAIN output
|
|
35
|
+
pgplan analyze plan.json
|
|
36
|
+
|
|
37
|
+
# Analyze by running a SQL file against a database
|
|
38
|
+
pgplan analyze query.sql --db postgres://localhost:5432/mydb
|
|
39
|
+
|
|
40
|
+
# Compare two plans
|
|
41
|
+
pgplan compare before.json after.json
|
|
42
|
+
|
|
43
|
+
# Interactive mode - paste plans or queries directly into the terminal
|
|
44
|
+
pgplan analyze
|
|
45
|
+
pgplan compare
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Commands
|
|
49
|
+
|
|
50
|
+
### `pgplan analyze [file]`
|
|
51
|
+
|
|
52
|
+
Analyzes a single query plan and returns optimization findings sorted by severity.
|
|
53
|
+
|
|
54
|
+
**Arguments:**
|
|
55
|
+
|
|
56
|
+
| Argument | Description |
|
|
57
|
+
| -------- | ----------- |
|
|
58
|
+
| `file` | Path to a `.json` (EXPLAIN output) or `.sql` file. Use `-` for stdin. Omit for interactive mode. |
|
|
59
|
+
|
|
60
|
+
**Flags:**
|
|
61
|
+
|
|
62
|
+
| Flag | Description |
|
|
63
|
+
| ---- | ----------- |
|
|
64
|
+
| `-d, --db` | PostgreSQL connection string (required for SQL input) |
|
|
65
|
+
| `-p, --profile` | Named connection profile to use |
|
|
66
|
+
| `-f, --format` | Output format: `text` (default) or `json` |
|
|
67
|
+
|
|
68
|
+
**Example:**
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
pgplan analyze slow-query.sql --profile prod
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### `pgplan compare [file1] [file2]`
|
|
75
|
+
|
|
76
|
+
Compares two query plans and reports on cost, time, row estimate, and buffer differences across every node in the plan tree.
|
|
77
|
+
|
|
78
|
+
**Arguments:**
|
|
79
|
+
|
|
80
|
+
| Argument | Description |
|
|
81
|
+
| -------- | ----------- |
|
|
82
|
+
| `file1` | The "before" plan. `.json`, `.sql`, `-` for stdin, or omit for interactive. |
|
|
83
|
+
| `file2` | The "after" plan. Same input options as `file1`. |
|
|
84
|
+
|
|
85
|
+
**Flags:**
|
|
86
|
+
|
|
87
|
+
| Flag | Description |
|
|
88
|
+
| ---- | ----------- |
|
|
89
|
+
| `-d, --db` | PostgreSQL connection string (required for SQL input) |
|
|
90
|
+
| `-p, --profile` | Named connection profile to use |
|
|
91
|
+
| `-f, --format` | Output format: `text` (default) or `json` |
|
|
92
|
+
| `-t, --threshold` | Percent change threshold for significance (default: `5`) |
|
|
93
|
+
|
|
94
|
+
**Example:**
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
pgplan compare before.json after.json --threshold 10
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### `pgplan profile <subcommand>`
|
|
101
|
+
|
|
102
|
+
Manages saved PostgreSQL connection profiles stored in `~/.config/pgplan/profiles.yaml`.
|
|
103
|
+
|
|
104
|
+
| Subcommand | Description |
|
|
105
|
+
| ---------- | ----------- |
|
|
106
|
+
| `list [--show]` | List saved profiles. Pass `--show` to display connection strings. |
|
|
107
|
+
| `add <name> <conn_str>` | Add or update a named profile. |
|
|
108
|
+
| `remove <name>` | Remove a profile. |
|
|
109
|
+
| `default <name>` | Set a profile as the default. |
|
|
110
|
+
| `clear-default` | Clear the default profile. |
|
|
111
|
+
|
|
112
|
+
**Example:**
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
pgplan profile add prod postgres://user:pass@host:5432/mydb
|
|
116
|
+
pgplan profile default prod
|
|
117
|
+
|
|
118
|
+
# Now use it with analyze or compare
|
|
119
|
+
pgplan analyze query.sql --profile prod
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Analysis Rules
|
|
123
|
+
|
|
124
|
+
The `analyze` command applies the following rules to identify performance issues. Each finding includes a severity level and an actionable suggestion.
|
|
125
|
+
|
|
126
|
+
| Severity | Rule | Description |
|
|
127
|
+
| -------- | ---- | ----------- |
|
|
128
|
+
| Critical | Sort Spill to Disk | Sort operation exceeded `work_mem` and spilled to disk |
|
|
129
|
+
| Warning | Hash Spill to Disk | Hash table exceeded `work_mem` |
|
|
130
|
+
| Warning | Temp Block I/O | Plan is reading/writing temporary blocks |
|
|
131
|
+
| Warning | Seq Scan in Join | Sequential scan used inside a join against a smaller set |
|
|
132
|
+
| Warning | Seq Scan with Filter | Standalone sequential scan filtering a large number of rows |
|
|
133
|
+
| Warning | Index Scan Filter Inefficiency | Index scan is fetching many rows then discarding most via filter |
|
|
134
|
+
| Warning | Bitmap Heap Recheck | Lossy bitmap scan rechecking conditions (bitmap exceeded `work_mem`) |
|
|
135
|
+
| Warning | Nested Loop High Loops | Nested loop executing 1,000+ iterations |
|
|
136
|
+
| Warning | Correlated Subplan | Subplan re-executing on every outer row |
|
|
137
|
+
| Warning | Worker Launch Mismatch | Fewer parallel workers launched than planned |
|
|
138
|
+
| Warning | Parallel Overhead | Parallel execution is slower than the serial estimate |
|
|
139
|
+
| Warning | Large Join Filter Removal | Join filter is discarding a large percentage of rows |
|
|
140
|
+
| Warning | Excessive Materialization | Materialize node looping many times |
|
|
141
|
+
| Info | Low Selectivity Index Scan | Index scan is returning most of the table |
|
|
142
|
+
| Info | Wide Row Output | Query is selecting more columns than necessary |
|
|
143
|
+
|
|
144
|
+
## Comparison Output
|
|
145
|
+
|
|
146
|
+
The `compare` command produces a structured diff of two plans including:
|
|
147
|
+
|
|
148
|
+
- **Summary** - Overall cost, execution time, and buffer changes with directional indicators
|
|
149
|
+
- **Node Details** - Per-node breakdown of metric changes (cost, rows, loops, buffers, filters, indexes)
|
|
150
|
+
- **Verdict** - A final assessment such as "faster and cheaper" or "slower but cheaper"
|
|
151
|
+
|
|
152
|
+
Changes below the significance threshold (default 5%) are filtered out to reduce noise.
|
|
153
|
+
|
|
154
|
+
## Output Formats
|
|
155
|
+
|
|
156
|
+
### Text (default)
|
|
157
|
+
|
|
158
|
+
Colored terminal output with severity-coded findings and directional change indicators. Designed for quick human review.
|
|
159
|
+
|
|
160
|
+
### JSON
|
|
161
|
+
|
|
162
|
+
Structured output suitable for piping into other tools, CI systems, or dashboards. Includes all metrics, findings, and comparison deltas.
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
pgplan analyze plan.json --format json | jq '.findings[] | select(.severity == "critical")'
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
## Configuration
|
|
169
|
+
|
|
170
|
+
### Connection Profiles
|
|
171
|
+
|
|
172
|
+
Profiles are stored in a YAML configuration file at the platform-appropriate config directory:
|
|
173
|
+
|
|
174
|
+
- **Linux/macOS:** `~/.config/pgplan/profiles.yaml`
|
|
175
|
+
- **Windows:** `%APPDATA%\pgplan\profiles.yaml`
|
|
176
|
+
|
|
177
|
+
```yaml
|
|
178
|
+
default: prod
|
|
179
|
+
profiles:
|
|
180
|
+
- name: prod
|
|
181
|
+
conn_str: postgres://user:pass@host:5432/production
|
|
182
|
+
- name: dev
|
|
183
|
+
conn_str: postgres://localhost:5432/development
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Use `--profile <name>` with any command, or set a default to skip the flag entirely. The `--db` and `--profile` flags are mutually exclusive.
|
|
187
|
+
|
|
188
|
+
## Contributing
|
|
189
|
+
|
|
190
|
+
Contributions are welcome! To get started:
|
|
191
|
+
|
|
192
|
+
1. Fork the repository
|
|
193
|
+
2. Create a feature branch (`git checkout -b my-new-feature`)
|
|
194
|
+
3. Open a pull request
|
|
195
|
+
|
|
196
|
+
CI will automatically run tests and linting on your PR.
|
|
197
|
+
|
|
198
|
+
## License
|
|
199
|
+
|
|
200
|
+
This project is licensed under the [MIT License](LICENSE).
|
package/bin/pgplan
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
"use strict";
|
|
4
|
+
|
|
5
|
+
const { execFileSync } = require("child_process");
|
|
6
|
+
const path = require("path");
|
|
7
|
+
const os = require("os");
|
|
8
|
+
|
|
9
|
+
const PLATFORMS = {
|
|
10
|
+
"linux-x64": { pkg: "@pgplan/linux-x64", bin: "pgplan" },
|
|
11
|
+
"linux-arm64": { pkg: "@pgplan/linux-arm64", bin: "pgplan" },
|
|
12
|
+
"darwin-x64": { pkg: "@pgplan/darwin-x64", bin: "pgplan" },
|
|
13
|
+
"darwin-arm64": { pkg: "@pgplan/darwin-arm64", bin: "pgplan" },
|
|
14
|
+
"win32-x64": { pkg: "@pgplan/win32-x64", bin: "pgplan.exe" },
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
function getPlatformKey() {
|
|
18
|
+
const platform = os.platform();
|
|
19
|
+
const arch = os.arch();
|
|
20
|
+
return `${platform}-${arch}`;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
function getBinaryPath() {
|
|
24
|
+
const key = getPlatformKey();
|
|
25
|
+
const entry = PLATFORMS[key];
|
|
26
|
+
if (!entry) {
|
|
27
|
+
const supported = Object.keys(PLATFORMS).join(", ");
|
|
28
|
+
console.error(
|
|
29
|
+
`pgplan: unsupported platform ${key}\nSupported: ${supported}`
|
|
30
|
+
);
|
|
31
|
+
process.exit(1);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
try {
|
|
35
|
+
const pkgPath = require.resolve(`${entry.pkg}/package.json`);
|
|
36
|
+
return path.join(path.dirname(pkgPath), entry.bin);
|
|
37
|
+
} catch {
|
|
38
|
+
console.error(
|
|
39
|
+
`pgplan: platform package ${entry.pkg} not installed.\n` +
|
|
40
|
+
`Try reinstalling: npm install pgplan`
|
|
41
|
+
);
|
|
42
|
+
process.exit(1);
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const binary = getBinaryPath();
|
|
47
|
+
|
|
48
|
+
try {
|
|
49
|
+
const result = execFileSync(binary, process.argv.slice(2), {
|
|
50
|
+
stdio: "inherit",
|
|
51
|
+
env: process.env,
|
|
52
|
+
});
|
|
53
|
+
} catch (e) {
|
|
54
|
+
if (e.status !== null) {
|
|
55
|
+
process.exit(e.status);
|
|
56
|
+
}
|
|
57
|
+
throw e;
|
|
58
|
+
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,29 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "pgplan",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
5
|
-
"
|
|
6
|
-
|
|
7
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "pgplan",
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"description": "Analyze and compare PostgreSQL query plans",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "git+https://github.com/JacobArthurs/pgplan.git"
|
|
8
|
+
},
|
|
9
|
+
"author": "Jacob Arthurs",
|
|
10
|
+
"license": "MIT",
|
|
11
|
+
"bugs": {
|
|
12
|
+
"url": "https://github.com/JacobArthurs/pgplan/issues"
|
|
13
|
+
},
|
|
14
|
+
"homepage": "https://github.com/JacobArthurs/pgplan",
|
|
15
|
+
"bin": {
|
|
16
|
+
"pgplan": "bin/pgplan"
|
|
17
|
+
},
|
|
18
|
+
"files": [
|
|
19
|
+
"bin/**",
|
|
20
|
+
"README.md"
|
|
21
|
+
],
|
|
22
|
+
"optionalDependencies": {
|
|
23
|
+
"@pgplan/linux-x64": "0.2.1",
|
|
24
|
+
"@pgplan/linux-arm64": "0.2.1",
|
|
25
|
+
"@pgplan/darwin-x64": "0.2.1",
|
|
26
|
+
"@pgplan/darwin-arm64": "0.2.1",
|
|
27
|
+
"@pgplan/win32-x64": "0.2.1"
|
|
28
|
+
}
|
|
29
|
+
}
|
package/DESIGN.md
DELETED
|
@@ -1,169 +0,0 @@
|
|
|
1
|
-
# pgplan design
|
|
2
|
-
|
|
3
|
-
## Project Goals
|
|
4
|
-
|
|
5
|
-
- Compare PostgreSQL EXPLAIN plans with semantic understanding
|
|
6
|
-
- Provide CLI-native analysis without browser dependency
|
|
7
|
-
- Support multiple input formats (SQL, JSON, TEXT)
|
|
8
|
-
- Offer actionable optimization recommendations
|
|
9
|
-
|
|
10
|
-
## Commands
|
|
11
|
-
|
|
12
|
-
```text
|
|
13
|
-
pgplan compare [file1] [file2] [OPTIONS] Compare two query plans
|
|
14
|
-
pgplan analyze [file] [OPTIONS] Analyze a single query plan
|
|
15
|
-
pgplan init Create ~/.config/pgplan/config.yml with example template
|
|
16
|
-
pgplan --help Show help
|
|
17
|
-
pgplan --version Show version
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
## pgplan compare [file1] [file2] [OPTIONS]
|
|
21
|
-
|
|
22
|
-
### Compare Files
|
|
23
|
-
|
|
24
|
-
- `file1` and `file2` are optional
|
|
25
|
-
- Can be SQL files, JSON files (EXPLAIN output), or TEXT files (EXPLAIN output)
|
|
26
|
-
- Either file (but not both) can be `-` to read from stdin
|
|
27
|
-
- Files don't need to be the same type
|
|
28
|
-
- If no files provided, enters interactive mode
|
|
29
|
-
|
|
30
|
-
### Compare Options
|
|
31
|
-
|
|
32
|
-
| Flag | Description |
|
|
33
|
-
| ------------------- | --------------------------------------- |
|
|
34
|
-
| `--db <connection>` | PostgreSQL connection string |
|
|
35
|
-
| `--profile <name>` | Use named profile from config |
|
|
36
|
-
| `--format <type>` | Output format: `text` (default), `json` |
|
|
37
|
-
|
|
38
|
-
### Compare Connection Resolution (only needed for SQL input)
|
|
39
|
-
|
|
40
|
-
1. If `--db` flag provided, use it
|
|
41
|
-
2. Else if `--profile` flag provided, load from config.yml
|
|
42
|
-
3. Else if config.yml exists with `default_profile`, use default
|
|
43
|
-
4. Else, error with helpful message
|
|
44
|
-
|
|
45
|
-
### Compare Behavior
|
|
46
|
-
|
|
47
|
-
Process each input independently:
|
|
48
|
-
|
|
49
|
-
- SQL: requires DB connection, wraps query in `EXPLAIN (ANALYZE, FORMAT JSON)` and captures output
|
|
50
|
-
- JSON: parse directly
|
|
51
|
-
- EXPLAIN TEXT: parse directly
|
|
52
|
-
|
|
53
|
-
Then compare the two resulting plans.
|
|
54
|
-
|
|
55
|
-
### Compare Examples
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
|
-
# Interactive mode (no files)
|
|
59
|
-
pgplan compare
|
|
60
|
-
|
|
61
|
-
# From files (any combination)
|
|
62
|
-
pgplan compare old.sql new.sql --db postgres://localhost/mydb
|
|
63
|
-
pgplan compare prod-plan.json new-query.sql --profile dev
|
|
64
|
-
|
|
65
|
-
# Read one plan from stdin
|
|
66
|
-
psql -c "EXPLAIN (ANALYZE, FORMAT JSON) SELECT ..." | pgplan compare - new.sql --db postgres://localhost/mydb
|
|
67
|
-
pgplan compare old-plan.json - < new-plan.json
|
|
68
|
-
|
|
69
|
-
# Using default profile
|
|
70
|
-
pgplan compare old.sql new.sql
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
## pgplan analyze [file] [OPTIONS]
|
|
74
|
-
|
|
75
|
-
### Analyze File
|
|
76
|
-
|
|
77
|
-
- `file` is optional
|
|
78
|
-
- Can be a SQL file, JSON file (EXPLAIN output), or TEXT file (EXPLAIN output)
|
|
79
|
-
- Use `-` for stdin
|
|
80
|
-
- If no file provided, enters interactive mode
|
|
81
|
-
|
|
82
|
-
### Analyze Options
|
|
83
|
-
|
|
84
|
-
| Flag | Description |
|
|
85
|
-
| ------------------- | --------------------------------------- |
|
|
86
|
-
| `--db <connection>` | PostgreSQL connection string |
|
|
87
|
-
| `--profile <name>` | Use named profile from config |
|
|
88
|
-
| `--format <type>` | Output format: `text` (default), `json` |
|
|
89
|
-
|
|
90
|
-
### Analyze Connection Resolution (only needed for SQL input)
|
|
91
|
-
|
|
92
|
-
Same as `pgplan compare`.
|
|
93
|
-
|
|
94
|
-
### Analyze Behavior
|
|
95
|
-
|
|
96
|
-
Process input:
|
|
97
|
-
|
|
98
|
-
- SQL: requires DB connection, wraps query in `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` and captures output
|
|
99
|
-
- JSON: parse directly
|
|
100
|
-
- EXPLAIN TEXT: parse directly
|
|
101
|
-
|
|
102
|
-
Then analyze the plan and provide insights:
|
|
103
|
-
|
|
104
|
-
- Execution summary (time, cost, rows)
|
|
105
|
-
- Detected issues (seq scans, high filter ratios, missing indexes)
|
|
106
|
-
- Node-by-node breakdown
|
|
107
|
-
- Recommendations for optimization
|
|
108
|
-
|
|
109
|
-
### Analyze Interactive Mode
|
|
110
|
-
|
|
111
|
-
If no file provided:
|
|
112
|
-
|
|
113
|
-
```text
|
|
114
|
-
pgplan analyze
|
|
115
|
-
|
|
116
|
-
→ Paste or type query or query plan (Ctrl+D or Ctrl+Z when done):
|
|
117
|
-
[user pastes content]
|
|
118
|
-
^D
|
|
119
|
-
|
|
120
|
-
→ Auto-detect input type
|
|
121
|
-
→ If SQL, resolve DB connection
|
|
122
|
-
→ Analyze plan
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
### Analyze Examples
|
|
126
|
-
|
|
127
|
-
```bash
|
|
128
|
-
# Interactive mode
|
|
129
|
-
pgplan analyze
|
|
130
|
-
|
|
131
|
-
# Analyze SQL file
|
|
132
|
-
pgplan analyze slow-query.sql --db postgres://localhost/mydb
|
|
133
|
-
|
|
134
|
-
# Analyze saved EXPLAIN output
|
|
135
|
-
pgplan analyze prod-slow-plan.json
|
|
136
|
-
|
|
137
|
-
# Analyze from stdin
|
|
138
|
-
pgplan analyze -
|
|
139
|
-
|
|
140
|
-
# Pipe from psql
|
|
141
|
-
psql -c "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT ..." | pgplan analyze -
|
|
142
|
-
|
|
143
|
-
# Using profile
|
|
144
|
-
pgplan analyze query.sql --profile prod
|
|
145
|
-
|
|
146
|
-
# JSON output for scripting
|
|
147
|
-
pgplan analyze query.sql --db postgres://localhost/mydb --format json
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
## Config File (optional)
|
|
151
|
-
|
|
152
|
-
Location: `~/.config/pgplan/config.yml`
|
|
153
|
-
|
|
154
|
-
```yaml
|
|
155
|
-
profiles:
|
|
156
|
-
dev:
|
|
157
|
-
host: localhost
|
|
158
|
-
database: myapp_dev
|
|
159
|
-
user: postgres
|
|
160
|
-
password: dev_pass
|
|
161
|
-
|
|
162
|
-
prod:
|
|
163
|
-
host: prod.example.com
|
|
164
|
-
database: myapp_prod
|
|
165
|
-
user: readonly
|
|
166
|
-
password: prod_pass
|
|
167
|
-
|
|
168
|
-
default_profile: dev
|
|
169
|
-
```
|
package/LICENSE
DELETED
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 Jacob Arthurs
|
|
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/cmd/analyze.go
DELETED
|
@@ -1,39 +0,0 @@
|
|
|
1
|
-
/*
|
|
2
|
-
Copyright © 2026 JACOB ARTHURS
|
|
3
|
-
*/
|
|
4
|
-
package cmd
|
|
5
|
-
|
|
6
|
-
import (
|
|
7
|
-
"fmt"
|
|
8
|
-
|
|
9
|
-
"github.com/spf13/cobra"
|
|
10
|
-
)
|
|
11
|
-
|
|
12
|
-
// analyzeCmd represents the analyze command
|
|
13
|
-
var analyzeCmd = &cobra.Command{
|
|
14
|
-
Use: "analyze",
|
|
15
|
-
Short: "A brief description of your command",
|
|
16
|
-
Long: `A longer description that spans multiple lines and likely contains examples
|
|
17
|
-
and usage of using your command. For example:
|
|
18
|
-
|
|
19
|
-
Cobra is a CLI library for Go that empowers applications.
|
|
20
|
-
This application is a tool to generate the needed files
|
|
21
|
-
to quickly create a Cobra application.`,
|
|
22
|
-
Run: func(cmd *cobra.Command, args []string) {
|
|
23
|
-
fmt.Println("analyze called")
|
|
24
|
-
},
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
func init() {
|
|
28
|
-
rootCmd.AddCommand(analyzeCmd)
|
|
29
|
-
|
|
30
|
-
// Here you will define your flags and configuration settings.
|
|
31
|
-
|
|
32
|
-
// Cobra supports Persistent Flags which will work for this command
|
|
33
|
-
// and all subcommands, e.g.:
|
|
34
|
-
// analyzeCmd.PersistentFlags().String("foo", "", "A help for foo")
|
|
35
|
-
|
|
36
|
-
// Cobra supports local flags which will only run when this command
|
|
37
|
-
// is called directly, e.g.:
|
|
38
|
-
// analyzeCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
|
|
39
|
-
}
|
package/cmd/compare.go
DELETED
|
@@ -1,39 +0,0 @@
|
|
|
1
|
-
/*
|
|
2
|
-
Copyright © 2026 JACOB ARTHURS
|
|
3
|
-
*/
|
|
4
|
-
package cmd
|
|
5
|
-
|
|
6
|
-
import (
|
|
7
|
-
"fmt"
|
|
8
|
-
|
|
9
|
-
"github.com/spf13/cobra"
|
|
10
|
-
)
|
|
11
|
-
|
|
12
|
-
// compareCmd represents the compare command
|
|
13
|
-
var compareCmd = &cobra.Command{
|
|
14
|
-
Use: "compare",
|
|
15
|
-
Short: "A brief description of your command",
|
|
16
|
-
Long: `A longer description that spans multiple lines and likely contains examples
|
|
17
|
-
and usage of using your command. For example:
|
|
18
|
-
|
|
19
|
-
Cobra is a CLI library for Go that empowers applications.
|
|
20
|
-
This application is a tool to generate the needed files
|
|
21
|
-
to quickly create a Cobra application.`,
|
|
22
|
-
Run: func(cmd *cobra.Command, args []string) {
|
|
23
|
-
fmt.Println("compare called")
|
|
24
|
-
},
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
func init() {
|
|
28
|
-
rootCmd.AddCommand(compareCmd)
|
|
29
|
-
|
|
30
|
-
// Here you will define your flags and configuration settings.
|
|
31
|
-
|
|
32
|
-
// Cobra supports Persistent Flags which will work for this command
|
|
33
|
-
// and all subcommands, e.g.:
|
|
34
|
-
// compareCmd.PersistentFlags().String("foo", "", "A help for foo")
|
|
35
|
-
|
|
36
|
-
// Cobra supports local flags which will only run when this command
|
|
37
|
-
// is called directly, e.g.:
|
|
38
|
-
// compareCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
|
|
39
|
-
}
|
package/cmd/init.go
DELETED
|
@@ -1,39 +0,0 @@
|
|
|
1
|
-
/*
|
|
2
|
-
Copyright © 2026 JACOB ARTHURS
|
|
3
|
-
*/
|
|
4
|
-
package cmd
|
|
5
|
-
|
|
6
|
-
import (
|
|
7
|
-
"fmt"
|
|
8
|
-
|
|
9
|
-
"github.com/spf13/cobra"
|
|
10
|
-
)
|
|
11
|
-
|
|
12
|
-
// initCmd represents the init command
|
|
13
|
-
var initCmd = &cobra.Command{
|
|
14
|
-
Use: "init",
|
|
15
|
-
Short: "A brief description of your command",
|
|
16
|
-
Long: `A longer description that spans multiple lines and likely contains examples
|
|
17
|
-
and usage of using your command. For example:
|
|
18
|
-
|
|
19
|
-
Cobra is a CLI library for Go that empowers applications.
|
|
20
|
-
This application is a tool to generate the needed files
|
|
21
|
-
to quickly create a Cobra application.`,
|
|
22
|
-
Run: func(cmd *cobra.Command, args []string) {
|
|
23
|
-
fmt.Println("init called")
|
|
24
|
-
},
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
func init() {
|
|
28
|
-
rootCmd.AddCommand(initCmd)
|
|
29
|
-
|
|
30
|
-
// Here you will define your flags and configuration settings.
|
|
31
|
-
|
|
32
|
-
// Cobra supports Persistent Flags which will work for this command
|
|
33
|
-
// and all subcommands, e.g.:
|
|
34
|
-
// initCmd.PersistentFlags().String("foo", "", "A help for foo")
|
|
35
|
-
|
|
36
|
-
// Cobra supports local flags which will only run when this command
|
|
37
|
-
// is called directly, e.g.:
|
|
38
|
-
// initCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
|
|
39
|
-
}
|
package/cmd/root.go
DELETED
|
@@ -1,46 +0,0 @@
|
|
|
1
|
-
/*
|
|
2
|
-
Copyright © 2026 JACOB ARTHURS
|
|
3
|
-
*/
|
|
4
|
-
package cmd
|
|
5
|
-
|
|
6
|
-
import (
|
|
7
|
-
"os"
|
|
8
|
-
|
|
9
|
-
"github.com/spf13/cobra"
|
|
10
|
-
)
|
|
11
|
-
|
|
12
|
-
// rootCmd represents the base command when called without any subcommands
|
|
13
|
-
var rootCmd = &cobra.Command{
|
|
14
|
-
Use: "pgplan",
|
|
15
|
-
Short: "A brief description of your application",
|
|
16
|
-
Long: `A longer description that spans multiple lines and likely contains
|
|
17
|
-
examples and usage of using your application. For example:
|
|
18
|
-
|
|
19
|
-
Cobra is a CLI library for Go that empowers applications.
|
|
20
|
-
This application is a tool to generate the needed files
|
|
21
|
-
to quickly create a Cobra application.`,
|
|
22
|
-
// Uncomment the following line if your bare application
|
|
23
|
-
// has an action associated with it:
|
|
24
|
-
// Run: func(cmd *cobra.Command, args []string) { },
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
// Execute adds all child commands to the root command and sets flags appropriately.
|
|
28
|
-
// This is called by main.main(). It only needs to happen once to the rootCmd.
|
|
29
|
-
func Execute() {
|
|
30
|
-
err := rootCmd.Execute()
|
|
31
|
-
if err != nil {
|
|
32
|
-
os.Exit(1)
|
|
33
|
-
}
|
|
34
|
-
}
|
|
35
|
-
|
|
36
|
-
func init() {
|
|
37
|
-
// Here you will define your flags and configuration settings.
|
|
38
|
-
// Cobra supports persistent flags, which, if defined here,
|
|
39
|
-
// will be global for your application.
|
|
40
|
-
|
|
41
|
-
// rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.pgplan.yaml)")
|
|
42
|
-
|
|
43
|
-
// Cobra also supports local flags, which will only run
|
|
44
|
-
// when this action is called directly.
|
|
45
|
-
rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
|
|
46
|
-
}
|
package/go.mod
DELETED
package/go.sum
DELETED
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
|
|
2
|
-
github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
|
|
3
|
-
github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
|
|
4
|
-
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
|
|
5
|
-
github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
|
|
6
|
-
github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
|
|
7
|
-
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
|
|
8
|
-
github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
|
|
9
|
-
github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
|
|
10
|
-
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
|
|
11
|
-
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|