Agent-first database control CLI with least-privilege execution
npm install plenumAgent-first database control CLI with least-privilege execution
Plenum is a lightweight, deterministic database control tool designed specifically for autonomous AI coding agents. It provides a constrained, safe execution surface for database operations with read-only defaults and explicit capability requirements.
> This is not a human-oriented database client. If you're looking for a tool with interactive shells, autocomplete, or pretty-printed output, Plenum is not for you.
Plenum enables AI agents to:
- Introspect database schemas safely and deterministically
- Execute read-only SQL queries with safety constraints
- Ensure strict read-only access - all write and DDL operations are rejected
- Produce machine-parseable output (JSON-only to stdout)
Plenum is exposed via a local MCP (Model Context Protocol) server, making it seamlessly integrable with AI agent frameworks.
- Agent-First Design: JSON-only output, no interactive UX, deterministic behavior
- Vendor-Specific SQL: No query abstraction layer - PostgreSQL SQL ≠ MySQL SQL ≠ SQLite SQL
- Strictly Read-Only: All write and DDL operations are rejected - guaranteed safe for AI agents
- Stateless Execution: No persistent connections, no caching, no implicit state
- Three Database Engines: PostgreSQL, MySQL, and SQLite support (first-class, equally constrained)
``bash`
git clone https://github.com/yourusername/plenum.git
cd plenum
cargo build --release
./target/release/plenum --help
- Rust 1.70 or later
- Supported platforms: Linux, macOS, Windows
Plenum provides exactly three commands:
Manage database connection configurations (interactive or non-interactive):
`bashInteractive connection picker
plenum connect
Connection configurations are stored:
- Local:
.plenum/config.json (team-shareable)
- Global: ~/.config/plenum/connections.json (per-user)$3
Inspect database schema and return structured JSON:
`bash
Introspect using named connection
plenum introspect --name prodIntrospect with explicit parameters
plenum introspect --engine postgres --host localhost --port 5432 \
--user admin --password secret --database mydbIntrospect specific schema
plenum introspect --name prod --schema public
`Returns JSON with:
- Tables
- Columns (name, type, nullable)
- Primary keys
- Foreign keys
- Indexes
$3
Execute read-only SQL queries with safety constraints:
`bash
Read-only query
plenum query --name prod --sql "SELECT * FROM users WHERE id = 1"With row limit (recommended for large tables)
plenum query --name prod --sql "SELECT * FROM large_table" \
--max-rows 100 --timeout-ms 5000Introspection queries
plenum query --name prod --sql "SHOW TABLES"
plenum query --name prod --sql "DESCRIBE users"Complex query with joins
plenum query --name prod --sql "
SELECT u.name, o.total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE o.status = 'completed'
" --max-rows 50
`Read-Only Enforcement:
- ✅ SELECT queries are permitted
- ✅ SHOW, DESCRIBE, PRAGMA statements are permitted
- ✅ EXPLAIN queries are permitted
- ❌ INSERT, UPDATE, DELETE operations are rejected
- ❌ CREATE, DROP, ALTER operations are rejected
For write operations: Plenum will reject the query with a helpful error message. Construct the SQL and present it to the user for manual execution.
Output Format
All commands output structured JSON to stdout:
Success:
`json
{
"ok": true,
"engine": "postgres",
"command": "query",
"data": { ... },
"meta": {
"execution_ms": 42,
"rows_returned": 10
}
}
`Error:
`json
{
"ok": false,
"engine": "postgres",
"command": "query",
"error": {
"code": "CAPABILITY_VIOLATION",
"message": "DDL statements require --allow-ddl flag"
}
}
`$3
Plenum returns stable, machine-parseable error codes. Agents should check the
error.code field for programmatic error handling:| Code | Description | When It Occurs |
|------|-------------|----------------|
|
CAPABILITY_VIOLATION | Operation blocked - Plenum is read-only | Attempting any write or DDL operations (INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, etc.) |
| CONNECTION_FAILED | Database connection failed | Invalid credentials, unreachable host, or database doesn't exist |
| QUERY_FAILED | Query execution failed | SQL syntax errors, missing tables/columns, constraint violations |
| INVALID_INPUT | Malformed input or missing parameters | Missing required flags, invalid engine type, etc. |
| ENGINE_ERROR | Engine-specific database error | Database-specific errors wrapped for consistency |
| CONFIG_ERROR | Configuration file or connection registry error | Missing config file, invalid JSON, connection name not found |Example error handling:
`json
{
"ok": false,
"engine": "postgres",
"command": "query",
"error": {
"code": "CAPABILITY_VIOLATION",
"message": "Plenum is read-only and cannot execute this query. Please run this query manually:\n\nINSERT INTO users (name) VALUES ('Alice')"
}
}
`Agents should:
1. Check
ok field first (true = success, false = error)
2. Match on error.code for programmatic handling
3. Use error.message for logging/debugging (agent-appropriate, no sensitive data)MCP Integration
Plenum exposes functionality via MCP (Model Context Protocol) server:
`bash
Start MCP server (hidden command, for AI agent use)
plenum mcp
`Configure in your MCP client:
`json
{
"mcpServers": {
"plenum": {
"command": "plenum",
"args": ["mcp"]
}
}
}
`Each CLI command maps to an MCP tool:
-
connect → Validate and save database connections
- introspect → Retrieve schema information
- query → Execute constrained SQL queriesArchitecture
Plenum is built around strict architectural principles:
$3
1. No query language abstraction - SQL remains vendor-specific
2. Agent-first, machine-only - No interactive UX, JSON-only output
3. Explicit over implicit - No inferred values, fail-fast on missing inputs
4. Least privilege - Read-only default, explicit capability requirements
5. Determinism - Identical inputs → identical outputs
$3
Plenum's security boundary is strict read-only enforcement, not SQL validation.
Plenum enforces:
- ✅ Strict read-only operation - all write/DDL operations are rejected
- ✅ Row limits (
max_rows) and query timeouts (timeout_ms)
- ✅ Pre-execution validation (queries validated before execution)
- ✅ Credential security (best-effort, no intentional logging)Plenum does NOT enforce:
- ❌ SQL injection prevention (agent's responsibility)
- ❌ Query semantic correctness
- ❌ Business logic constraints
- ❌ Data access policies (row-level security, column masking)
Critical: Agents must sanitize all user inputs before constructing SQL. Plenum assumes read-only SQL passed to it is safe and passes it verbatim to database drivers.
#### Credential Security
Credentials are stored as plaintext JSON in config files:
- Local:
.plenum/config.json (team-shareable)
- Global: ~/.config/plenum/connections.json (user-private)Recommendations:
- Use
password_env for production (environment variables)
- Secure config files with OS-level permissions (chmod 600)
- Avoid --password CLI flag (visible in process listings)#### Security Reporting
For detailed security documentation, threat model, and vulnerability reporting, see SECURITY.md.
To report security vulnerabilities, create a GitHub issue with the
security label.$3
Plenum uses native, engine-specific drivers (NOT sqlx):
- PostgreSQL:
tokio-postgres
- MySQL: mysql_async
- SQLite: rusqliteThis ensures maximum isolation between engines and preserves vendor-specific behavior.
Building from Source
`bash
Clone repository
git clone https://github.com/yourusername/plenum.git
cd plenumBuild
cargo build --releaseRun tests
cargo testCheck code quality
cargo fmt --check
cargo clippy --all-targets --all-featuresInstall locally
cargo install --path .
`Development
See CONTRIBUTING.md for development guidelines.
$3
`
plenum/
├── src/
│ ├── lib.rs # Library API for CLI and MCP
│ ├── main.rs # CLI entry point
│ ├── engine/ # Database engine implementations (Phase 3-5)
│ ├── capability/ # Capability validation (Phase 1.4)
│ ├── config/ # Configuration management (Phase 1.5)
│ ├── output/ # JSON output envelopes (Phase 1.2)
│ └── error/ # Error handling (Phase 1.3)
├── CLAUDE.md # Core principles and architecture
├── PROJECT_PLAN.md # Implementation roadmap
├── RESEARCH.md # Design decisions and rationale
└── PROBLEMS.md # Resolved architectural issues
``- CLAUDE.md - Core principles and non-negotiable requirements
- PROJECT_PLAN.md - Complete implementation roadmap
- SECURITY.md - Security model, threat analysis, and vulnerability reporting
- RESEARCH.md - Design decisions, rationale, and research
- PROBLEMS.md - Architectural issues and resolutions
- CONTRIBUTING.md - Development guidelines
Plenum has completed Phase 8: Security Audit.
Recent Accomplishments:
- Phase 7: MCP Server implementation complete ✅
- Phase 8: Comprehensive security audit complete ✅
- Critical security fixes applied (password masking, path panic prevention)
- SECURITY.md documentation created
See PROJECT_PLAN.md for the complete implementation roadmap:
- Phase 0: Project Foundation ✅
- Phase 1: Core Architecture ✅
- Phase 2: CLI Foundation ✅
- Phase 3: SQLite Engine ✅
- Phase 4: PostgreSQL Engine ✅
- Phase 5: MySQL Engine ✅
- Phase 6: Integration & Polish ✅
- Phase 7: MCP Server ✅
- Phase 8: Security Audit ✅
- Phase 9: Release Preparation ← Next Phase
Contributions must adhere to Plenum's core principles. Before adding code, ask:
> "Does this make autonomous agents safer, more deterministic, or more constrained?"
If the answer is no, it does not belong in Plenum.
See CONTRIBUTING.md for detailed guidelines.
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Plenum follows the architecture pattern established by reflex-search for MCP integration.