Skip to main content
Glama
codeDB Lens

codeDB Lens

Official

v0.8: check (with an executive summary and --redact for sharing), compare, and record + report to 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

Installer (per user, no admin) or portable .zip

Windows (Scoop)

scoop bucket add codedb https://github.com/codedb-io/codedb-lens then scoop install codedb/codedb-lens

Linux

.deb / .rpm from the latest release, or the tarball for x64 / arm64

Docker

docker run --rm -e PG_DSN -v "$PWD:/out" ghcr.io/codedb-io/codedb-lens check --engine pg --dsn-env PG_DSN --out /out

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_DSN

Passwords 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 SELECT at a time, within row and time limits.

codedb-lens mcp install --client claude-desktop --profile prod   # or vscode, cursor, claude-code

The 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 tools
checkB
Read-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

compareA
Read-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_tableA
Read-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_ruleA
Read-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_findingA
Read-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

historyA
Read-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_databasesA
Read-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_profilesA
Read-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_recordingsA
Read-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_rulesA
Read-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_tablesA
Read-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

queryA
Read-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_commandA
Read-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_reportA
Read-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

    A3.9/5.0

    Scored across 14 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      SQL 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).
      12
      8
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Read-only MySQL/MariaDB MCP server for running SELECT queries safely, with automatic read-only enforcement and query limits.
      3
      14 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables natural language to SQL queries on MSSQL databases via Claude, with safe SELECT-only execution and schema discovery.
      3
      ISC
    • A
      license
      Not graded
      quality
      F
      maintenance
      Read-only MCP server for SQL databases (SQL Server, Postgres, SQLite) with multi-server support and three-layer safety using AST validation and linting.
      MIT