Give your coding agent the database context it needs to investigate a bug,
understand a schema or inspect a query plan. SafeSelect exposes read-only tools
for PostgreSQL and MongoDB, with local policy and bounded results.
Debug with database context. Discover tables, collections and indexes before
reading the rows or documents relevant to your task.
Start with connections you already have. Import from DBeaver, Docker Compose
or MongoDB Compass, including SSH-backed connections.
Keep control of access. Set project-specific access rules, row limits and
timeouts. Passwords stay in macOS Keychain or environment variables.
Run locally. The agent connects over MCP stdio, with no MCP network listener.
SafeSelect enforces its read-only tool surface even when the configured
database credentials allow writes.
[!IMPORTANT]
SafeSelect's read-only boundary covers its database tools. An agent's shell,
other MCP servers and direct credentials remain outside that boundary.
Use least-privilege database users and start with development data or a
sanitized replica. See the threat model and limits.
See it in action
From Homebrew to a connected agent: import a DBeaver connection, keep its password
in Keychain, and let OpenCode inspect an order through read-only tools.
See the demo gallery for more clients, MongoDB and Linux onboarding.
Quick Start
Run setup from your repository root. You need a PostgreSQL or MongoDB connection
and a Java 17+ runtime for database commands.
1. Install
On macOS with Homebrew:
brew install antonillos/tap/safeselect
For Linux, prebuilt binaries, asdf, Java setup or source builds, follow the
installation guide.
Use your actual export or Compass directory, then follow the importer's driver
and password setup steps. Keep secrets out of project files and chat.
For a complete SSH-backed example, follow the DBeaver → Codex walkthrough.
3. Connect your agent
# Verify connectivity; this can open SSH tunnels and contact databases.
safeselect check
# Replace codex with opencode, or choose another supported client below.
safeselect agent install codex
safeselect agent status
If you have multiple environments, add --environment <name> to both check
and agent install to select the intended database. Without it, check tests
all environments; installation only infers a target when there is exactly one.
Open or restart your agent and approve the MCP server if prompted. Installation
uses user scope by default; add --local for project scope where supported.
See client setup and scopes.
4. Try it
Ask your agent:
Use SafeSelect to identify the connected backend. For PostgreSQL, list tables
and describe one using catalog metadata. For MongoDB, list databases and
collections only. Stop before reading rows or sampling documents.
Success: the agent reports the database identity and available tables or
collections without needing a database password in the conversation.
Then ask it to investigate a specific issue with a small, targeted read.
MongoDB schema inference samples documents, so include that step only when
you are ready to read data.
Need help? Run safeselect doctor --environment <name> and follow its next
step. Diagnostics can contact the database. See the
connection diagnostics or
agent recovery guide.
SafeSelect works with MCP clients over stdio. Built-in installation handles the
clients above; the integration guide covers configuration,
scopes and manual setup. Codex and OpenCode also receive four portable workflow
skills. After updating SafeSelect, run safeselect agent upgrade <client> and
reload your client.
Security and quality evidence
SafeSelect validates requests against project policy before database execution.
Ordinary policy rejections return an error; serious security attempts and internal
validation or audit failures stop the server. Result limits and timeouts bound
reads, and query text is hashed for audit records.
The database security suites run against disposable PostgreSQL and MongoDB
fixtures. Rejection cases check the expected error and compare the resulting
database state with a baseline, so a rejected response alone is not enough to pass.
What is checked
Inspect the evidence
SQL writes, stacked statements and side-effecting functions
See how to verify a CI execution
for results tied to a specific commit. Test source describes the checks; a
successful matching run provides execution evidence. Pending or skipped suites
are unverified, and badges can refer to a different revision.
Have a setup problem or a feature request? Open an issue.
For setup feedback, include your client, OS and the step that failed; leave out
credentials, connection exports and database contents.
Report security vulnerabilities through the security policy.
Contributions are welcome—see Contributing to get started.
