Skip to content

Commit 61ead2d

Browse files
NikolaySNikolayS
committed
Modernize README: badges, individual credits, optional extensions table, cleaner layout
1 parent 745062b commit 61ead2d

1 file changed

Lines changed: 68 additions & 44 deletions

File tree

‎README.md‎

Lines changed: 68 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,43 @@
1-
# postgres_dba
1+
# 🐘 postgres_dba
22

3-
The missing set of useful tools for Postgres DBAs.
3+
[![CI](https://github.com/NikolayS/postgres_dba/actions/workflows/test.yml/badge.svg)](https://github.com/NikolayS/postgres_dba/actions)
4+
[![PostgreSQL 13–18](https://img.shields.io/badge/PostgreSQL-13--18-336791?logo=postgresql&logoColor=white)](https://www.postgresql.org/)
5+
[![License: BSD-3](https://img.shields.io/badge/License-BSD--3-blue.svg)](LICENSE)
6+
7+
**34 diagnostic reports for PostgreSQL, right inside `psql`.** No agents, no daemons, no external dependencies — just SQL.
8+
9+
Bloat estimation, index health, lock trees, vacuum monitoring, query analysis, corruption checks, buffer cache inspection, and more. Type `:dba` and go.
410

511
![Demo](https://user-images.githubusercontent.com/1345402/74124060-dbe25c00-4b85-11ea-9538-8d3b67f09896.gif)
612

7-
## Installation
13+
## Quick Start
814

915
```bash
1016
git clone https://github.com/NikolayS/postgres_dba.git
1117
cd postgres_dba
12-
printf "%s %s %s %s\n" \\echo 🧐 🐘 'postgres_dba installed. Use ":dba" to see menu' >> ~/.psqlrc
13-
printf "%s %s %s %s\n" \\set dba \'\\\\i $(pwd)/start.psql\' >> ~/.psqlrc
18+
echo "\\set dba '\\\\i $(pwd)/start.psql'" >> ~/.psqlrc
1419
```
1520

16-
Then connect to any Postgres server via psql and type `:dba` to open the interactive menu.
21+
Connect to any Postgres server via psql and type `:dba`.
1722

18-
**Requires psql 10+.** The Postgres server itself can be older for most reports. For best results, use psql from the latest PostgreSQL release.
23+
> **Requires psql 10+.** The server can be any version. For best results, use the latest psql client.
1924
2025
## Reports
2126

22-
### General info
27+
### General (0–3)
2328
| ID | Report |
2429
|----|--------|
25-
| 0 | Node information: primary/replica, lag, database size, temp files |
30+
| 0 | Node info: primary/replica, replication lag, database size, temp files, WAL, replication slots |
2631
| 1 | Database sizes and stats |
2732
| 2 | Table and index sizes, row counts |
2833
| 3 | Load profile |
2934

30-
### Activity and locks
35+
### Activity & Locks
3136
| ID | Report |
3237
|----|--------|
33-
| a1 | Current activity: connections grouped by database, user, state |
38+
| a1 | Current connections grouped by database, user, state |
3439
| l1 | Lock trees (lightweight) |
35-
| l2 | Lock trees, detailed (on PG14+ shows wait time from `pg_locks.waitstart`) |
40+
| l2 | Lock trees with wait times (PG14+ `pg_locks.waitstart`) |
3641

3742
### Bloat
3843
| ID | Report |
@@ -41,20 +46,20 @@ Then connect to any Postgres server via psql and type `:dba` to open the interac
4146
| b2 | B-tree index bloat estimation |
4247
| b3 | Table bloat via `pgstattuple` (expensive) |
4348
| b4 | B-tree index bloat via `pgstattuple` (expensive) |
44-
| b5 | Tables and columns without stats (bloat cannot be estimated) |
49+
| b5 | Tables without stats (bloat can't be estimated) |
4550

46-
### Corruption checks
47-
| ID | Report |
48-
|----|--------|
49-
| c1 | Quick index check: btree + GIN (PG18+). Fast, safe for production (AccessShareLock) |
50-
| c2 | Indexes + heap/TOAST (PG14+). Safe for production but reads all data (AccessShareLock) |
51-
| c3 | B-tree parent check — detects glibc/collation corruption (⚠️ ShareLock — use on clones) |
52-
| c4 | Full: heapallindexed + parent + heap — proves every tuple is indexed (⚠️⚠️ slow + ShareLock — use on clones) |
51+
### Corruption Checks (`amcheck`)
52+
| ID | Lock | Report |
53+
|----|------|--------|
54+
| c1 | AccessShareLock | Quick index check: btree + GIN (PG18+). Safe for production. |
55+
| c2 | AccessShareLock | Indexes + heap/TOAST (PG14+). Safe but reads all data. |
56+
| c3 | ⚠️ ShareLock | B-tree parent check — detects glibc/collation corruption. Use on clones. |
57+
| c4 | ⚠️⚠️ ShareLock | Full: heapallindexed + parent + heap. Proves every tuple is indexed. |
5358

5459
### Memory
5560
| ID | Report |
5661
|----|--------|
57-
| m1 | Buffer cache contents (requires `pg_buffercache`, expensive) |
62+
| m1 | Buffer cache contents (`pg_buffercache`, expensive) |
5863

5964
### Indexes
6065
| ID | Report |
@@ -63,9 +68,9 @@ Then connect to any Postgres server via psql and type `:dba` to open the interac
6368
| i2 | Redundant indexes |
6469
| i3 | Foreign keys with missing indexes |
6570
| i4 | Invalid indexes |
66-
| i5 | Index cleanup migration DDL (DO & UNDO) |
71+
| i5 | Index cleanup DDL generator (DO & UNDO) |
6772

68-
### Vacuum and maintenance
73+
### Vacuum
6974
| ID | Report |
7075
|----|--------|
7176
| v1 | Vacuum: current activity |
@@ -74,56 +79,75 @@ Then connect to any Postgres server via psql and type `:dba` to open the interac
7479
### Progress
7580
| ID | Report |
7681
|----|--------|
77-
| p1 | Index creation/reindex progress |
82+
| p1 | `CREATE INDEX` / `REINDEX` progress |
7883

79-
### Statements
84+
### Statements (`pg_stat_statements`)
8085
| ID | Report |
8186
|----|--------|
82-
| s1 | Slowest queries by total time (requires `pg_stat_statements`) |
83-
| s2 | Slowest queries report (requires `pg_stat_statements`) |
84-
| s3 | Workload profile by query type (requires `pg_stat_statements`) |
87+
| s1 | Slowest queries by total time |
88+
| s2 | Full query performance report |
89+
| s3 | Workload profile by query type |
8590

86-
### Configuration and other
91+
### Tuning & Config
8792
| ID | Report |
8893
|----|--------|
8994
| t1 | Postgres parameters tuning |
9095
| t2 | Objects with custom storage parameters |
9196
| e1 | Installed extensions |
9297
| x1 | Alignment padding analysis (experimental) |
93-
| r1 | Create user with random password (interactive) |
94-
| r2 | Alter user with random password (interactive) |
98+
| r1 | Create user with random password |
99+
| r2 | Alter user with random password |
100+
101+
## Optional Extensions
102+
103+
Some reports benefit from additional extensions:
95104

96-
## PostgreSQL compatibility
105+
| Extension | Reports | Install |
106+
|-----------|---------|---------|
107+
| `pg_stat_statements` | s1, s2, s3 | `shared_preload_libraries = 'pg_stat_statements'` |
108+
| `amcheck` | c1, c2, c3, c4 | `CREATE EXTENSION amcheck;` |
109+
| `pgstattuple` | b3, b4 | `CREATE EXTENSION pgstattuple;` |
110+
| `pg_buffercache` | m1 | `CREATE EXTENSION pg_buffercache;` |
97111

98-
Tested with **PostgreSQL 13 through 18**. Older versions (9.6-12) may work but are not actively tested. Some reports require features from newer versions (noted in the report headers).
112+
## Compatibility
99113

100-
## Adding custom reports
114+
Tested on **PostgreSQL 13 through 18** via CI on every commit. Older versions (9.6–12) may work but are not actively tested.
101115

102-
Add a `.sql` file to the `sql/` directory. The filename format is `<id>_<name>.sql` (e.g., `f1_my_query.sql`). The first line must be an SQL comment (`--`) with the report description — it appears in the menu automatically.
116+
Works with the `pg_monitor` role — superuser is not required for most reports (corruption checks need superuser or explicit `GRANT EXECUTE`).
103117

104-
Then regenerate the menu:
118+
## Adding Custom Reports
119+
120+
Drop a `.sql` file in `sql/`. The filename format is `<id>_<name>.sql`. The first line must be a `--` comment with the description — it becomes the menu entry automatically.
105121

106122
```bash
123+
# Regenerate the menu after adding/removing reports
107124
bash ./init/generate.sh
108125
```
109126

110-
## Recommended: pspg pager
127+
## Recommended: pspg
111128

112-
[pspg](https://github.com/okbob/pspg) makes tabular psql output much easier to read. After installing, add to `~/.psqlrc`:
129+
[pspg](https://github.com/okbob/pspg) makes tabular output much easier to read:
113130

114-
```
131+
```sql
115132
\setenv PAGER pspg
116133
\pset border 2
117134
\pset linestyle unicode
118135
```
119136

120137
## Credits
121138

122-
Based on queries by many contributors, including:
123-
- [ioguix](https://github.com/ioguix/pgsql-bloat-estimation) (bloat estimation)
124-
- [Data Egret](https://github.com/dataegret/pg-utils) (Lesovsky, Ermakov, Boguk, Kosmodemiansky et al.)
125-
- [PostgreSQL Experts](https://github.com/pgexperts/pgx_scripts) (Berkus, Weaver et al.)
139+
Built on diagnostic queries contributed by many people over the years:
140+
141+
- **Gilles Darold** ([ioguix](https://github.com/ioguix)) — bloat estimation queries
142+
- **Alexey Lesovsky**, **Maxim Boguk**, **Ilya Kosmodemiansky**, **Andrey Ermakov** — pg-utils diagnostic suite
143+
- **Josh Berkus**, **Greg Smith**, **Christophe Pettus**, **Quinn Weaver** — pgx_scripts collection
144+
145+
## License
146+
147+
[BSD 3-Clause](LICENSE)
126148

127149
## Contact
128150

129-
Questions or ideas: nik@postgres.ai (Nikolay Samokhvalov), or [open an issue](https://github.com/NikolayS/postgres_dba/issues).
151+
[Nikolay Samokhvalov](https://github.com/NikolayS) — nik@postgres.ai
152+
153+
[Open an issue](https://github.com/NikolayS/postgres_dba/issues) for questions, ideas, or bug reports.

0 commit comments

Comments
 (0)