Skip to content
Skills Library
Programming · Testing

sqlpysim

/sqlpysim

Public Preview Python-based port of sqlsim built on Microsoft's native `mssql-python` driver. USE FOR — running SQL queries, scripts, and multi-threaded workloads from Python environments; mixed workload files (`-workload`); live progress streaming (`-stream-json`); periodic query-statistic snapshots (`-querystats-interval`); comparing driver behavior between native ODBC (sqlsim) and `mssql-python`; producing sqlpysim JSON for automation. DO NOT USE FOR — sqlsim-only replay modes; setting an application name (`-app`, which the driver reserves); exact cross-tool JSON compatibility; or performan

Repository
sqlsimtools ↗
Licence
MIT
Last repository change
20.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
5
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Public Preview Python-based port of sqlsim built on Microsoft's native `mssql-python` driver. USE FOR — running SQL queries, scripts, and multi-threaded workloads from Python environments; mixed workload files (`-workload`); live progress streaming (`-stream-json`); periodic query-statistic snapshots (`-querystats-interval`); comparing driver behavior between native ODBC (sqlsim) and `mssql-python`; producing sqlpysim JSON for automation. DO NOT USE FOR — sqlsim-only replay modes; setting an application name (`-app`, which the driver reserves); exact cross-tool JSON compatibility; or performan

Original author description

Public Preview Python-based port of sqlsim built on Microsoft's native `mssql-python` driver. USE FOR — running SQL queries, scripts, and multi-threaded workloads from Python environments; mixed workload files (`-workload`); live progress streaming (`-stream-json`); periodic query-statistic snapshots (`-querystats-interval`); comparing driver behavior between native ODBC (sqlsim) and `mssql-python`; producing sqlpysim JSON for automation. DO NOT USE FOR — sqlsim-only replay modes; setting an application name (`-app`, which the driver reserves); exact cross-tool JSON compatibility; or performan

How it works

  1. Authoritative references
  2. Installation prerequisite and entry-point discovery
  3. Driver constraints (do not violate)
  4. Canonical patterns
  5. Installation prerequisite
  6. Rules
Original SKILL.md headings · 101 lines, 762 words
SKILL.md preview
---
name: sqlpysim
description: Public Preview Python-based port of sqlsim built on Microsoft's native `mssql-python` driver. USE FOR — running SQL queries, scripts, and multi-threaded workloads from Python environments; mixed workload files (`-workload`); live progress streaming (`-stream-json`); periodic query-statistic snapshots (`-querystats-interval`); comparing driver behavior between native ODBC (sqlsim) and `mssql-python`; producing sqlpysim JSON for automation. DO NOT USE FOR — sqlsim-only replay modes; setting an application name (`-app`, which the driver reserves); exact cross-tool JSON compatibility; or performance comparisons that require the lowest possible client overhead (use sqlsim instead).
---

# sqlpysim — Python port of sqlsim

## Authoritative references
Prefer the installed, version-matched copies in the workspace release overlay.
They match the script you will run and work offline:
- Consumer-facing agent instructions: `sqlpysim/AGENTS.md`
- User manual: `sqlpysim/sqlpysim.md`
- Examples: `sqlpysim/examples/`

If the overlay is not installed, for example when this skill comes from an
Agent Plugin, use the public copies. They track the latest release, so confirm
an option exists in `sqlpysim.py -h` before relying on it:
- <https://github.com/microsoft/sqlsimtools/blob/main/sqlpysim/AGENTS.md>
- <https://github.com/microsoft/sqlsimtools/blob/main/sqlpysim/sqlpysim.md>

Driver reference: <https://github.com/microsoft/mssql-python>

