n8500x/sql-server-rca-assistant

•Updated about 2 months ago

AI root-cause analysis for SQL Server, on any model endpoint (LiteLLM/vLLM/OpenAI/Anthropic).

Image

1.5K

n8500x/sql-server-rca-assistant repository overview

⁠sql-server-rca-assistant — AI root-cause analysis for SQL Server, any model endpoint

An AI DBA assistant that diagnoses SQL Server performance incidents. It runs First Responder Kit⁠ diagnostics + DMV telemetry and uses an LLM agent to turn waits, blocking, expensive queries, and resource pressure into plain-language root causes and next steps.

Based on dzigz/sql-server-rca-assistant⁠, extended so the AI runs on any model endpoint — your on-prem LiteLLM⁠ gateway, vLLM, Ollama, Azure OpenAI, or the native Anthropic API. Pick the provider and model with env vars; no rebuild.

Browser ──▶ :3000 (web UI) ──proxy──▶ :8000 (API + agent)
                                          ├─▶ model endpoint (LiteLLM / vLLM / Anthropic / …)
                                          ├─▶ SQL Server  (DMV + First Responder Kit)
                                          └─▶ ClickHouse  (optional trend baseline)

The frontend and backend run in one container. Expose port 3000 and you're done.

⁠1. Fastest start (60 seconds)

Point it at an OpenAI-compatible endpoint (here, a LiteLLM gateway) and your SQL Server:

docker run --rm -p 3000:3000 \
  -e RCA_LLM_PROVIDER=openai \
  -e RCA_BASE_URL=http://host.docker.internal:4000/v1 \
  -e RCA_MODEL=bedrock-claude \
  -e OPENAI_API_KEY=not-needed \
  -e SQLSERVER_HOST=your-sqlserver-host \
  -e SQLSERVER_USER=sa \
  -e SQLSERVER_PASSWORD='YourSecurePassword123!' \
  n8500x/sql-server-rca-assistant:latest

Open http://localhost:3000⁠ and ask it to investigate an incident or run a health check.

⁠2. Choosing your model endpoint

Everything is env-driven. Switch endpoints/models without rebuilding.

Endpoint	Env vars
LiteLLM gateway (recommended on-prem)	`RCA_LLM_PROVIDER=openai` · `RCA_BASE_URL=http://litellm...:4000/v1` · `RCA_MODEL=<served-name>` · `OPENAI_API_KEY=<key-if-enforced>`
vLLM / Ollama / TGI	`RCA_LLM_PROVIDER=openai` · `RCA_BASE_URL=http://<host>:<port>/v1` · `RCA_MODEL=<model>`
Azure OpenAI	`RCA_LLM_PROVIDER=openai` · `RCA_BASE_URL=https://<res>.openai.azure.com/openai/deployments/<dep>` · `RCA_MODEL=<dep>`
api.openai.com	`RCA_LLM_PROVIDER=openai` · `RCA_MODEL=gpt-4o` · `OPENAI_API_KEY=sk-...`
Native Anthropic	`RCA_LLM_PROVIDER=anthropic` · `RCA_MODEL=claude-opus-4-6` · `ANTHROPIC_API_KEY=sk-ant-...`

RCA_MODEL is required for the openai provider — it's the model name your endpoint serves. For reasoning models, add RCA_REASONING_EFFORT=medium.

⁠3. Environment variables

Variable	Default	Purpose
`RCA_LLM_PROVIDER`	`openai`	`openai` (any compatible endpoint) or `anthropic`
`RCA_MODEL`	—	Model name (required for `openai`)
`RCA_BASE_URL`	—	OpenAI-compatible base URL (also `OPENAI_BASE_URL`)
`OPENAI_API_KEY`	—	Key if your gateway enforces one (optional)
`ANTHROPIC_API_KEY`	—	Required only for `provider=anthropic`
`RCA_REASONING_EFFORT`	off	`low`/`medium`/`high`/`max` (reasoning models only)
`RCA_MAX_TOKENS`	`4096`	Max response tokens
`RCA_TEMPERATURE`	`0.1`	Sampling temperature
`RCA_MAX_TOOL_ITERATIONS`	`30`	Agent tool-loop cap
`SQLSERVER_HOST` / `_PORT` / `_USER` / `_PASSWORD` / `_DATABASE`	— / `1433` / `sa` / — / `master`	SQL Server target
`SIM_ENABLE_MONITORING`	`0`	Set `1` to enable ClickHouse trend analysis
`CLICKHOUSE_HOST` / `_PORT` / …	—	ClickHouse endpoint (when monitoring on)

⁠4. Ports

Port	Service
3000	Web UI (front door — proxies `/api/*` to the backend)
8000	Backend API + `/health` (usually internal only)

⁠5. Deployment examples (one per method)

Everything below runs the same image; only the wrapper changes.

⁠A. `docker run` (single container)

docker run -d --name sql-rca -p 3000:3000 \
  -e RCA_LLM_PROVIDER=openai \
  -e RCA_BASE_URL=http://host.docker.internal:4000/v1 \
  -e RCA_MODEL=bedrock-claude \
  -e OPENAI_API_KEY=not-needed \
  -e SQLSERVER_HOST=your-sqlserver-host \
  -e SQLSERVER_USER=sa \
  -e SQLSERVER_PASSWORD='YourSecurePassword123!' \
  n8500x/sql-server-rca-assistant:latest
# UI: http://localhost:3000

⁠B. Docker Compose

A ready docker-compose.yml and .env.example ship in the repo:

cp .env.example .env    # edit RCA_BASE_URL, RCA_MODEL, SQLSERVER_*
docker compose up -d
# UI: http://localhost:3000

Prefer inline instead of a repo checkout? This is equivalent:

