Skip to content

inspect --all-instances: every Aurora writer and reader behind one endpoint (experimental) #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alexshapalov wants to merge 2 commits into
base: main
Choose a base branch
from
Open

inspect --all-instances: every Aurora writer and reader behind one endpoint (experimental) #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fd36c9e
feat(inspect): --all-instances — every Aurora writer and reader behin…
alexshapalov Sep 7, 2026
e2de73a
Merge branch 'main' into feat/aurora-all-instances
alexshapalov Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
All notable changes to pgbot are documented here. The format follows
[Keep a Changelog](https://keepachangelog.com/), and the project aims for
[Semantic Versioning](https://semver.org/). The `--json` contract is versioned
separately by `model.SchemaVersion` (currently 1.2.0).
separately by `model.SchemaVersion` (currently 1.3.0).

## [Unreleased]

Expand All @@ -21,6 +21,20 @@ separately by `model.SchemaVersion` (currently 1.2.0).
`pgbot ask "why is it slow?"`.

### Added
- **`pgbot inspect --all-instances` — every Aurora writer and reader behind one
endpoint (experimental)** (#23). An Aurora cluster endpoint stands for several
instances; this discovers the members with `aurora_replica_status()`, derives
each instance endpoint from the cluster endpoint's DNS name (custom domains
are followed through their CNAME), verifies each derived endpoint reached the
member it names with `aurora_db_instance_identifier()` before collecting, and
inspects every one through the existing fan-out — writer first, then readers,
composing with `--all-databases`. SQL and DNS only: no AWS credentials, CLI,
SDK, or API. An RDS Proxy endpoint, a non-RDS name, or an unreachable member
fails loudly rather than guessing; missing members mean partial coverage and
exit 3. Text output banners each target, JSON carries `server.instance` and
`server.instance_role`, SARIF/JUnit objects are prefixed `instance:<id>/`, and
Prometheus series gain `instance` and `role` labels. Needs validation on a
real cluster — please report the cluster endpoint shape if derivation fails.
- **`$PGSERVICE` as a connection fallback** (#25). When no connection string
is passed and neither `$DATABASE_URL` nor `$PGBOT_DATABASE_URL` is set,
pgbot now checks `$PGSERVICE` too, so a
Expand All @@ -42,6 +56,10 @@ separately by `model.SchemaVersion` (currently 1.2.0).
ever go to the Mantle host for the configured region, and Bedrock requests
never follow redirects.

### Changed
- `model.ServerInfo` gains `instance` and `instance_role` (additive). JSON
contract `SchemaVersion` → **1.3.0**; a 1.2.0 consumer still parses 1.3.0
output unchanged.
### Fixed
- **Connection-string redaction now covers `?password=` in URL form.** libpq
accepts the password as a query parameter as well as in the userinfo; the
Expand Down
8 changes: 5 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
<a href="docs/providers.md">Provider notes</a>
</p>

> **Status: beta.** The `--json` contract is versioned (currently `1.2.0`, JSON
> **Status: beta.** The `--json` contract is versioned (currently `1.3.0`, JSON
> Schema published in [`schema/`](schema/)) and breaking changes to it are
> treated as breaking changes to the tool. The human-readable report is **not**
> a stable interface — parse `--json`, not the terminal output.
Expand Down Expand Up @@ -256,6 +256,7 @@ Key `inspect` flags:
| `--profile=full\|schema` | `schema` runs only catalog-derived findings — safe on an empty CI database |
| `--fail-on-new <base.json>` | act only on findings not already in a base report (migration PRs) |
| `--all-databases` | inspect every database in the cluster; cluster-wide findings reported once |
| `--all-instances` | Aurora (experimental): discover every writer and reader instance behind the cluster endpoint and inspect each; composes with `--all-databases` |
| `--config <path>` | a `.pgbot.toml` for thresholds, severity remaps, and `[[ignore]]` rules |

Exit codes are a scriptable contract: `0` clean · `1` warn · `2` critical · `3`
Expand Down Expand Up @@ -823,7 +824,7 @@ rates; the rest are point-in-time reads trended against the baseline.
## The `--json` contract

`--json` (and `--format=json`) is the interface to build on — a versioned,
PII-free document (`schema_version`, currently `1.2.0`) whose machine-checkable
PII-free document (`schema_version`, currently `1.3.0`) whose machine-checkable
JSON Schema is published in [`schema/`](schema/). Every section carries an
`exactness` label — `sampled`, `cumulative`, `scraped`, or `unavailable` — so a
consumer never mistakes a cumulative total for a live rate.
Expand Down Expand Up @@ -1094,7 +1095,8 @@ pgbot inspect "$DATABASE_URL" --format=prometheus > /var/lib/node_exporter/pgbot
mv /var/lib/node_exporter/pgbot.prom.$$ /var/lib/node_exporter/pgbot.prom # atomic
```

Under `--all-databases`, each database's series carry a `database="…"` label.
Under `--all-databases`, each database's series carry a `database="…"` label;
under `--all-instances`, `instance="…"` and `role="writer|reader"` as well.

## The findings catalogue

Expand Down
Loading