feat: driver abstraction and PostgreSQL driver

[mickamy]

Summary

Introduces the driver abstraction and a complete PostgreSQL 14+ implementation — the data layer behind the three screens dbtop renders (Activity, Metrics, Statements).

The TUI is driver-independent: it only consumes []Backend, MetricSample, and []Statement. This PR lands the contract plus the first concrete driver, all verified against a live PostgreSQL.

What's included

Driver contract (internal/driver)

• Driver interface: Activity / Metrics / Statements / ResetStatements / Cancel / Terminate / Capabilities / Close.
• Normalized domain types so the TUI never sees driver-specific shapes: Backend (with a normalized State enum), MetricSample (raw counters + gauges; rates derived downstream), Statement, and Capabilities.

PostgreSQL driver (internal/driver/postgres)

• Connection setup over pgxpool (small pool, max 3) with a PG 14+ version guard.
• Activity: pg_stat_activity + pg_blocking_pids, server-side now() durations, NULL handling, sorted by the displayed duration.
• Metrics: connection breakdown, TPS/cache/tuples/temp counters, waiting locks, and replica lag — connection counts exclude dbtop's own pool connections.
• Statements / ResetStatements: pg_stat_statements digest ranking.
• Cancel / Terminate: pg_cancel_backend / pg_terminate_backend, surfacing "no such backend" as an error rather than crashing.
• Capabilities: probes superuser / pg_monitor / pg_signal_backend / pg_stat_statements for graceful degradation.

Helpers

• internal/ptr (OrZero, Map) and internal/durations (FromSeconds, FromMillis) for NULL-safe scanning and time normalization.

Testing

• Unit tests for all pure logic (state mapping, duration selection, helpers).

• Integration tests behind a //go:build integration tag, driven by DBTOP_TEST_DSN:

  DBTOP_TEST_DSN=postgres://... go test -tags integration ./internal/driver/postgres/
  

• Every query was additionally verified against a live PostgreSQL 16 (activity snapshot, idle-in-transaction state, cancel of a running query, statements digest with reset, metrics) during development.

Notes

• MySQL 8.0 driver and the TUI itself are out of scope for this PR (v0.2 / follow-ups per the design doc).
• temp_files / temp_bytes are cumulative counters; rendering them as a rate is left to the TUI layer.

[gemini-code-assist]

Code Review

This pull request introduces the driver interfaces and PostgreSQL-specific implementations for dbtop, including activity tracking, metrics sampling, capabilities detection, and statement statistics. It also includes utility packages for durations and pointer helpers, along with comprehensive unit and integration tests. The reviewer provided valuable feedback on two issues in the PostgreSQL activity query: first, a high-severity issue where idle connections could be sorted to the top of the activity list due to stale query start times, and second, a medium-severity issue where scanning the integer[] returned by pg_blocking_pids into a Go []int64 slice might cause type mismatch errors depending on the driver configuration.

[mickamy]

/gemini review

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered ☂️

[gemini-code-assist]

Code Review

This pull request introduces a database driver interface and a PostgreSQL 14+ implementation for the dbtop database monitoring tool. It includes capabilities to fetch database activity, system metrics, replica lag, and statement statistics. The review feedback highlights a few critical improvements: ensuring superusers are correctly granted monitor and kill capabilities, filtering out dbtop's own connections from the active backends list to reduce noise, and restricting statement statistics to the current database to prevent UI clutter.

[mickamy]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a PostgreSQL driver implementation for dbtop, establishing the core interfaces and structures for monitoring database activity, metrics, capabilities, and statements. It includes unit and integration tests to verify the driver's behavior. The feedback highlights two high-severity issues in the SQL queries within activity.go and metrics.go, where comparing application_name directly with a placeholder filters out connections with NULL application names, leading to incomplete activity lists and inaccurate connection metrics. It is recommended to use coalesce to handle NULL values correctly.

[mickamy]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the core database driver interfaces and a PostgreSQL 14+ driver implementation for dbtop. It defines models for database activity, metrics, and statements, along with helper utilities for durations and pointers. A review comment recommends defensively checking and initializing cfg.ConnConfig.RuntimeParams to prevent a potential nil map assignment panic.