# Mssql

> Query and execute Microsoft SQL Server SQL through a JSON CLI. Use when the user explicitly asks to inspect MSSQL/SQL Server or run a confirmed DDL, DML, or administrative statement. Access is limited by the configured SQL Server account grants.

- Skill: `bgevorkian/mssql` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add bgevorkian/mssql`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bgevorkian/mssql/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- License: MIT
- Author: bgevorkian (https://skillmd.com/u/bgevorkian)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bgevorkian/mssql

---


# MSSQL

Generic Microsoft SQL Server JSON CLI. Read commands use guarded SQL and read-only connection intent; `exec` runs one statement allowed by the configured SQL Server account.

## Local `.env`

The CLI automatically loads a private `.env` beside this `SKILL.md` through `pass-cli`. Copy `.env.example` to `.env` and replace placeholders with environment values or secret-manager pointers.

A single `.env` may hold several namespaced profiles. Select one with `--profile`:

```bash
uv run --python 3.13 --with pymssql python scripts/ms.py --profile analytics query --sql "SELECT @@VERSION"
```

Without `--profile`, the CLI uses ordinary `MSSQL_*` variables.

| Variable | Flag | Default |
|---|---|---|
| `MSSQL_HOST` | `--host` | none |
| `MSSQL_PORT` | `--port` | `1433` |
| `MSSQL_DATABASE` | `--database` | none |
| `MSSQL_USER` | `--user` | none |
| `MSSQL_PASSWORD` | none | empty |
| `MSSQL_ENCRYPTION` | `--encryption` | `require` |
| `MSSQL_TDS_VERSION` | `--tds-version` | driver default |
| `MSSQL_APPNAME` | `--appname` | `mssql` |

Never pass a password as a CLI argument or commit a real `.env`.

## Read

```bash
uv run --python 3.13 --with pymssql python scripts/ms.py query --sql "SELECT TOP 10 * FROM dbo.events"
uv run --python 3.13 --with pymssql python scripts/ms.py list-databases
uv run --python 3.13 --with pymssql python scripts/ms.py list-schemas
uv run --python 3.13 --with pymssql python scripts/ms.py list-tables --schema dbo
uv run --python 3.13 --with pymssql python scripts/ms.py describe-table --schema dbo --table events
```

Read commands reject obvious mutations, use SQL Server read-only connection intent, and cap results.

## Execute

Use `exec` only after the user approves the exact operation and target:

```bash
uv run --python 3.13 --with pymssql python scripts/ms.py \
  exec --sql "ALTER TABLE dbo.events ADD source nvarchar(30) NULL"
```

`exec` accepts one DDL, DML, or administrative statement. It rejects empty and multi-statement SQL. There is no local write authorization gate: SQL Server account grants are the authorization boundary.

`--sql` accepts literal SQL, `@file.sql`, or `-`. `--params` accepts a JSON array or object.

## Safety contract

- Obtain fresh user approval before each mutation scope.
- Read commands retain local SQL guards, timeout, row limits, and read-only connection intent.
- `exec` uses a normal transaction and rolls back on failure.
- `exec` rejects empty and multi-statement SQL; the configured account decides what is allowed.
- Do not print secrets, connection strings, `.env` contents, or environment variables.
- Ask before touching sensitive data, even in read mode.

## Output

```json
{
  "rows": [{"name": "master"}],
  "row_count": 1
}
```

Execution returns `{"ok": true}` plus affected rows or returned data when available.

## Tests

```bash
uv run --python 3.13 --with pymssql python tests/test_ms.py
```