## Installation prerequisite and entry-point discovery
This plugin supplies agent guidance, not the sqlpysim runtime. Install a
[sqlpysim release](https://github.com/microsoft/sqlsimtools/releases) in the
workspace and install its Python requirements before running a workload.

Resolve the entry point in this order:
1. Workspace release overlay: `python .\sqlpysim\sqlpysim.py`.
2. An installed `sqlpysim` command on `PATH`.

If neither exists, stop and report the missing prerequisite. Do not assume the
Agent Plugin installation directory contains `sqlpysim.py`.

Canonical workspace command:
```powershell
python .\sqlpysim\sqlpysim.py <args>
```
Core query invocations follow sqlsim's command shape. Advanced flags,
validation, and JSON fields differ; consult the release notes before translating
commands or parsers between tools.

## Driver constraints (do not violate)
- Import: `from mssql_python import connect`
- **Reserved keywords** — driver controls these; do not set them in the connection string: `APP`, `Application Name`
- **Token auth** must use `attrs_before[SQL_COPT_SS_ACCESS_TOKEN]` with a UTF-16LE / SQLLEN-prefixed buffer. There is NO `access_token=` parameter.
  ```python
  SQL_COPT_SS_ACCESS_TOKEN = 1256
  token_bytes  = token.encode("utf-16le")
  token_struct = struct.pack(f"<I{len(token_bytes)}s", len(token_bytes), token_bytes)
  conn = connect(conn_str, attrs_before={SQL_COPT_SS_ACCESS_TOKEN: token_struct})
  ```

## Canonical patterns
```powershell
# Local SQL Server, Windows Auth
python .\sqlpysim\sqlpysim.py -S localhost -E -C -Q "SELECT 1"

# Azure SQL with token
$token = az account get-access-token --resource https://database.windows.net --query accessToken -o tsv
$token | python .\sqlpysim\sqlpysim.py -S myserver.database.windows.net -d mydb -T - -Q "SELECT 1"

# Multi-threaded workload (quiet)
python .\sqlpysim\sqlpysim.py -S localhost -E -C -Q "SELECT 1" -n 10 -r 100 -q

# JSON for automation
python .\sqlpysim\sqlpysim.py -S localhost -E -C -i .\workload.sql -n 4 -r 50 -json -o results.json

# Per-query server statistics using the sqlsim JSON contract
python .\sqlpysim\sqlpysim.py -S localhost -E -C -i .\workload.sql -n 4 -r 50 -querystats -json -q -o results.json

# Mixed workload groups from a sqlsim-format workload file
python .\sqlpysim\sqlpysim.py -S localhost -E -C -workload .\workload.json -q

# Live progress for a supervising process: one JSON event per line on stdout
python .\sqlpysim\sqlpysim.py -S localhost -E -C -Q "SELECT 1" -n 4 -r 500 -stream-json -q

# Live progress plus canonical final JSON
python .\sqlpysim\sqlpysim.py -S localhost -E -C -Q "SELECT 1" -n 4 -r 500 `
  -stream-json -json -o final-results.json -q

# Periodic server-statistic snapshots while the run is in flight
python .\sqlpysim\sqlpysim.py -S localhost -E -C -Q "SELECT 1" -n 4 -r 500 -querystats-interval 5 -querystats-file live.json -q

# Secure password input for local applications and automation
$password | python .\sqlpysim\sqlpysim.py -S localhost -U testuser -P - -Q "SELECT 1"
```

## Installation prerequisite
```powershell
python -m pip install -r .\sqlpysim\requirements.txt
```

## Rules
1. Verify any driver syntax against the official `mssql-python` docs before writing or modifying connection code. Do not invent parameters.
2. Never append `2>&1` or pipe through `Select-String`. Capture output into a PowerShell variable if needed.
3. Parse sqlpysim JSON with `ConvertFrom-Json`, but do not assume its schema is identical to sqlsim.
4. When comparing tools, limit assertions to documented shared behavior and account for driver-specific timing and metrics.
5. For applications and automation, use `-T -` or `-P -` with redirected stdin so secrets do not appear in process arguments.
6. `-querystats` reports sqlsim-compatible aggregates without querying DMVs or emitting query/plan hashes.
7. `-stream-json` turns on JSON mode. Combine it with `-json -o <file>` to keep NDJSON on stdout and write the canonical final result to the file; combined mode requires `-o`. Events are cumulative and `throughput_per_second` is a running average, so compute deltas between events for a current rate.
8. `-querystats-interval` implies `-querystats` and defaults its file to `querystats-live.json`. A write failure never fails the run and is reported once on the normal error channel, which is silent in `-json` and `-stream-json` modes; verify the file exists rather than relying on a message or the exit code.
9. `-app` is rejected: `mssql-python` reserves the application name and always reports `MSSQL-Python`. Use sqlsim when the application name matters.
10. Start load tests with a small `-n` value and scale gradually while monitoring client and server CPU, memory, network, and connection usage. High thread counts can exhaust client resources and invalidate results; use a dedicated client for significant load tests.

Versions

The database has no other skills named sqlpysim.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 276e2dcc9909 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100sqlsim
    Run SQL queries, scripts, or multi-threaded workloads against SQL Server, Azure SQL Database, Azure SQL Managed Instance, or SQL database in Microsoft Fabric using the sqlsim CLI. USE FOR — executing T-SQL ad-hoc or from a `.sql` file; stress / load testing with N threads × R…
  • 98sqlsimtools-build
    Build and test sqlsimtools from source. USE WHEN: cloning the repository, setting up a development environment, compiling sqlsim, preparing sqlpysim, building sqlsim Studio, running smoke tests or the full test suite, checking prerequisites, or diagnosing a build or test failure…
  • 100connect-from-python
    Connects a Python application to Azure SQL Database, choosing between Microsoft's first-party mssql-python driver and the incumbent pyodbc, and covering driver installation, the connection string each one wants, connection pooling, and Microsoft Entra ID including token-based…
  • 100connect-from-typescript-and-node
    Connects a TypeScript or JavaScript application to Azure SQL Database with the mssql package over tedious: which packages to install, where the connection pool has to live, how to type query results, and how to authenticate with Microsoft Entra ID without a password. Use when a…
  • 100mormot2-db
    Use for raw SQL via TSqlDB* providers, picking DB engines (SQLite, PostgreSQL, MSSQL, Oracle, Mongo, ZEOS, ODBC), pooling, BSON. Do NOT use for ORM (mormot2-orm) or REST (mormot2-rest-soa).
  • 100mariadb-connector-odbc-usage
    MariaDB-specific behavior of MariaDB Connector/ODBC (the ODBC 3.8-compliant driver built on MariaDB Connector/C) for application code — that the DSN-less keyword is `DRIVER={MariaDB ODBC 3.2 Driver}` on Windows, or a registered driver name / `.so` path on Linux and macOS; that…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.