Contributing to pgxcli

First off — thank you for being here. Whether you're fixing a typo, reporting a bug, or building a feature, every contribution matters. pgxcli is a solo project and contributions from the community genuinely move the needle.

Table of Contents

• I Just Have a Quick Question
• What Should I Know Before Getting Started?
• How Can I Contribute?
  • Reporting Bugs
  • Suggesting Enhancements
  • Your First Code Contribution
  • Pull Requests
• Development Setup
• Style Guide
• AI Usage
• Recognition

I Just Have a Quick Question

GitHub Issues are for bugs and feature requests only — not questions. If you're unsure whether something is a bug, start a Discussion first.

• Open a GitHub Discussion for Q&A, ideas, and general conversation.
• Check the docs — configuration, CLI reference, and guides live there.

What Should I Know Before Getting Started?

pgxcli is a single Go binary — a PostgreSQL REPL built for speed and a smooth user experience. Understanding the high-level architecture will help you find your way around quickly.

Package Structure

Layer	Package	Purpose
Entry	cmd/pgxcli/main.go	Bootstrap context & printer
CLI	internal/cli/	Cobra commands, flags, connection params
Config	internal/config/	TOML loading, validation, paths
Logger	internal/logger/	slog-based file logging
App / REPL	internal/app/	Main loop, command routing, history
Database	internal/database/	pgx connection and query execution
Parser	internal/parser/	SQL splitting and query classification
UI	internal/ui/	Interactive connection forms (Charm TUI)
Completer	internal/completer/	SQL autocomplete suggestions
Output	internal/cliio/	stdout/stderr abstraction

Key Dependencies

Dependency	Purpose	Role in pgxcli
pgx	PostgreSQL driver	Core — all DB connections and queries
cobra	CLI framework	Core — every command is built on this
viper	Config management	Core — handles all config file parsing
tablewriter	Table rendering	UI — formats query results in the terminal
go-prompter	Interactive prompts	UI — handles REPL input and history

How Can I Contribute?

Reporting Bugs

Before opening a bug report:

• Check existing issues — if the bug is already reported and still open, leave a comment there instead of opening a new one.
• Try to reproduce the issue on the latest release.

When filing a bug, please include:

• A clear, specific title. "pgxcli crashes" is not helpful. "pgxcli panics when running \d on a table with no columns" is.
• Steps to reproduce — as precise as possible.
• Expected vs. actual behavior.
• Your environment: OS, architecture, pgxcli version (pgxcli --version), PostgreSQL version.
• Relevant config from ~/.config/pgxcli/config.toml, if applicable.
• A stack trace or terminal output, pasted in a fenced code block.

Please use the bug report template when available.

Suggesting Enhancements

Feature ideas are welcome. Before submitting one:

• Search existing issues and discussions to avoid duplicates.
• Check the roadmap — it might already be planned.

A good enhancement request includes:

• What problem it solves — not just what it does.
• How you'd expect it to work from the user's perspective.
• Alternatives you've considered, and why this approach is better.
• Examples from other tools, if relevant (psql, pgcli, usql, etc.).

Please use the feature request template when available.

Your First Code Contribution

Not sure where to start? Look for issues tagged:

• good first issue — small, well-scoped, good for getting familiar with the codebase.
• help wanted — meaningful contributions that don't require deep context.

Issues are sorted by comment count as a rough proxy for impact.

Pull Requests

1. Fork the repo and create your branch from main.
2. Set up your dev environment (see Development Setup below).
3. Make your changes. Keep scope focused — one fix or feature per PR.
4. Add or update tests for whatever you changed.
5. Run golangci-lint run and resolve any new warnings before pushing.
6. Open a PR against main with a clear description of what changed and why. Link any related issues.
7. Be responsive — if a reviewer leaves feedback, engage with it promptly.

For roadmap-sized features (streaming results, browser table view, export formats), open a Discussion first to align on approach before writing significant code.

Note: All status checks must pass before a PR is reviewed. If a check fails for an unrelated reason, leave a comment explaining why.

Development Setup

Prerequisites: Go 1.26.4+, a running PostgreSQL instance (local or via Docker).

# Clone your fork
git clone https://github.com/<your-username>/pgxcli.git
cd pgxcli

# Install dependencies
go mod download

# Run from source
go run ./cmd/pgxcli --help

# Build the binary
go build -o pgxcli ./cmd/pgxcli

# Run tests
go test ./...

# Lint — install golangci-lint first: https://golangci-lint.run/usage/install/
golangci-lint run

For a quick local PostgreSQL instance via Docker:

docker run --rm -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16

Then connect:

go run ./cmd/pgxcli --host localhost --port 5432 --user postgres --dbname postgres

Style Guide

• Follow standard Go conventions — gofmt is non-negotiable.
• Run golangci-lint run before committing. Fix all new warnings.
• Prefer table-driven tests using t.Run(...).
• All exported functions and types must have doc comments.
• Avoid unnecessary abstractions — pgxcli values clarity over cleverness.

AI Usage

AI tools are welcome in your workflow — with some boundaries.

We discourage submitting AI-generated code directly into core Go source files (packages like internal/database/, internal/app/, internal/parser/, etc.). These are load-bearing parts of the codebase where correctness, clarity, and intentionality matter. AI-generated logic here tends to introduce subtle bugs or patterns that are hard to review and maintain.

We actively encourage using AI for:

• Test cases — generating table-driven tests, edge case coverage, and test scaffolding.
• Docs & comments — writing or improving godoc comments, README sections, and guides.
• Release notes — summarizing changelogs and formatting release content.
• Understanding the codebase — using AI to explore, explain, or map out unfamiliar parts before diving in.
• Vulnerability hunting — prompting AI to review code for security issues, edge cases, or misuse of APIs.
• Non-critical tooling — scripts, CI config, Dockerfiles, and other supporting files.

The rule of thumb: if it's going into a .go file that runs in production, write it yourself and understand every line. If it's helping you around that work — use whatever tools help you do it better.

Recognition

Every merged contribution gets credited in the release notes. Significant contributors will be added to the ACKNOWLEDGMENTS section of the README.

Thank you for taking the time to improve pgxcli. 🙌