Documentation
¶
Overview ¶
Package preflight runs read-only checks against a PostgreSQL instance to answer: "is this database ready to be a DBGorilla collector source?"
Each check returns a storage-agnostic Result with a severity and, when relevant, copy-pastable fix commands. The check logic is isolated from pgx via the Inspector port; the pgxInspector adapter is the only thing that imports pgx, so the rules are unit-testable against an in-memory fake.
Index ¶
- func ContainsLib(libs, needle string) bool
- func DSNSummary(dsn string) string
- type Inspector
- type Report
- type Result
- func CheckExtension(ctx context.Context, ins Inspector) Result
- func CheckServerVersion(ctx context.Context, ins Inspector) Result
- func CheckSharedPreload(ctx context.Context, ins Inspector) Result
- func CheckStatsGrants(ctx context.Context, ins Inspector) Result
- func CheckTopologyGrants(ctx context.Context, ins Inspector) Result
- func CheckTrackFunctions(ctx context.Context, ins Inspector) Result
- func CheckTrackIOTiming(ctx context.Context, ins Inspector) Result
- func CheckWorkload(ctx context.Context, dsn string) Result
- type Severity
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContainsLib ¶
ContainsLib reports whether a comma-separated preload list contains needle.
func DSNSummary ¶
DSNSummary returns a host/db-only view of a DSN, hiding credentials.
Types ¶
type Inspector ¶
type Inspector interface {
Summary() string
ServerVersionNum(ctx context.Context) (string, error)
ShowParam(ctx context.Context, name string) (string, error)
HasExtension(ctx context.Context, name string) (bool, error)
// MaintenanceDBHasExtension checks for the extension in the `postgres`
// maintenance database -- the DB the collector's capability probe connects
// to, which can differ from the target DB this preflight is connected to.
MaintenanceDBHasExtension(ctx context.Context, name string) (bool, error)
CanReadStats(ctx context.Context) error
UnreadableUserTables(ctx context.Context) (int, error)
}
Inspector is the port the checks read DB state through.
type Report ¶
type Report struct {
Results []Result
}
Report aggregates all check results from a run.
func Run ¶
Run opens a pgx connection to dsn and runs all checks. A connection failure short-circuits to a single Fail result.
func (Report) HasWarnings ¶
HasWarnings returns true if any result is a Warn.
type Result ¶
type Result struct {
Name string
Severity Severity
Detail string
// Fix, when non-empty, is copy-pastable remediation. Empty on OK.
Fix []string
}
Result is the outcome of one preflight check.
func CheckExtension ¶
CheckExtension requires pg_stat_statements in the `postgres` MAINTENANCE database -- the DB the collector's capability probe actually connects to. This is deliberately NOT (only) the target/business DB: if the extension lives only in the target DB, the collector probes `postgres`, finds nothing, and silently advertises NO workload -- topology flows but the Queries views stay permanently empty with no error. So we gate on the maintenance DB and call out the target-only divergence explicitly (dbgorilla-cli#14).
func CheckServerVersion ¶
CheckServerVersion requires Postgres 13+.
func CheckSharedPreload ¶
CheckSharedPreload requires pg_stat_statements in shared_preload_libraries.
func CheckStatsGrants ¶
CheckStatsGrants requires the role to be able to read pg_stat_statements.
func CheckTopologyGrants ¶
CheckTopologyGrants warns if the role cannot read every user table. The topology scrape uses pg_dump, which LOCKs each table IN ACCESS SHARE MODE and reads its definition; without read access the scrape fails and the topology view stays empty (metrics are unaffected). pg_read_all_stats is NOT enough -- it grants stats, not table data.
func CheckTrackFunctions ¶
CheckTrackFunctions warns if track_functions is 'none'.
func CheckTrackIOTiming ¶
CheckTrackIOTiming warns if track_io_timing is off.
func CheckWorkload ¶ added in v0.3.0
CheckWorkload opens a connection to dsn and returns ONLY the workload (pg_stat_statements) capability check -- the `postgres` maintenance-DB probe that determines whether query/workload data flows. It lets `dbg collector status` answer "topology works but the Queries views are empty" without running the full preflight. A connection failure degrades to a Warn so status never hard-errors on a transiently-unreachable DB.
Source Files