Sherlock

A read-only database query tool for AI assistants

Give your AI the power to investigate — without the power to destroy.

$ curl -fsSL https://raw.githubusercontent.com/michaelbromley/sherlock/main/install.sh | bash
View on GitHub Quick Start ↓

Ask, don't write SQL

Ask your AI a question about your data. Sherlock translates it into safe, read-only queries.

Five databases, one tool

PostgreSQL, MySQL, SQLite, MSSQL, and Redis. One binary, one command.

Security by default

Read-only enforced, OS keychain credentials, SQL injection prevention built in.

Two Commands, That's It

After installing, these are the only two commands you need to know.

Terminal
$ sherlock manage

Manage your connections

Interactive wizard that handles everything — add databases, update passwords, store credentials securely in your OS keychain.

  • Add, edit, and delete connections
  • Store passwords in OS keychain
  • Set project directories for auto-detection
  • Test connections before saving
Terminal
$ sherlock update

Always up to date

One command to check for new releases and update in-place. No package manager needed, no manual downloads.

  • Checks GitHub for the latest release
  • Downloads the right binary for your platform
  • Replaces the old version automatically
  • Shows you what changed

See It in Action

Real-world scenarios showing how your AI assistant uses Sherlock to investigate databases.

Why is checkout so slow on prod-db?
AI Assistant

Let me investigate the checkout performance. I'll start by checking the indexes on order-related tables and looking at table statistics.

sherlock indexes -c prod-db -t orders sherlock stats -c prod-db -t orders

The orders table has 2.3M rows but no index on customer_id — which is used in every checkout lookup. Sequential scans are taking ~1,200ms. Let me verify with the query plan:

sherlock query -c prod-db "EXPLAIN SELECT * FROM orders WHERE customer_id = 42"

Confirmed — it's a sequential scan. Adding an index on orders.customer_id should bring that down to under 5ms.

Generate a monthly sales comparison for Q4.
AI Assistant

I'll map out the schema first to understand the relationship between orders and line items, then build the report.

sherlock introspect -c prod-db sherlock fk -c prod-db -t order_items

Got it — order_items joins to orders via order_id, and products via product_id. Now I can aggregate:

sherlock query -c prod-db "SELECT DATE_TRUNC('month', o.created_at) AS month, SUM(oi.quantity * oi.unit_price) AS revenue, COUNT(DISTINCT o.id) AS order_count FROM orders o JOIN order_items oi ON o.id = oi.order_id WHERE o.created_at >= '2025-10-01' AND o.created_at < '2026-01-01' GROUP BY month ORDER BY month"

Here's your Q4 breakdown: October did £142k across 1,847 orders, November £218k (Black Friday bump), and December £195k. November was up 53% month-over-month.

User jane@example.com says she can't complete checkout. What's wrong?
AI Assistant

Let me look up her account and check for anything that might block checkout.

sherlock query -c prod-db "SELECT id, email, status, suspended_at, suspension_reason FROM users WHERE email = 'jane@example.com'"

Found it — her account was suspended on 2026-02-14 with reason: "payment_dispute". Let me check the audit trail:

sherlock query -c prod-db "SELECT action, details, created_at, performed_by FROM audit_log WHERE user_id = 4872 ORDER BY created_at DESC LIMIT 5"

The suspension was triggered automatically by the payment dispute system. Her PayPal dispute from order #8891 was resolved in her favour 3 days ago, but the account was never reinstated. This looks like a bug in the auto-reinstatement flow.

I'm new on this project. Can you explain the database structure?
AI Assistant

Welcome aboard! Let me map out the entire schema and the relationships between tables.

sherlock introspect -c prod-db sherlock fk -c prod-db

Here's the lay of the land. You've got 23 tables organised into four domains:

Users & Auth: users, sessions, password_resets, roles, user_roles

Products: products, categories, product_categories, inventory

Orders: orders, order_items, payments, refunds, shipping

System: audit_log, settings, migrations, jobs, notifications

The core flow is: usersordersorder_itemsproducts. Payments link back to orders with a one-to-many (supporting split payments).

Is our Redis cache actually helping? It feels like the app is still slow.
AI Assistant

Let me check the Redis server stats and see what's going on in the cache.

sherlock info -c redis-prod sherlock keys -c redis-prod "sess:*"

Hit rate is only 60% — that's low. You've got 12,400 session keys with a 30-minute TTL, but product caches are expiring every 60 seconds. Let me check for slow operations:

sherlock slowlog -c redis-prod sherlock inspect -c redis-prod "product:catalog:all"

Found it. The slow log shows KEYS * being called every 10 seconds — that's a full keyspace scan in production with 48k keys. It's coming from the health check endpoint. The product catalog key is 4.2MB of serialised JSON being re-fetched every minute. Two fixes needed: replace KEYS with SCAN in the health check, and bump the product cache TTL to at least 5 minutes.

Supported Databases

One binary to investigate them all.

PostgreSQL

Tables, schemas, queries, indexes, foreign keys, and data profiling.

MySQL / MariaDB

Full introspection, stats, and read-only queries.

MSSQL / SQL Server

Full introspection, schemas, queries, and stats for SQL Server.

SQLite

Local file-based databases, great for development and testing.

Redis

Server info, key scanning, value inspection, and slow log analysis.

Built Paranoid

Security isn't an afterthought — it's the entire point.

Read-only enforced

SQL validation blocks any mutation. Redis uses a command whitelist. No write ever gets through.

OS keychain storage

Passwords stored in macOS Keychain, Windows Credential Manager, or Linux Secret Service.

Zero network exposure

No server, no open ports. Sherlock connects outbound only, never listens for inbound traffic.

Single binary

~57MB standalone executable. Zero runtime dependencies. Download and run.

SQL injection prevention

Keyword blocking in subqueries. Nested mutations can't sneak through SELECT wrappers.

Query logging opt-in

All logging disabled by default. Opt in when you need an audit trail.

Get Started in 60 Seconds

Three steps from zero to database investigation.

1

Install

One command, no dependencies.

curl -fsSL https://raw.githubusercontent.com/michaelbromley/sherlock/main/install.sh | bash
2

Configure

Interactive wizard sets up your connection and stores credentials securely.

sherlock manage
3

Investigate

Ask your AI questions about your data.

"Show me the top customers by order value from prod-db"