Plenum

Agent-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.

What is Plenum?

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.

Key Features

Agent-First Design: JSON-only output, no interactive UX, deterministic behavior
Vendor-Specific SQL: No query abstraction layer - PostgreSQL SQL ≠ MySQL SQL ≠ SQLite SQL ≠ DuckDB 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
Four Database Engines: PostgreSQL, MySQL, SQLite, and DuckDB support (first-class, equally constrained)

Installation

From Source

git clone https://github.com/yourusername/plenum.git
cd plenum
cargo build --release
./target/release/plenum --help

System Requirements

Rust 1.70 or later
Supported platforms: Linux, macOS, Windows

Zero to Query

Two paths from nothing to a working query result.

Path A — CLI-first (recommended for most setups)

1. Save a connection:

# Save a PostgreSQL connection to the current project (password via env var — never plaintext)
plenum connect --name dev --engine postgres \
  --host localhost --port 5432 --user myuser \
  --password-env PGPASSWORD --database mydb --save local

2. Query immediately:

plenum query --sql "SELECT COUNT(*) FROM users"
# => {"ok":true,"engine":"postgres","command":"query","data":{"rows":[{"count":42}]},"meta":{...}}

Plenum resolves the dev connection automatically from .plenum/config.json because it is the default for this project directory.

Path B — MCP-first (for AI coding agents via Claude Desktop or editors)

Register Plenum in your MCP client config with the project path bound at registration time. You must supply --project-path — see the cwd-Coupling Warning below.

Option 1 — use a saved named connection:

{
  "mcpServers": {
    "plenum": {
      "command": "plenum",
      "args": ["mcp", "--project-path", "/abs/path/to/your/project", "--name", "dev"]
    }
  }
}

Run plenum connect first (Path A) to save the connection, then add the stanza above.

Option 2 — use a DSN from a named env var (no saved config needed):

{
  "mcpServers": {
    "plenum": {
      "command": "plenum",
      "args": ["mcp", "--dsn-env", "DATABASE_URL"]
    }
  }
}

DATABASE_URL is read at connection time from that env var only. No ambient credential scanning.

Once the MCP server is running the agent can call the query tool without any further setup.

Usage

Plenum provides exactly three commands:

1. `plenum connect` - Configure Database Connections

Manage database connection configurations (interactive or non-interactive).

Flags

Flag	Default	Description
`--list`	—	List saved connections for the project as JSON (no secrets emitted)
`--name <NAME>`	`"default"`	Connection name
`--project-path <PATH>`	current directory	Project path for connection lookup
`--engine <ENGINE>`	—	Database engine: `postgres`, `mysql`, `sqlite`, or `duckdb`
`--host <HOST>`	—	Hostname (postgres/mysql)
`--port <PORT>`	—	Port (postgres/mysql)
`--user <USER>`	—	Username (postgres/mysql)
`--password <PASSWORD>`	—	Password (postgres/mysql; visible in process list — prefer `--password-env`)
`--password-env <VAR>`	—	Name of an environment variable whose value is the password
`--password-command <CMD>`	—	Shell command (`sh -c`) whose stdout is used as the password at connection time
`--keychain-service <SVC>`	—	OS keychain service name (pair with `--keychain-account`)
`--keychain-account <ACCT>`	—	OS keychain account name (pair with `--keychain-service`)
`--database <DATABASE>`	—	Database name (postgres/mysql)
`--file <FILE>`	—	SQLite/DuckDB file path
`--save <LOCATION>`	—	Save location: `local` (`.plenum/config.json`) or `global` (`~/.config/plenum/connections.json`)
`--ssl-mode <MODE>`	—	TLS/SSL mode: `disable`, `require`, `verify-ca`, or `verify-full` (postgres/mysql)
`--ssl-ca <PATH>`	—	PEM CA certificate for TLS verification (required for `verify-ca`/`verify-full`)
`--ssl-cert <PATH>`	—	PEM client certificate for mTLS (must be paired with `--ssl-key`)
`--ssl-key <PATH>`	—	PEM client private key for mTLS (must be paired with `--ssl-cert`)
`--test`	—	Test connection liveness and return server metadata without saving config

