How s19835/pg-opt-toolkit works
Project type and purpose
• This is a Go-based CLI tool (“PostgreSQL Query Optimizer Toolkit”) for running EXPLAIN ANALYZE, parsing the resulting JSON plan, and highlighting basic bottlenecks in PostgreSQL queries.
File structure
• cmd/pgopt: entry point (CLI using cobra)
• internal/config: reads YAML/env via Viper
• internal/connector: opens and manages pgx database connections
• internal/analyzer: core logic that examines parsed plans and flags slow operations
• pkg/queryplan: JSON plan parser, builds intermediate representations
• pkg/models: Go structs modeling plan nodes and analysis results
• go.mod/go.sum: module and dependency management
README for additional insights
• Uses cobra for CLI, viper for configuration, pgx for DB driver
• Workflow: user runs pgopt analyze "<SQL>" → connect to Postgres → run EXPLAIN ANALYZE → parse/ analyze → print human-readable output
a. Main components
• CLI Layer (cmd/pgopt)
• Configuration Layer (internal/config + Viper)
• Connector Layer (internal/connector + pgx)
• QueryPlan Parser (pkg/queryplan)
• Domain Models (pkg/models)
• Analyzer Engine (internal/analyzer)
• External System: PostgreSQL Database
• End-User/Terminal
b. Relationships & interactions
1. User invokes CLI command →
2. CLI Layer loads configuration from files/env →
3. Connector Layer establishes connection to Postgres →
4. Connector Layer issues EXPLAIN ANALYZE →
5. JSON plan is returned →
6. QueryPlan Parser deserializes JSON into domain models →
7. Analyzer Engine processes models to detect bottlenecks →
8. CLI Layer formats and outputs analysis to terminal
c. Architectural patterns & design principles
• Layered architecture (presentation → config → connector → domain → analysis)
• Clear separation of concerns (CLI vs. config vs. data access vs. business logic)
• Internal vs. pkg distinction: internal packages are non-public, pkg is reusable
d. Key technologies & libraries
• Go 1.18+
• cobra (CLI)
• viper (config)
• pgx/v5 (PostgreSQL driver)
• encoding/json (built-in JSON parsing)