If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/sosedoff/pgweb shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2w ago
• 13 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 78% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live sosedoff/pgweb repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sosedoff/pgweb.

What it runs against: a local clone of sosedoff/pgweb — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in sosedoff/pgweb | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 41 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sosedoff/pgweb. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sosedoff/pgweb.git
#   cd pgweb
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of sosedoff/pgweb and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sosedoff/pgweb(\\.git)?\\b" \\
  && ok "origin remote is sosedoff/pgweb" \\
  || miss "origin remote is not sosedoff/pgweb (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "pkg/api/api.go" \\
  && ok "pkg/api/api.go" \\
  || miss "missing critical file: pkg/api/api.go"
test -f "pkg/client/client.go" \\
  && ok "pkg/client/client.go" \\
  || miss "missing critical file: pkg/client/client.go"
test -f "pkg/connection/connection_string.go" \\
  && ok "pkg/connection/connection_string.go" \\
  || miss "missing critical file: pkg/connection/connection_string.go"
test -f "pkg/bookmarks/bookmarks.go" \\
  && ok "pkg/bookmarks/bookmarks.go" \\
  || miss "missing critical file: pkg/bookmarks/bookmarks.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 41 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~11d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/sosedoff/pgweb"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Pgweb is a lightweight, cross-platform web UI for PostgreSQL databases written in Go that bundles frontend (JavaScript/HTML) and backend (Go API) into a single binary with zero external dependencies. It lets users browse database schemas, execute SQL queries, export results to CSV/JSON/XML, and manage multiple database sessions through a browser interface without installation overhead. Monolithic binary architecture: main.go is the entry point; pkg/api/api.go contains the REST API handlers (built with Gin); pkg/ organizes database logic, SSH tunneling, and bookmarks; static assets (HTML/CSS/JavaScript) are embedded or served from public/; config/ holds example SSH backends and system integration files (systemd service, FreeBSD rc); Dockerfile provides container builds with multi-stage optimization.

Database administrators and developers who need quick, portable access to PostgreSQL instances for ad-hoc querying and exploration—particularly those running pgweb on remote servers via Docker or as a standalone binary, and teams managing multiple database bookmarks and SSH tunneled connections.

Production-ready with active maintenance: the repo uses Go 1.25.4, has comprehensive CI workflows (.github/workflows/ with checks, deploy, docker, and release automation), includes Docker support with pull counts, and maintains consistent release distribution. The codebase is stable with well-structured testing (Makefile test targets, test-all for multi-version PostgreSQL validation) and clear documentation (CONTRIBUTING.md, SCREENS.md, WIKI).

Low risk overall: single primary maintainer (sosedoff) but well-established project with active releases; dependency footprint is lean (~15 direct Go dependencies, all well-maintained like gin-gonic, lib/pq, sqlx). Main constraints are PostgreSQL 9.1+ requirement and reliance on lib/pq as the sole database driver—no vendor redundancy. No evidence of stale code (release workflow active), though security-sensitive features (SSH tunneling via ScaleFT/sshkeys, password handling via jackc/pgpassfile) warrant careful review for sensitive deployments.

