Skip to content

Commit 5005e81

Browse files
tianzhouclaude
tianzhou
and
claude
committed
chore: expand README with feature details, screenshots, and quickstart link
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent a4554a8 commit 5005e81

File tree

1 file changed

+150
-9
lines changed

1 file changed

+150
-9
lines changed

‎README.md‎

Lines changed: 150 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,19 +14,20 @@
1414
<img src="https://raw.githubusercontent.com/pgplex/pgconsole/main/website/public/sql-editor-overview.webp" alt="pgconsole SQL editor" />
1515
</td></tr></table>
1616

17-
**pgconsole** is web-based PostgreSQL editor. Single binary, single config file, no database required. Connect your team to PostgreSQL with access control and audit logging built in.
17+
**pgconsole** is a web-based PostgreSQL editor. Single binary, single config file, no database required. Connect your team to PostgreSQL with access control and audit logging built in.
1818

19-
## Features
20-
21-
- Full PostgreSQL parser powers realtime autocomplete, syntax highlighting, and error detection
22-
- Query, edit results, stage changes, and apply — all in one view
23-
- AI assistant generates SQL, explains queries, fixes errors, and assesses change risk
24-
- Fine-grained IAM controls who can read, write, or administer each connection
25-
- Every query and login is recorded in the audit log
26-
- Everything is in `pgconsole.toml` — connections, users, groups, access rules, AI providers
19+
<a href="https://www.star-history.com/#pgplex/pgconsole&Date">
20+
<picture>
21+
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=pgplex/pgconsole&type=Date&theme=dark" />
22+
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=pgplex/pgconsole&type=Date" />
23+
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=pgplex/pgconsole&type=Date" />
24+
</picture>
25+
</a>
2726

2827
## Installation
2928

29+
Visit https://docs.pgconsole.com/getting-started/quickstart
30+
3031
### Prerequisites
3132