Examples

# List saved connections for the current project
plenum connect --list

# Save a PostgreSQL connection globally (password via env var — recommended)
plenum connect --name prod --engine postgres --host db.example.com \
  --port 5432 --user readonly --password-env DB_PASSWORD \
  --database myapp --save global

# Save a PostgreSQL connection with full TLS verification
plenum connect --name prod-tls --engine postgres --host db.example.com \
  --user readonly --password-env DB_PASSWORD --database myapp \
  --ssl-mode verify-full --ssl-ca /etc/ssl/certs/ca.pem --save global

# Save a connection using OS keychain for the password
plenum connect --name staging --engine mysql --host staging.db.internal \
  --user agent --keychain-service MyApp --keychain-account db-staging \
  --database app --save local

# Save a connection using a shell command to retrieve the password (e.g. 1Password CLI)
plenum connect --name vault --engine postgres --host localhost \
  --user app --password-command "op read op://vault/db/password" \
  --database mydb --save global

# Save a SQLite connection
plenum connect --name dev --engine sqlite --file ./dev.db --save local

# Save a DuckDB connection
plenum connect --name analytics --engine duckdb --file ./analytics.duckdb --save local

# Test a connection without saving
plenum connect --engine postgres --host localhost --user dev \
  --password-env DEV_DB_PASSWORD --database mydb --test

Connection configurations are stored:

Local: .plenum/config.json (team-shareable, per-project)
Global: ~/.config/plenum/connections.json (per-user)

These files use different schemas:

Local (.plenum/config.json) — flat ProjectConfig, already scoped to this directory:

{
  "connections": {
    "local": { "engine": "sqlite", "file": "./app.db" },
    "prod":  { "engine": "postgres", "host": "db.example.com", "port": 5432,
               "user": "readonly", "database": "myapp", "password_env": "PROD_DB_PASSWORD" }
  },
  "default": "local"
}

Global (~/.config/plenum/connections.json) — ConnectionRegistry, projects keyed by absolute path:

{
  "projects": {
    "/home/user/myapp": {
      "connections": {
        "local": { "engine": "sqlite", "file": "./app.db" },
        "prod":  { "engine": "postgres", "host": "db.example.com", "port": 5432,
                   "user": "readonly", "database": "myapp", "password_env": "PROD_DB_PASSWORD" }
      },
      "default": "local"
    }
  }
}

The first connection created for a project is automatically set as the default. Run plenum connect --list to see the current registry.

2. `plenum introspect` - Schema Introspection

Inspect database schema and return structured JSON.

Connection flags

Flag	Default	Description
`--dsn <DSN>`	—	One-off connection URL (mutually exclusive with `--name` and explicit flags). Accepted schemes: `postgres://`, `postgresql://`, `mysql://`, `sqlite:`, `duckdb:`
`--name <NAME>`	`"default"`	Named connection from the saved registry
`--project-path <PATH>`	current directory	Project path for connection lookup
`--engine <ENGINE>`	—	Engine override: `postgres`, `mysql`, `sqlite`, or `duckdb`
`--host <HOST>`	—	Host override
`--port <PORT>`	—	Port override
`--user <USER>`	—	Username override
`--password <PASSWORD>`	—	Password override
`--database <DATABASE>`	—	Database override
`--file <FILE>`	—	SQLite/DuckDB file override
`--ssl-mode <MODE>`	—	TLS/SSL mode: `disable`, `require`, `verify-ca`, or `verify-full` (postgres/mysql)
`--ssl-ca <PATH>`	—	PEM CA certificate (required for `verify-ca`/`verify-full`)
`--ssl-cert <PATH>`	—	PEM client certificate for mTLS (pair with `--ssl-key`)
`--ssl-key <PATH>`	—	PEM client private key for mTLS (pair with `--ssl-cert`)

Operation flags