Active release cycle visible through .github/workflows/release.yml and deploy.yml; recent toolchain upgrade to Go 1.25.4 suggests ongoing maintenance. The repo includes demo deployment configuration (fly.toml for https://pgweb-demo.fly.dev/) and multi-database backend examples in config/examples/ (Go and Ruby connect backends), indicating feature expansion around custom connection handlers.

git clone https://github.com/sosedoff/pgweb.git
cd pgweb
make
./pgweb --host localhost --user postgres --db postgres

Then open http://localhost:8081 in your browser. For Docker: docker-compose up using docker-compose.yml or docker-compose-pg.yml. Requires PostgreSQL 9.1+ running locally for make test.

Daily commands: Development: make build compiles binary to ./pgweb; make test runs full test suite against local PostgreSQL (requires postgres user with CREATE DATABASE); make test-all runs multi-version tests in Docker. Production: ./pgweb [flags] (e.g., ./pgweb --url postgres://user:pass@host/db --sessions to enable multi-session mode). Docker: docker build -t pgweb . && docker run -p 8081:8081 pgweb or use compose files.

• main.go — Application entry point that initializes the CLI, parses flags, and starts the web server or backend connection.
• pkg/api/api.go — Core API server implementation using Gin framework; defines all HTTP handlers and request routing for the web UI.
• pkg/client/client.go — PostgreSQL connection abstraction layer; handles query execution, result formatting, and database introspection.
• pkg/connection/connection_string.go — Connection string parsing and validation logic; critical for establishing secure PostgreSQL connections.
• pkg/bookmarks/bookmarks.go — Bookmark persistence layer for saved database connections; essential for user workflow and configuration management.
• pkg/api/session_manager.go — HTTP session and state management; handles concurrent database connections and user session isolation.
• pkg/cli/cli.go — Command-line interface definition and execution; bridges user input to core application logic.

Add a new API endpoint

1. Define the handler function in pkg/api/api.go following the Gin handler signature (pkg/api/api.go)
2. Register the route in the routes group in pkg/api/routes.go with appropriate HTTP method (pkg/api/routes.go)
3. Add request/response types to pkg/api/types.go if using custom structs (pkg/api/types.go)
4. Use pkg/api/helpers.go functions like sendJSON() or sendError() for consistent responses (pkg/api/helpers.go)
5. Write tests in pkg/api/api_test.go using the existing test patterns (pkg/api/api_test.go)

Add a new database query capability

1. Implement the query method in pkg/client/client.go that calls the PostgreSQL driver (pkg/client/client.go)
2. Parse results using pkg/client/result.go conversion functions if specialized formatting needed (pkg/client/result.go)
3. Create an API endpoint that calls the client method (see API endpoint pattern above) (pkg/api/api.go)
4. Add unit tests for the client method in pkg/client/client_test.go (pkg/client/client_test.go)

Add support for a new connection configuration option

1. Add the flag definition to pkg/command/options.go with appropriate struct tags (pkg/command/options.go)
2. Update the connection string builder in pkg/connection/connection_string.go to include the new option (pkg/connection/connection_string.go)
3. Update bookmark structures in pkg/bookmarks/bookmarks.go TOML tags if persisting the option (pkg/bookmarks/bookmarks.go)
4. Add integration tests in pkg/connection/connection_string_test.go (pkg/connection/connection_string_test.go)

Add a new monitoring metric

1. Define the Prometheus metric in pkg/metrics/metrics.go following client_golang patterns (pkg/metrics/metrics.go)
2. Record the metric at relevant points in pkg/client/client.go or pkg/api/api.go (pkg/metrics/metrics.go)
3. The metric is automatically exposed on the metrics HTTP server via pkg/metrics/server.go (pkg/metrics/server.go)

• Go 1.25 — Enables single-binary cross-platform distribution (Mac/Linux/Windows) with zero runtime dependencies, critical for pgweb's 'simple installation' goal
• Gin Web Framework — Lightweight HTTP server for serving the web UI and REST API; handles routing, middleware, and request/response efficiently
• lib/pq (PostgreSQL driver) — Pure Go PostgreSQL driver; enables zero external dependencies while providing full access to all PostgreSQL protocols and features
• Prometheus client_golang — Standard observability framework; exposes metrics for monitoring production deployments at scale
• TOML for bookmarks — Human-readable configuration format for persisting saved database connections; easier for users to edit directly than JSON or binary formats

• Single-binary distribution model

  • Why: Matches user expectation of 'simple installation' and zero dependencies; critical UX requirement
  • Consequence: Cannot embed large assets (frontend) statically; requires separate asset serving or bundling via build toolchain

• In-process session management instead of distributed cache (Redis)

  • Why: Maintains zero external dependencies and simplifies deployment for single-user or small-team use cases
  • Consequence: Cannot scale horizontally; each pgweb instance has isolated session state; not suitable for load-balanced multi-instance deployments

• SSH tunnel support via golang.org/x/crypto

  • Why: Enables
  • Consequence: undefined

1. PostgreSQL must be running on localhost:5432 with a 'postgres' user capable of CREATE DATABASE for make test to pass—tests are integration tests, not mocked. 2. PGWEB_SESSIONS=1 env var or --sessions flag must be explicitly set for multi-session support; single-session is default. 3. Static assets likely embedded: if modifying frontend files (HTML/CSS/JS), they may be embedded via go-bindata or similar (check main.go for //go:embed directives). 4. SSH tunneling requires ScaleFT/sshkeys: passfile loading uses jackc/pgpassfile; .pgpass permissions and ~/.ssh/ key setup are implicit prerequisites for SSH features. 5. SSLMODE defaults to 'disable' in connection strings; URL parsing via lib/pq requires explicit ?sslmode=require for production.

• SSH Tunneling (Port Forwarding) — pgweb uses ScaleFT/sshkeys to establish secure proxied connections to remote PostgreSQL instances; critical for safe production deployments where direct database access is forbidden
• Connection Pooling — jmoiron/sqlx manages multiple concurrent database connections; understanding pool exhaustion and idle timeouts is essential for diagnosing multi-session performance issues
• Prepared Statements & SQL Injection Prevention — pgweb accepts arbitrary user SQL queries; lib/pq's parameterized query support ($1, $2 placeholders) is the primary defense against injection attacks
• PostgreSQL Wire Protocol (libpq) — lib/pq implements the PostgreSQL frontend/backend wire protocol; understanding message framing helps debug connection hangs and protocol-level errors
• Gin Web Framework Middleware & Routing — pgweb's REST API is built on Gin (like Express.js but Go); middleware stack handles CORS, logging, and authentication; routing patterns determine API extensibility
• Prometheus Metrics Export — prometheus/client_golang integration enables monitoring of pgweb query latency, connection counts, and error rates in production; critical for observability
• Go Embedding (go:embed directive) — pgweb's static assets (HTML/CSS/JavaScript) are likely embedded into the binary at compile time; understanding embed mechanics is necessary for asset modification workflows

• dbeaver/dbeaver — Feature-complete Java-based database IDE that includes PostgreSQL + multi-database support; positioned as pgweb's heavyweight alternative for desktop use
• adminer/adminer — Single-file PHP database explorer supporting PostgreSQL, MySQL, SQLite; similar lightweight web-based philosophy but older codebase and heavier dependencies
• jackc/pgx — Pure Go PostgreSQL driver used by pgweb's ecosystem; understanding pgx internals helps debug connection pooling and prepared statement behavior in pgweb
• golang-migrate/migrate — Database migration tool for PostgreSQL often paired with pgweb for schema versioning; complements pgweb's ad-hoc query execution with automated schema evolution
• getgauge/gauge — Not directly related but pgweb's testing philosophy (integration tests against real PostgreSQL) mirrors Gauge's approach to acceptance testing; relevant for understanding pgweb's test design

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for pkg/bookmarks/manager.go

The bookmarks manager handles persistence and loading of database connection bookmarks from TOML files. While pkg/bookmarks/bookmarks_test.go exists, there are no visible tests for manager.go which handles the critical I/O operations. Given test data files exist (data/bookmark*.toml), this is a high-value addition to prevent regressions in bookmark loading, SSH configuration, and SSL certificate handling.

• [ ] Create pkg/bookmarks/manager_test.go with test cases for LoadBookmarks() covering valid/invalid TOML files
• [ ] Add tests for bookmark file persistence and update operations
• [ ] Test edge cases using existing test data: data/bookmark_invalid_ssl.toml, data/bookmark_with_ssh.toml, data/bookmark_url.toml
• [ ] Verify SSH key handling and SSL certificate path validation through manager methods

Add integration tests in GitHub Actions for SSH bookmark connections

The repo has config/examples for SSH tunnel backends (config/examples/connect_backend_go/main.go) and test data for SSH bookmarks (data/bookmark_with_ssh.toml), but .github/workflows/checks.yml likely doesn't test SSH connection flows. This would catch regressions in the ScaleFT/sshkeys dependency and SSH tunnel establishment without manual testing.

• [ ] Review .github/workflows/checks.yml to confirm SSH integration tests are missing
• [ ] Create a new workflow step using docker-compose to spin up PostgreSQL with SSH tunneling
• [ ] Use the existing config/examples/connect_backend_go as a reference implementation
• [ ] Add test case that connects via SSH bookmark and executes a simple query to verify tunnel integrity

Add unit tests for pkg/api/middleware.go

The middleware.go file handles HTTP request/response processing and likely contains critical security logic, session validation, and error handling. No corresponding middleware_test.go file exists in the file structure. Given the API serves a web database explorer with potential security implications, comprehensive middleware testing is essential.

• [ ] Create pkg/api/middleware_test.go with test cases for authentication/authorization middleware
• [ ] Add tests for CORS handling, request logging, and error response formatting
• [ ] Test session validation and cookie/token handling through middleware chains
• [ ] Reference pkg/api/session_manager_test.go patterns to ensure consistency with existing test style

• Add test coverage for pkg/api/helpers.go: helpers.go likely contains utility functions for response serialization, error handling, and data formatting, but no dedicated test file exists. Create pkg/api/helpers_test.go with table-driven tests for CSV/JSON/XML export edge cases and error response formatting.
• Document SSH tunnel configuration in CONTRIBUTING.md: config/examples/ shows SSH backends but CONTRIBUTING.md has no section on testing SSH features locally. Add a short guide: 'Testing SSH Tunnels' that explains .pgpass setup, known_hosts, and how to run integration tests against tunneled connections.
• Add GitHub issue template for database-specific bugs: .github/workflows/ has CI but no issue templates (.github/ISSUE_TEMPLATE/*.md). Create a PostgreSQL version + pgweb version + connection details template to reduce support burden and improve bug reports for version-specific failures (e.g., PostgreSQL 9.1 vs. 16 syntax differences).

• High · Outdated Go Version with Known CVEs — go.mod, Dockerfile. The project uses Go 1.25.4, which is beyond the latest stable release (1.23.x as of current standards). This version may contain unpatched vulnerabilities. Additionally, the golang:1.25-trixie base image in Dockerfile may not receive security updates. Fix: Update to a stable, well-maintained Go version (1.22.x or 1.23.x) and verify all dependencies are compatible.
• High · Hardcoded Database Credentials in docker-compose.yml — docker-compose.yml. Database credentials are hardcoded in plain text in the docker-compose.yml file: POSTGRES_PASSWORD=pgweb and POSTGRES_USER=pgweb. This is exposed in version control and could be exploited. Fix: Use Docker secrets, environment files (.env with .gitignore), or orchestration platform secrets management. Never commit credentials to version control.
• High · Disabled SSL/TLS in Database Connection — docker-compose.yml - PGWEB_DATABASE_URL. The docker-compose.yml explicitly disables SSL mode (sslmode=disable) in the connection string. This means database traffic is unencrypted and vulnerable to man-in-the-middle attacks. Fix: Enable SSL/TLS for database connections (sslmode=require or sslmode=verify-full). Only disable for development when absolutely necessary and document it clearly.
• High · Outdated PostgreSQL Client Library — go.mod. The project uses 'github.com/lib/pq v1.10.5', released in 2021. Newer versions (1.10.9+) contain important security patches. This is the primary database driver and should be kept current. Fix: Update github.com/lib/pq to v1.10.9 or later. Consider migrating to pgx driver which is more actively maintained.
• High · Deprecated SSH Key Handling Library — go.mod. The project uses 'github.com/ScaleFT/sshkeys v0.0.0-20200327173127-6142f742bca5', last updated in 2020. SSH key handling is security-critical and this unmaintained dependency is a risk. Fix: Replace with golang.org/x/crypto/ssh or a more actively maintained SSH library. Review all SSH-related code for vulnerabilities.
• Medium · Potential SQL Injection Risk in Query Handling — pkg/client/client.go, pkg/api/routes.go. The file structure shows pkg/client/client.go which likely handles SQL queries. Without examining the actual code, the presence of client query handling combined with a web interface (Gin framework) suggests potential SQL injection vectors if parameterized queries aren't consistently used. Fix: Audit all SQL query construction to ensure parameterized queries (prepared statements) are used universally. Never concatenate user input into SQL strings.
• Medium · CGO Disabled in Build but Not Enforced — Dockerfile. The Dockerfile sets CGO_ENABLED=0 as default but uses ARG which can be overridden at build time without visibility. If CGO is enabled with certain dependencies, it could introduce C library vulnerabilities. Fix: Document CGO requirements clearly. Consider using 'ENV CGO_ENABLED=0' without ARG override to enforce static linking. Scan C dependencies if CGO is required.
• Medium · Missing Security Headers in Web Framework — pkg/api/middleware.go, pkg/api/api.go. The project uses Gin framework (github.com/gin-gonic/gin) for the web API. Without examining middleware.go, it's unclear if security headers (CSP, X-Frame-Options, X-Content-Type-Options, HSTS) are properly configured. Fix: Implement comprehensive security headers middleware. Add Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and HSTS headers.
• Medium · Insecure Random Number Generation Dependency — undefined. The project uses Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.