3233
- Node.js 20+
@@ -49,3 +50,143 @@ npx @pgplex/pgconsole --config pgconsole.toml
4950
```bash
5051
docker run -p 9876:9876 -v /path/to/pgconsole.toml:/etc/pgconsole.toml pgplex/pgconsole
5152
```
53+
54+
Run without `--config` to start in demo mode with a bundled sample database.
55+
56+
## Features
57+
58+
### SQL Editor
59+
60+
A full-featured SQL workspace with real-time intelligence powered by a PostgreSQL parser — not regex.
61+
62+
- **Autocomplete** — context-aware suggestions for tables, columns, joins, and CTEs
63+
- **Formatting** — pretty-print or collapse SQL to one line
64+
- **Error detection** — red underlines with hover tooltips
65+
- **Code folding** — collapse `SELECT`, `WITH`, and other blocks
66+
- **Function signature help** — parameter hints as you type
67+
68+
<table><tr><td>
69+
<img src="https://raw.githubusercontent.com/pgplex/pgconsole/main/docs/images/features/sql-editor/sql-editor-autocomplete.webp" alt="Autocomplete" />
70+
</td></tr></table>
71+
72+
### Data Grid & Inline Editing
73+
74+
Query results appear in a virtual-scrolling grid. With `write` permission, you can edit data directly — all changes are staged locally and previewed before execution.
75+
76+
- Double-click a cell to edit, or use the row detail panel
77+
- Add, delete, and duplicate rows
78+
- Staged changes are color-coded: green (INSERT), amber (UPDATE), red (DELETE)
79+
- Preview generated SQL and optionally run an AI risk assessment before executing
80+
81+
<table><tr><td>
82+
<img src="https://raw.githubusercontent.com/pgplex/pgconsole/main/docs/images/features/sql-editor/sql-editor-staged-changes.webp" alt="Staged changes preview" />
83+
</td></tr></table>
84+
85+
### Schema Browser
86+
87+
Browse and inspect database objects — tables, views, materialized views, functions, and procedures — with full metadata, indexes, constraints, triggers, and grants.
88+
89+
<table><tr><td>
90+
<img src="https://raw.githubusercontent.com/pgplex/pgconsole/main/docs/images/features/sql-editor/sql-editor-schema-tab.webp" alt="Schema browser" />
91+
</td></tr></table>
92+
93+
### AI Assistant
94+
95+
Generate, explain, fix, and rewrite SQL with an AI assistant that understands your schema context. Supports OpenAI, Anthropic, and Google providers.
96+
97+
- **Text-to-SQL** — describe a query in natural language, get SQL back
98+
- **Explain SQL** — get plain-language explanations of any query
99+
- **Fix SQL** — AI-powered error correction from inline linting
100+
- **Rewrite SQL** — optimize queries for performance or readability
101+
- **Risk assessment** — analyze staged changes for potential risks before execution
102+
103+
<table><tr><td>
104+
<img src="https://raw.githubusercontent.com/pgplex/pgconsole/main/docs/images/features/ai-assistant/ai-text-to-sql.webp" alt="AI Text-to-SQL" />
105+
</td></tr></table>
106+
107+
<table><tr><td>
108+
<img src="https://raw.githubusercontent.com/pgplex/pgconsole/main/docs/images/features/ai-assistant/ai-risk-assessment.webp" alt="AI risk assessment" />
109+
</td></tr></table>
110+
111+
### Database Access Control
112+
113+
Fine-grained IAM controls who can read, write, or administer each connection. Permissions are enforced at the application layer — no database roles needed.
114+
115+
- **Default deny** — users have no access unless a rule explicitly grants it
116+
- **Connection-scoped** — permissions are granted per connection, not globally
117+
- **Disjoint permissions** — `read`, `write`, `ddl`, `admin`, `explain`, `execute`, `export` are independent
118+
119+
<table><tr><td>
120+
<img src="https://raw.githubusercontent.com/pgplex/pgconsole/main/docs/images/features/database-access-control/iam-permission-denied.webp" alt="Permission denied" />
121+
</td></tr></table>
122+
123+
<table><tr><td>
124+
<img src="https://raw.githubusercontent.com/pgplex/pgconsole/main/docs/images/features/database-access-control/iam-permission-badge.webp" alt="Permission badge" />
125+
</td></tr></table>
126+
127+
### Audit Log
128+
129+
Every query and login is recorded as structured JSON to stdout. Filter and forward to your log infrastructure.
130+
131+
```json
132+
{
133+
"type": "audit",
134+
"ts": "2024-01-15T10:32:15.456Z",
135+
"action": "sql.execute",
136+
"actor": "alice@example.com",
137+
"connection": "prod-db",
138+
"sql": "SELECT * FROM users WHERE active = true",
139+
"duration_ms": 45,
140+
"row_count": 150
141+
}
142+
```
143+
144+
### Single-File Configuration
145+
146+
Everything lives in `pgconsole.toml` — connections, users, groups, access rules, AI providers. No database required.
147+
148+
```toml
149+
[[connections]]
150+
id = "production"
151+
name = "Production"
152+
host = "db.example.com"
153+
port = 5432
154+
database = "myapp"
155+
username = "readonly"
156+
password = "..."
157+
158+
[[iam]]
159+
connection = "production"
160+
permissions = ["read", "explain", "export"]
161+
members = ["*"]
162+
163+
[[iam]]
164+
connection = "production"
165+
permissions = ["*"]
166+
members = ["group:dba"]
167+
168+
[[ai.providers]]
169+
id = "claude"
170+
vendor = "anthropic"
171+
model = "claude-sonnet-4-20250514"
172+
api_key = "sk-ant-..."
173+
```
174+
175+
## Getting Help
176+
177+
- [Docs](https://www.pgconsole.com)
178+
- [GitHub Issues](https://github.com/pgplex/pgconsole/issues)
179+
180+
## Development
181+
182+
> [!NOTE]
183+
> **For external contributors**: If you want to request a feature, please create a GitHub issue to discuss first instead of creating a PR directly.
184+
185+
```bash
186+
git clone https://github.com/pgplex/pgconsole.git
187+
cd pgconsole
188+
pnpm install
189+
pnpm dev # Start dev server (frontend + backend)
190+
pnpm build # Production build
191+
pnpm test # Run all tests
192+
```

0 commit comments

Comments
 (0)