Flag	Default	Description
`--list-databases`	—	List all databases (requires a wildcard/no-database connection)
`--list-schemas`	—	List all schemas (PostgreSQL/DuckDB)
`--list-tables`	—	List all table names
`--list-views`	—	List all view names
`--list-indexes [TABLE]`	—	List all indexes, optionally filtered to a single table
`--table <TABLE>`	—	Return full details for a specific table
`--view <VIEW>`	—	Return details for a specific view
`--target-database <DB>`	—	Switch to a different database before introspecting
`--schema <SCHEMA>`	—	Filter results to a specific schema (PostgreSQL/MySQL/DuckDB)
`--diff-against <NAME>`	—	Structural schema diff against another named connection. Mutually exclusive with all other operation flags. Returns tables/views added, removed, and changed (columns, indexes, foreign keys, primary keys)
`--diff-against-project-path <PATH>`	current project	Project path for the `--diff-against` connection (for cross-project comparison)

Detail flags (apply when using `--table`)

Flag	Default	Description
`--columns <true\|false>`	`true`	Include column details
`--primary-key <true\|false>`	`true`	Include primary key details
`--foreign-keys <true\|false>`	`true`	Include foreign key details
`--indexes <true\|false>`	`true`	Include index details

Examples

# Full schema introspection using the default saved connection
plenum introspect --name prod

# One-off introspection via DSN (no saved config needed)
plenum introspect --dsn "postgres://user:pass@localhost/mydb"

# List all databases on a server
plenum introspect --name dev --list-databases

# List all schemas (PostgreSQL)
plenum introspect --name prod --list-schemas

# List tables in a specific schema
plenum introspect --name prod --list-tables --schema public

# List views
plenum introspect --name prod --list-views

# List indexes for a specific table
plenum introspect --name prod --list-indexes users

# Get full details for a table (columns, PKs, FKs, indexes)
plenum introspect --name prod --table users

# Get table details without indexes
plenum introspect --name prod --table users --indexes false

# Get details for a view
plenum introspect --name prod --view active_users

# Diff current schema against a saved baseline (useful in CI)
plenum introspect --name prod --diff-against baseline

# Cross-project schema diff
plenum introspect --name prod \
  --diff-against staging \
  --diff-against-project-path /other/project

3. `plenum query` - Read-Only Query Execution

Execute read-only SQL queries with safety constraints:

# 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 5000

# Introspection 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:

{
  "ok": true,
  "engine": "postgres",
  "command": "query",
  "data": { ... },
  "meta": {
    "execution_ms": 42,
    "rows_returned": 10
  }
}

Error:

{
  "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\nCREATE TABLE users (id INT)"
  }
}

JSON Schemas

Machine-consumable JSON Schema (Draft 7) files for every output envelope are checked into schemas/:

File	Validates
`schemas/error_envelope.json`	All error responses
`schemas/connect_success.json`	`plenum connect` success response
`schemas/introspect_success.json`	`plenum introspect` success response
`schemas/query_success.json`	`plenum query` success response

All schemas include meta.contract_version — agents should check this field to guard against silent breaking changes.

Schemas are generated directly from the Rust types via schemars. To regenerate after a type change:

cargo run --bin generate-schemas

A drift test (tests/schema_drift.rs) fails CI if checked-in schemas diverge from the live types.

Error Codes

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:

{
  "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:

Check ok field first (true = success, false = error)
Match on error.code for programmatic handling
Use error.message for logging/debugging (agent-appropriate, no sensitive data)

MCP Integration

Plenum exposes all three CLI commands as MCP tools via a local MCP server. The server is started with plenum mcp and connection binding is controlled at registration time:

plenum mcp --project-path /abs/path/to/project          # pin to a project (recommended)
plenum mcp --project-path /abs/path/to/project --name prod  # pin to a named connection
plenum mcp --dsn-env DATABASE_URL                        # read DSN from a named env var

cwd-Coupling Warning

When plenum mcp is started without --project-path or --dsn-env, connection resolution falls back to the server process's working directory. MCP clients (Claude Desktop, editors, daemons) launch plenum mcp from arbitrary directories — often not your project root. The result is a failed resolution, not a wrong connection: the tool call fails with a structured error that names the missing flag to add.

Always supply --project-path or --dsn-env in your mcpServers stanza.

mcpServers configuration

{
  "mcpServers": {
    "plenum": {
      "command": "plenum",
      "args": ["mcp", "--project-path", "/abs/path/to/your/project", "--name", "dev"]
    }
  }
}

MCP tools

Each CLI command maps to one MCP tool. Tool-call arguments mirror the CLI flags and take precedence over the binding set at server start.

`connect` tool

Validates and persists a database connection by credential reference. Inline plaintext passwords and password_command are rejected with CAPABILITY_VIOLATION at the MCP boundary — never pass raw secrets through tool arguments.

Field	Description
`engine`	`postgres`, `mysql`, `sqlite`, or `duckdb`
`host`, `port`, `user`, `database`	Server coordinates (postgres/mysql)
`file`	File path (sqlite/duckdb)
`password_env`	Name of env var holding the password
`keychain_service` + `keychain_account`	OS keychain lookup pair (both required together)
`save`	`"local"` (`.plenum/config.json`) or `"global"` (`~/.config/plenum/connections.json`)
`project_path`	Absolute path of the project to save the connection under
`name`	Connection name (defaults to `"default"`)

At most one credential-reference source (password_env or the keychain pair) may be supplied per call.

password_command is rejected on every MCP tool because it executes a shell command. Accepting it from tool arguments would let an agent run arbitrary commands on the host. Use --password-command from the CLI (plenum connect) instead — a human types it there.

`introspect` tool

Retrieves schema information. Accepts the same credential-reference fields (password_env, keychain_service/keychain_account) for one-off explicit connections — secrets are resolved at connect time and never appear in tool arguments or logs.

`query` tool

Executes a constrained, read-only SQL query. Accepts the same credential-reference fields as introspect.

Architecture

Plenum is built around strict architectural principles:

Core Principles

The five core invariants governing all design decisions are defined in CLAUDE.md.

Security Model

Plenum's security boundary is strict read-only enforcement, not SQL validation. For the full security model — what Plenum enforces, agent responsibilities, and what falls outside Plenum's scope — see CLAUDE.md.

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)

Credential Sourcing Safety Rules

Plenum's credential sourcing is deterministic and reference-based. These rules hold unconditionally:

Explicit reference only — The MCP connect tool rejects inline plaintext passwords with CAPABILITY_VIOLATION. Credentials flow through Plenum only as named references (password_env, keychain_service/keychain_account). MCP tools reject password_command because it executes a shell command; it is available only from the CLI. The CLI --password flag is available but strongly discouraged (visible in process listings and shell history).
No ambient pickup — --dsn-env reads exactly the one env var you name. Plenum never scans DATABASE_URL, PGPASSWORD, or any other ambient variable on its own.
No scanning — Plenum reads only the two fixed config file paths (.plenum/config.json and ~/.config/plenum/connections.json). No directory walking, no inference from arbitrary paths.
Deterministic resolution — Given the same --project-path, --name, and env vars, the same connection is always resolved. The precedence order is: explicit CLI flags → local config → global config → structured error.

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.

Database Drivers

Plenum uses native, engine-specific drivers (NOT sqlx):

PostgreSQL: tokio-postgres
MySQL: mysql_async
SQLite: rusqlite
DuckDB: duckdb

This ensures maximum isolation between engines and preserves vendor-specific behavior.

Building from Source

# Clone repository
git clone https://github.com/yourusername/plenum.git
cd plenum

# Build
cargo build --release

# Run tests
cargo test

# Check code quality
cargo fmt --check
cargo clippy --all-targets --all-features

# Install locally
cargo install --path .

Development

See CONTRIBUTING.md for development guidelines.

Project Structure

plenum/
├── src/
│   ├── lib.rs           # Library API for CLI and MCP
│   ├── main.rs          # CLI entry point
│   ├── bin/
│   │   └── generate_schemas.rs  # Schema generation binary
│   ├── engine/          # Database engine implementations
│   ├── capability/      # Capability validation
│   ├── config/          # Configuration management
│   ├── output/          # JSON output envelopes
│   └── error/           # Error handling
├── schemas/             # JSON Schema files (generated, checked in)
│   ├── error_envelope.json
│   ├── connect_success.json
│   ├── introspect_success.json
│   └── query_success.json
├── tests/
│   ├── schema_drift.rs  # Fails if schemas diverge from types
│   └── ...
├── CLAUDE.md            # Canonical agent rules, invariants, and non-negotiable requirements
├── PROJECT_PLAN.md      # Implementation roadmap
├── RESEARCH.md          # Design decisions and rationale
└── PROBLEMS.md          # Resolved architectural issues

