pgplan 0.0.1

package/DESIGN.md

@@ -0,0 +1,169 @@
+# pgplan design
+
+## Project Goals
+
+- Compare PostgreSQL EXPLAIN plans with semantic understanding
+- Provide CLI-native analysis without browser dependency  
+- Support multiple input formats (SQL, JSON, TEXT)
+- Offer actionable optimization recommendations
+
+## Commands
+
+```text
+pgplan compare [file1] [file2] [OPTIONS]   Compare two query plans
+pgplan analyze [file] [OPTIONS]            Analyze a single query plan
+pgplan init                                Create ~/.config/pgplan/config.yml with example template
+pgplan --help                              Show help
+pgplan --version                           Show version
+```
+
+## pgplan compare [file1] [file2] [OPTIONS]
+
+### Compare Files
+
+- `file1` and `file2` are optional
+- Can be SQL files, JSON files (EXPLAIN output), or TEXT files (EXPLAIN output)
+- Either file (but not both) can be `-` to read from stdin
+- Files don't need to be the same type
+- If no files provided, enters interactive mode
+
+### Compare Options
+
+| Flag                | Description                             |
+| ------------------- | --------------------------------------- |
+| `--db <connection>` | PostgreSQL connection string            |
+| `--profile <name>`  | Use named profile from config           |
+| `--format <type>`   | Output format: `text` (default), `json` |
+
+### Compare Connection Resolution (only needed for SQL input)
+
+1. If `--db` flag provided, use it
+2. Else if `--profile` flag provided, load from config.yml
+3. Else if config.yml exists with `default_profile`, use default
+4. Else, error with helpful message
+
+### Compare Behavior
+
+Process each input independently:
+
+- SQL: requires DB connection, wraps query in `EXPLAIN (ANALYZE, FORMAT JSON)` and captures output
+- JSON: parse directly
+- EXPLAIN TEXT: parse directly
+
+Then compare the two resulting plans.
+
+### Compare Examples
+
+```bash
+# Interactive mode (no files)
+pgplan compare
+
+# From files (any combination)
+pgplan compare old.sql new.sql --db postgres://localhost/mydb
+pgplan compare prod-plan.json new-query.sql --profile dev
+
+# Read one plan from stdin
+psql -c "EXPLAIN (ANALYZE, FORMAT JSON) SELECT ..." | pgplan compare - new.sql --db postgres://localhost/mydb
+pgplan compare old-plan.json - < new-plan.json
+
+# Using default profile
+pgplan compare old.sql new.sql
+```
+
+## pgplan analyze [file] [OPTIONS]
+
+### Analyze File
+
+- `file` is optional
+- Can be a SQL file, JSON file (EXPLAIN output), or TEXT file (EXPLAIN output)
+- Use `-` for stdin
+- If no file provided, enters interactive mode
+
+### Analyze Options
+
+| Flag                | Description                             |
+| ------------------- | --------------------------------------- |
+| `--db <connection>` | PostgreSQL connection string            |
+| `--profile <name>`  | Use named profile from config           |
+| `--format <type>`   | Output format: `text` (default), `json` |
+
+### Analyze Connection Resolution (only needed for SQL input)
+
+Same as `pgplan compare`.
+
+### Analyze Behavior
+
+Process input:
+
+- SQL: requires DB connection, wraps query in `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` and captures output
+- JSON: parse directly
+- EXPLAIN TEXT: parse directly
+
+Then analyze the plan and provide insights:
+
+- Execution summary (time, cost, rows)
+- Detected issues (seq scans, high filter ratios, missing indexes)
+- Node-by-node breakdown
+- Recommendations for optimization
+
+### Analyze Interactive Mode
+
+If no file provided:
+
+```text
+pgplan analyze
+
+→ Paste or type query or query plan (Ctrl+D or Ctrl+Z when done):
+[user pastes content]
+^D
+
+→ Auto-detect input type
+→ If SQL, resolve DB connection
+→ Analyze plan
+```
+
+### Analyze Examples
+
+```bash
+# Interactive mode
+pgplan analyze
+
+# Analyze SQL file
+pgplan analyze slow-query.sql --db postgres://localhost/mydb
+
+# Analyze saved EXPLAIN output
+pgplan analyze prod-slow-plan.json
+
+# Analyze from stdin
+pgplan analyze -
+
+# Pipe from psql
+psql -c "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT ..." | pgplan analyze -
+
+# Using profile
+pgplan analyze query.sql --profile prod
+
+# JSON output for scripting
+pgplan analyze query.sql --db postgres://localhost/mydb --format json
+```
+
+## Config File (optional)
+
+Location: `~/.config/pgplan/config.yml`
+
+```yaml
+profiles:
+  dev:
+    host: localhost
+    database: myapp_dev
+    user: postgres
+    password: dev_pass
+
+  prod:
+    host: prod.example.com
+    database: myapp_prod
+    user: readonly
+    password: prod_pass
+
+default_profile: dev
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Arthurs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# pgplan
+
+> ⚠️ **Early Development** - Not ready for production use
+
+Compare and analyze PostgreSQL EXPLAIN plans from the CLI.
+
+## Why?
+
+Understand query performance regressions and get optimization insights without leaving your terminal.
+
+## Planned Features
+
+- [ ] EXPLAIN plan parsing (JSON, TEXT formats)
+- [ ] Intelligent plan comparison with semantic diff
+- [ ] Single plan analysis with recommendations
+- [ ] Interactive mode (paste plans directly)
+- [ ] Connection profiles for multiple databases
+- [ ] Web interface
+
+## Installation
+
+Not yet published. Clone and run locally:
+
+```bash
+git clone https://github.com/JacobArthurs/pgplan
+cd pgplan
+```
+
+## Usage (Planned)
+
+```bash
+# Compare two query plans
+pgplan compare old.sql new.sql --db postgres://localhost/mydb
+
+# Analyze a single query
+pgplan analyze slow-query.sql --profile prod
+
+# Interactive mode
+pgplan compare
+# Paste Plan A, then Plan B
+```
+
+## Development
+
+Contributions welcome! This is an early-stage project.
+
+MIT License

package/cmd/analyze.go

@@ -0,0 +1,39 @@
+/*
+Copyright © 2026 JACOB ARTHURS
+*/
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+// analyzeCmd represents the analyze command
+var analyzeCmd = &cobra.Command{
+	Use:   "analyze",
+	Short: "A brief description of your command",
+	Long: `A longer description that spans multiple lines and likely contains examples
+and usage of using your command. For example:
+
+Cobra is a CLI library for Go that empowers applications.
+This application is a tool to generate the needed files
+to quickly create a Cobra application.`,
+	Run: func(cmd *cobra.Command, args []string) {
+		fmt.Println("analyze called")
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(analyzeCmd)
+
+	// Here you will define your flags and configuration settings.
+
+	// Cobra supports Persistent Flags which will work for this command
+	// and all subcommands, e.g.:
+	// analyzeCmd.PersistentFlags().String("foo", "", "A help for foo")
+
+	// Cobra supports local flags which will only run when this command
+	// is called directly, e.g.:
+	// analyzeCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
+}

package/cmd/compare.go

@@ -0,0 +1,39 @@
+/*
+Copyright © 2026 JACOB ARTHURS
+*/
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+// compareCmd represents the compare command
+var compareCmd = &cobra.Command{
+	Use:   "compare",
+	Short: "A brief description of your command",
+	Long: `A longer description that spans multiple lines and likely contains examples
+and usage of using your command. For example:
+
+Cobra is a CLI library for Go that empowers applications.
+This application is a tool to generate the needed files
+to quickly create a Cobra application.`,
+	Run: func(cmd *cobra.Command, args []string) {
+		fmt.Println("compare called")
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(compareCmd)
+
+	// Here you will define your flags and configuration settings.
+
+	// Cobra supports Persistent Flags which will work for this command
+	// and all subcommands, e.g.:
+	// compareCmd.PersistentFlags().String("foo", "", "A help for foo")
+
+	// Cobra supports local flags which will only run when this command
+	// is called directly, e.g.:
+	// compareCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
+}

package/cmd/init.go

@@ -0,0 +1,39 @@
+/*
+Copyright © 2026 JACOB ARTHURS
+*/
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+// initCmd represents the init command
+var initCmd = &cobra.Command{
+	Use:   "init",
+	Short: "A brief description of your command",
+	Long: `A longer description that spans multiple lines and likely contains examples
+and usage of using your command. For example:
+
+Cobra is a CLI library for Go that empowers applications.
+This application is a tool to generate the needed files
+to quickly create a Cobra application.`,
+	Run: func(cmd *cobra.Command, args []string) {
+		fmt.Println("init called")
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(initCmd)
+
+	// Here you will define your flags and configuration settings.
+
+	// Cobra supports Persistent Flags which will work for this command
+	// and all subcommands, e.g.:
+	// initCmd.PersistentFlags().String("foo", "", "A help for foo")
+
+	// Cobra supports local flags which will only run when this command
+	// is called directly, e.g.:
+	// initCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
+}

package/cmd/root.go

@@ -0,0 +1,46 @@
+/*
+Copyright © 2026 JACOB ARTHURS
+*/
+package cmd
+
+import (
+	"os"
+
+	"github.com/spf13/cobra"
+)
+
+// rootCmd represents the base command when called without any subcommands
+var rootCmd = &cobra.Command{
+	Use:   "pgplan",
+	Short: "A brief description of your application",
+	Long: `A longer description that spans multiple lines and likely contains
+examples and usage of using your application. For example:
+
+Cobra is a CLI library for Go that empowers applications.
+This application is a tool to generate the needed files
+to quickly create a Cobra application.`,
+	// Uncomment the following line if your bare application
+	// has an action associated with it:
+	// Run: func(cmd *cobra.Command, args []string) { },
+}
+
+// Execute adds all child commands to the root command and sets flags appropriately.
+// This is called by main.main(). It only needs to happen once to the rootCmd.
+func Execute() {
+	err := rootCmd.Execute()
+	if err != nil {
+		os.Exit(1)
+	}
+}
+
+func init() {
+	// Here you will define your flags and configuration settings.
+	// Cobra supports persistent flags, which, if defined here,
+	// will be global for your application.
+
+	// rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.pgplan.yaml)")
+
+	// Cobra also supports local flags, which will only run
+	// when this action is called directly.
+	rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
+}

package/go.mod

@@ -0,0 +1,9 @@
+module pgplan
+
+go 1.25.6
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/cobra v1.10.2
+	github.com/spf13/pflag v1.0.10 // indirect
+)

package/go.sum

@@ -0,0 +1,11 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
+github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

package/main.go

@@ -0,0 +1,10 @@
+/*
+Copyright © 2026 JACOB ARTHURS
+*/
+package main
+
+import "pgplan/cmd"
+
+func main() {
+	cmd.Execute()
+}

package/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "pgplan",
+  "version": "0.0.1",
+  "description": "Compare and analyze PostgreSQL EXPLAIN plans from the CLI",
+  "private": false
+}