codeDB Lens
OfficialSummarize: codeDB Lens is a read-only MCP server that lets an AI client run database health checks, inspect reports and rule evidence, explore schemas, and query SQL Server/PostgreSQL instances safely.
Health checks: Run the Lens check on a saved profile and get an A–F grade, coverage, findings with severity/confidence/evidence preview and next actions, plus rules lacking data; optionally
--redactidentifiers and query text.Run comparison & history: List saved runs and compare two runs for new, resolved, persisting and changed findings and grade movement.
Finding drill-down: Fetch full detail and all evidence rows for one rule in a saved run.
Rule catalog: List rules by engine and explain a rule's purpose, impact, next action, verification steps, required permission, SQL and docs.
Schema exploration: List profiles (no secrets), list databases, list tables/views, and describe a table's columns, keys, indexes and row estimates.
Read-only querying: Execute a single SELECT/WITH statement with row, cell and timeout limits; writes, EXEC and multiple statements are refused.
Recordings: List recordings, produce the terminal command to record activity (1h, or 24h with a free key), and analyze a recording for gaps, episodes, chart peaks and top queries while writing an HTML report.
Connects read-only to PostgreSQL instances (15–18, plus managed offerings) to run an evidence-based health-check rule catalog, producing an A–F graded report with findings, coverage and next actions. Also lists and describes tables and answers questions with a single read-only SELECT at a time, within row and time limits.
v0.8:
check(with an executive summary and--redactfor sharing),compare, andrecord+reportto watch an instance for up to 24 hours (how). 26 rules plus 8 for recordings. FAQ and more on the website.
codeDB Lens connects to your instance with a read-only login, runs a catalog of evidence-based rules and writes a self-contained HTML + JSON report with an A–F grade and a coverage seal (the share of rules that could actually run). Nothing about your database leaves your machine.
Install
Where | How |
Windows | |
Windows (Scoop) |
|
Linux |
|
Docker |
|
The Windows binaries are open source but not code-signed yet, so SmartScreen may show a warning. Why, and how to verify the download.
Related MCP server: mcp-database
Why another tool?
Evidence, not opinions. Every finding shows the collected values, the query that produced them and when.
Honest confidence. Each finding is Confirmed, Hint or No data. A rule that lacks permission never shows up as a false "OK"; it lowers the coverage instead.
Read-only, always. No DDL, no DML, no agent, no installation on the server.
Rules are data. Each rule is a YAML file plus a SQL query. Contributions don't touch the engine.
English and Portuguese (Brazil), in the app, the CLI and the report.
What it checks
SQL Server | PostgreSQL |
Missing or old backups | Version out of support |
No recent clean DBCC CHECKDB | pg_stat_statements not available |
Failing SQL Agent jobs | A single query dominating execution time |
Disk or transaction log running out of space | Long and idle-in-transaction sessions |
Dominant waits, translated | Sessions blocked by locks |
Sessions blocked right now | Transaction ID wraparound risk |
A single query dominating CPU | Dead rows and autovacuum falling behind |
Instance settings left at defaults | Replication slots retaining WAL, replica lag |
TempDB file layout | Connections near the limit, no pooler |
Version out of support | Unused, duplicate and invalid indexes |
High-impact missing indexes | Estimated table bloat |
Unused and duplicate indexes | Largest tables |
Each rule has a documentation page with what it checks, why it matters, what to do and its limits.
Quick start
On Windows, open codeDB Lens from the Start menu. Pick the engine, enter the server and run the diagnosis. Connection profiles are saved; passwords go to the Windows Credential Manager.
Command line (Windows and Linux):
codedb-lens check --engine mssql --server prod01 --auth windows
codedb-lens check --engine pg --dsn-env PG_DSNPasswords are never accepted as command-line arguments. Use integrated auth, an environment variable or a saved profile.
Use with AI (MCP)
Ask Claude, GitHub Copilot or Cursor about your database. codedb-lens mcp is a read-only MCP server that your AI
client starts on your computer, with your saved profiles:
Diagnosis: with the Lens's minimal login, the AI runs the health check, reads recordings and explains what to fix, without reading business data.
Data: with a login that reads the tables you choose, the AI lists and describes them and answers questions with one
SELECTat a time, within row and time limits.
codedb-lens mcp install --client claude-desktop --profile prod # or vscode, cursor, claude-codeThe app's AI (MCP) screen has the commands ready to copy. Guide: lens.codedb.com.br/mcp.
Minimum permissions
-- SQL Server
CREATE LOGIN codedb_lens WITH PASSWORD = '<strong password>';
GRANT VIEW SERVER STATE TO codedb_lens;
GRANT VIEW ANY DEFINITION TO codedb_lens;
GRANT CONNECT ANY DATABASE TO codedb_lens; -- per-database rules (indexes); no data access
USE msdb;
CREATE USER codedb_lens FOR LOGIN codedb_lens;
ALTER ROLE db_datareader ADD MEMBER codedb_lens;
ALTER ROLE SQLAgentReaderRole ADD MEMBER codedb_lens;-- PostgreSQL (repeat GRANT CONNECT for each database)
CREATE ROLE codedb_lens LOGIN PASSWORD '<strong password>';
GRANT pg_monitor TO codedb_lens;
GRANT CONNECT ON DATABASE app TO codedb_lens;Supported versions
Engine | Supported | Best-effort |
SQL Server | 2017, 2019, 2022, 2025 (Windows and Linux), Azure SQL Managed Instance, Amazon RDS | 2016 and older; Azure SQL Database (6 of 13 rules apply, see permissions) |
PostgreSQL | 15, 16, 17, 18, Amazon RDS, Aurora, Azure Flexible Server | 14 |
Privacy
No telemetry. Lens makes two kinds of network calls: an optional, once-a-day version check against GitHub Releases
that sends no data (--no-update-check or CODEDB_LENS_NO_UPDATE=1 turns it off), and, only when you ask for the free
key, one registration request with the name and e-mail you type (or, when renewing, only the current key). See SECURITY.md.
Need continuous monitoring?
Lens shows a snapshot. codeDB watches your SQL Server and PostgreSQL instances around the clock, with history, baselines and alerts on Teams, Slack and e-mail.
Windows code signing
Windows binaries are built by GitHub Actions from this repository and are not code-signed yet (certificates are paid and this is a free project). Details, how to verify a download and warning-free alternatives: Why Windows shows a warning.
Contributing
New rules are especially welcome. A rule is a YAML file plus a SQL query, so you don't need to touch the Go code: see CONTRIBUTING.md, or just open an issue with a rule idea.
License
Apache 2.0. The codeDB SaaS and its API are separate, closed-source products.
Available Tools
14 toolscheckBRead-only
Run the codeDB Lens health check on a profile (read-only, 10-60 s): A-F grade with its coverage, findings with severity, confidence, evidence preview and next action, and rules without data. Saves the report in the profile's history, like the app does.
Inputs: profile (required), redact. Returns: note, grade, score, passed, +5 more
compareARead-only
Compare two runs of the same instance: new, resolved and persisting findings and the grade change. Default: the two latest runs. Needs the user's free key (codedb-lens register).
Inputs: profile (required), a, b. Returns: new, after, before, report, +4 more
describe_tableARead-only
Columns (type, nullable, default), primary key, foreign keys with the referenced table, indexes and estimated rows of one table or view. Use it before writing a query, so column names are right.
Inputs: table (required), profile (required), database. Returns: name, type, schema, columns, +4 more
explain_ruleARead-only
Explain one rule: what it measures, why it matters, the next action, how to verify the fix, the permission it needs, its SQL and its documentation link.
Inputs: rule_id (required). Returns: id, sql, kind, title, +9 more
get_findingARead-only
Full detail of one rule in a saved run: status, impact, next action, how to verify the fix, and all evidence rows. Default run: the latest.
Inputs: profile (required), rule_id (required), run. Returns: id, run, rows, title, +13 more
historyARead-only
Saved check runs of a profile, newest first: date, grade, coverage and number of findings. Each run's path can be passed to get_finding or compare.
Inputs: profile (required), limit. Returns: runs
list_databasesARead-only
Databases this profile's login can open: name, state, recovery model or encoding, collation and size in bytes.
Inputs: profile (required). Returns: note, rows, columns, truncated
list_profilesARead-only
List the saved connection profiles you may use: name, engine, host, initial database and language. Never returns passwords or connection strings.
Returns: note, profiles
list_recordingsARead-only
Recordings (activity sampled every 15 s for 1 or 24 h) kept with a profile's reports, newest first. Recordings made elsewhere can still be read with recording_report and their folder.
Inputs: profile. Returns: recordings
list_rulesARead-only
List the Lens rule catalog (health checks): ID, engine, category, severity and title. Kind "series" rules judge recordings, the others run in a check.
Inputs: engine. Returns: rules
list_tablesARead-only
Tables and views visible to the profile's login in a database: schema, name, type, estimated rows, size and whether the login can read them. Start here, then describe_table, then query.
Inputs: profile (required), filter, schema, database. Returns: note, rows, columns, truncated
queryARead-only
Run one read-only SELECT (or WITH ... SELECT) on a profile and get columns and rows. Aggregate in SQL (GROUP BY, TOP/LIMIT) instead of fetching raw rows: results stop at the profile's row limit (500 unless the user changed it), cells at 2 KB, and truncated: true means the answer is partial. Writes, EXEC, multiple statements and functions with side effects are refused; quote a column named like an SQL keyword. SQL Server reads uncommitted data, like the health check: counts and sums taken while other transactions are open can be off, so present them as approximate, not final.
Inputs: sql (required), profile (required), database, max_rows, +1 more. Returns: note, rows, columns, warning, +2 more
record_commandARead-only
The command the user runs in a terminal (or on the server) to record a profile for up to 1 h, or 24 h with the free key. You cannot start a recording: give the user this command.
Inputs: profile (required), duration. Returns: note, command, report_command, server_command
recording_reportARead-only
Analyse a recording, optionally for a period (e.g. an incident): time coverage, gaps without data, findings as episodes (blocking, waits, long queries, workers or connections), peak of each chart and the top queries. Also writes the HTML report into the recording folder.
Inputs: folder (required), to, from. Returns: to, from, gaps, charts, +8 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools target distinct resources and actions, with a clear progression from list_tables to describe_table to query. Some overlap exists in the reporting cluster (list_recordings, history, recording_report, check, compare), but the descriptions largely disambiguate them.
The set is mostly consistent verb_noun naming (list_recordings, describe_table, get_finding, explain_rule, record_command). The single-word names query, check, compare, and history are minor deviations but still readable and conventional for their actions.
Fourteen tools is well within a reasonable range for a database health-check and query server. Each tool appears to earn its place across discovery, querying, checking, and reporting workflows.
The surface covers profile/database/table discovery, querying, health checks, history, findings, rule explanation, recordings, and comparisons. Minor gaps remain around creating or editing profiles and managing recordings directly, though users can work around these via the external registration/recording flow.
Maintenance
Related MCP Connectors
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
DBRE-grade SQL analysis inside any MCP client. No connection. No install. Paste a query.
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Related MCP Servers
- AlicenseAqualityBmaintenanceSQL Server MCP server with AST-based query validation, read-only safety, schema exploration, ER diagram generation, and DBA toolkit integration (First Responder Kit, DarlingData, sp_WhoIsActive).128MIT
- AlicenseAqualityCmaintenanceRead-only MySQL/MariaDB MCP server for running SELECT queries safely, with automatic read-only enforcement and query limits.314 npmMIT
- AlicenseAqualityDmaintenanceEnables natural language to SQL queries on MSSQL databases via Claude, with safe SELECT-only execution and schema discovery.3ISC
- AlicenseNot gradedqualityFmaintenanceRead-only MCP server for SQL databases (SQL Server, Postgres, SQLite) with multi-server support and three-layer safety using AST validation and linting.MIT