Documentation

CLAUDE.md - Canonical agent rules, core invariants, and non-negotiable requirements
ARCHITECTURE.md - Internal design, module structure, data flow, and design rationale
CONTRIBUTING.md - Development guidelines
SECURITY.md - Security model, threat analysis, and vulnerability reporting
PROJECT_PLAN.md - Complete implementation roadmap
RESEARCH.md - Design decisions, rationale, and research
PROBLEMS.md - Architectural issues and resolutions

Roadmap

Plenum has completed Phase 8: Security Audit and is actively progressing through Phase 9: Release Preparation.

Completed phases:

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 — In Progress

Key deliverables shipped in this phase:

Area	Status	Details
Live test infrastructure	✅ Done	Docker Compose harness, vendor seeds, `test-live.sh`; MySQL 8.0/8.4 and PostgreSQL 16 matrices (REF-275, REF-276, REF-277, REF-278, REF-279)
Output schema versioning	✅ Done	JSON Schemas (Draft 7) for all envelopes; schema-drift CI gate (REF-265)
Introspect enhancements	✅ Done	Column comments, row estimates, `--diff-against` schema diff (REF-263, REF-281)
Connection improvements	✅ Done	`--dsn`, `--list`, `--test`, `password_command`, `keychain_entry` (REF-267–REF-272)
Query safety	✅ Done	`max_bytes` byte-budget guard, session-level driver read-only enforcement (REF-261, REF-269)
Security hardening	✅ Done	CTE DML bypass rejection, SQLite PRAGMA allowlist tightened (REF-41, REF-44)
Versioned release	⏳ Pending	crates.io and npm publish

See PROJECT_PLAN.md for the full implementation roadmap and CHANGELOG.md for a categorized history of all changes.

Contributing

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.

License

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.

Acknowledgements

Plenum follows the architecture pattern established by reflex-search for MCP integration.

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.github/workflows		.github/workflows
.plenum		.plenum
benches		benches
examples		examples
schemas		schemas
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.toml		Cargo.toml
EXAMPLES.md		EXAMPLES.md
LICENSE		LICENSE
Makefile		Makefile
PROBLEMS.md		PROBLEMS.md
PROJECT_PLAN.md		PROJECT_PLAN.md
README.md		README.md
RELEASE.md		RELEASE.md
RESEARCH.md		RESEARCH.md
SECURITY.md		SECURITY.md
dist-workspace.toml		dist-workspace.toml
rust-toolchain.toml		rust-toolchain.toml
rustfmt.toml		rustfmt.toml

Latest commit

History

Folders and files

Repository files navigation

Plenum

What is Plenum?

Key Features

Installation

From Source

System Requirements

Zero to Query

Path A — CLI-first (recommended for most setups)

Path B — MCP-first (for AI coding agents via Claude Desktop or editors)

Usage

1. plenum connect - Configure Database Connections

Flags

Examples

2. plenum introspect - Schema Introspection

Connection flags

Operation flags

Detail flags (apply when using --table)

Examples

3. plenum query - Read-Only Query Execution

Output Format

JSON Schemas

Error Codes

MCP Integration

cwd-Coupling Warning

mcpServers configuration

MCP tools

connect tool

introspect tool

query tool

Architecture

Core Principles

Security Model

Credential Security

Credential Sourcing Safety Rules

Security Reporting

Database Drivers

Building from Source

Development

Project Structure

Documentation

Roadmap

Contributing

License

Acknowledgements

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

1. `plenum connect` - Configure Database Connections

2. `plenum introspect` - Schema Introspection

Detail flags (apply when using `--table`)

3. `plenum query` - Read-Only Query Execution

`connect` tool

`introspect` tool

`query` tool