# docker-compose.yml
services:
  sql-rca:
    image: n8500x/sql-server-rca-assistant:latest
    ports:
      - "3000:3000"
    environment:
      RCA_LLM_PROVIDER: openai
      RCA_BASE_URL: http://litellm:4000/v1
      RCA_MODEL: bedrock-claude
      OPENAI_API_KEY: not-needed
      SQLSERVER_HOST: mssql
      SQLSERVER_USER: sa
      SQLSERVER_PASSWORD: YourSecurePassword123!
      SQLSERVER_DATABASE: master
    restart: unless-stopped

⁠C. Helm on OpenShift (Route — default)

helm upgrade --install rca ./helm/sql-server-rca-assistant -n sql-rca --create-namespace \
  --set ai.baseUrl=http://litellm.llm.svc.cluster.local:4000/v1 \
  --set ai.model=bedrock-claude \
  --set sqlServer.host=mssql.prod.svc \
  --set secrets.sqlServerPassword='YourSecurePassword123!'

oc get route rca-sql-server-rca-assistant -o jsonpath='{.spec.host}{"\n"}'

⁠D. Helm on Kubernetes (Ingress instead of Route)

helm upgrade --install rca ./helm/sql-server-rca-assistant -n sql-rca --create-namespace \
  --set route.enabled=false \
  --set ingress.enabled=true \
  --set ingress.host=sql-rca.example.com \
  --set ingress.className=nginx \
  --set ai.baseUrl=http://litellm.llm.svc.cluster.local:4000/v1 \
  --set ai.model=bedrock-claude \
  --set sqlServer.host=mssql.prod.svc \
  --set secrets.sqlServerPassword='YourSecurePassword123!'

⁠E. Helm with an existing Secret (GitOps / no plaintext in values)

oc create secret generic rca-secrets -n sql-rca \
  --from-literal=OPENAI_API_KEY=not-needed \
  --from-literal=SQLSERVER_PASSWORD='YourSecurePassword123!'

helm upgrade --install rca ./helm/sql-server-rca-assistant -n sql-rca \
  --set secrets.create=false \
  --set secrets.existingSecret=rca-secrets \
  --set ai.baseUrl=http://litellm.llm.svc.cluster.local:4000/v1 \
  --set ai.model=bedrock-claude \
  --set sqlServer.host=mssql.prod.svc

⁠F. Native Anthropic (public API, no gateway)

helm upgrade --install rca ./helm/sql-server-rca-assistant -n sql-rca --create-namespace \
  --set ai.provider=anthropic \
  --set ai.model=claude-opus-4-6 \
  --set secrets.anthropicApiKey=sk-ant-... \
  --set sqlServer.host=mssql.prod.svc \
  --set secrets.sqlServerPassword='YourSecurePassword123!'

⁠G. On-prem, NON-LiteLLM (vLLM direct) + full monitoring stack

Self-hosted model server (vLLM/Ollama/TGI) with the in-cluster ClickHouse + Grafana + DMV collector — nothing leaves the cluster:

helm upgrade --install rca ./helm/sql-server-rca-assistant -n sql-rca --create-namespace \
  --set ai.provider=openai \
  --set ai.baseUrl=http://vllm.llm.svc.cluster.local:8000/v1 \
  --set ai.model=Qwen2.5-72B-Instruct \
  --set sqlServer.host=mssql.prod.svc \
  --set secrets.sqlServerPassword='YourSecurePassword123!' \
  --set monitoring.enabled=true --set monitoring.deploy=true
# equivalently: -f ./helm/sql-server-rca-assistant/examples/values-vllm.yaml

Ready-made example value files: examples/values-vllm.yaml (on-prem non-LiteLLM), values-litellm.yaml, values-anthropic.yaml.

⁠H. Raw manifests (kustomize, no Helm)

cp openshift/base/secret.example.yaml openshift/base/secret.yaml   # edit
# edit openshift/base/configmap.yaml (RCA_BASE_URL, RCA_MODEL, SQLSERVER_*)
oc apply -k openshift/               # app only
oc apply -k openshift/monitoring/    # app + ClickHouse + Grafana + collector

⁠Monitoring stack images

The optional stack uses two extra images (both air-gap ready): n8500x/sql-server-rca-assistant-collector and n8500x/sql-server-rca-assistant-grafana (ClickHouse datasource + dashboards baked in). ClickHouse is the upstream clickhouse/clickhouse-server.

⁠Air-gapped note

The images are self-contained. Mirror them into your internal registry and, if using Helm, --set image.repository=<registry>/sql-server-rca-assistant (and the monitoring.*.image values). As long as the model endpoint is in-cluster (LiteLLM/vLLM), there is no external egress at runtime. The native Anthropic provider (F) is the exception — it needs egress to the API.

All deploy assets are baked into the app image under /app (Helm chart, OpenShift/kustomize manifests, example values, compose, docs) — extract them without the git repo:

id=$(docker create n8500x/sql-server-rca-assistant:latest)
docker cp "$id":/app/helm ./helm && docker cp "$id":/app/openshift ./openshift
docker rm "$id"

⁠6. What's inside / good to know

First Responder Kit (sp_Blitz*) is the diagnostic source of truth; the LLM narrates and correlates. Treat the AI output as assistive.
Optional application-code correlation — mount your app repo and it links slow queries to endpoints / ORM anti-patterns (N+1, etc.).
Upstream is a young project — pin the tag you test with in production.

Tags: latest plus dated YYYYMMDD-HHMMSS builds. License: MIT (upstream).

Tag summary

Recent tags

Content type

Image

Digest

sha256:7d12631a9…

Size

429.3 MB

Last updated

about 2 months ago

docker pull n8500x/sql-server-rca-assistant