# microsoft/mssql-python architecture

> Architecture diagram of the GitHub repository microsoft/mssql-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/mssql-python
- Repository: https://github.com/microsoft/mssql-python

## Overview

mssql-python is a Python DB-API 2.0 driver for SQL Server and Azure SQL, using DDBC for direct native connections. The main workflow is an application creating a connection, parsing connection settings and authenticating, executing statements through cursors, and fetching Python rows from SQL Server. The graph also preserves the documented async API and opt-in native-provider selection. Native binding internals are represented at their implementation paths; some links rely on README or source-index references because the relevant source was not excerpted.

Main entry points: [`mssql_python/connection.py`](https://github.com/microsoft/mssql-python/blob/main/mssql_python/connection.py) (Connection lifecycle), [`mssql_python/cursor.py`](https://github.com/microsoft/mssql-python/blob/main/mssql_python/cursor.py) (Query and fetch), [`mssql_python/async_query/async_cursor.py`](https://github.com/microsoft/mssql-python/blob/main/mssql_python/async_query/async_cursor.py) (Async cursor), [`mssql_python/ddbc_bindings.py`](https://github.com/microsoft/mssql-python/blob/main/mssql_python/ddbc_bindings.py) (Binding loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Python driver API"]
  node_public_api["DB-API exports<br/>[__init__.py]"]
  node_connection["Connection lifecycle<br/>[connection.py]"]
  node_cursor["Query and fetch<br/>[cursor.py]"]
  node_rows["Row results<br/>[row.py]"]
end

subgraph group_connect["Connection setup"]
  node_parser["Connection parsing"]
  node_builder["Connection building"]
  node_auth["Entra authentication<br/>[auth.py]"]
  node_pooling["Connection pooling<br/>[pooling.py]"]
  node_provider["ODBC provider selection<br/>[odbc_provider.py]"]
end

subgraph group_native["Native execution"]
  node_binding_loader["Binding loader<br/>[ddbc_bindings.py]"]
  node_native_api["Native DDBC bindings<br/>[ddbc_bindings.cpp]"]
  node_native_connection["Native connection<br/>[connection.cpp]"]
end

subgraph group_extensions["Async and providers"]
  node_async_connection["Async connection"]
  node_async_cursor["Async cursor<br/>[async_cursor.py]"]
  node_async_execute["Async execution<br/>[async_execute.py]"]
  node_async_fetch["Async fetching<br/>[async_fetch.py]"]
  node_rs_provider["Rust ODBC provider"]
end

node_application(("Python application"))
node_sql_server[("SQL Server / Azure SQL")]

node_application -->|"uses"| node_public_api
node_public_api -->|"creates"| node_connection
node_connection -->|"parses"| node_parser
node_connection -->|"builds"| node_builder
node_connection -->|"authenticates"| node_auth
node_connection -->|"uses"| node_pooling
node_connection -->|"selects"| node_provider
node_connection -->|"creates"| node_cursor
node_cursor -->|"returns"| node_rows
node_connection -->|"calls"| node_binding_loader
node_cursor -->|"calls"| node_binding_loader
node_binding_loader -.->|"loads"| node_native_api
node_native_api -->|"uses"| node_native_connection
node_native_connection -->|"connects"| node_sql_server
node_application -->|"uses"| node_async_connection
node_async_connection -->|"creates"| node_async_cursor
node_async_cursor -->|"delegates"| node_async_execute
node_async_cursor -->|"delegates"| node_async_fetch
node_provider -.->|"selects optionally"| node_rs_provider

click node_public_api "https://github.com/microsoft/mssql-python/blob/main/mssql_python/__init__.py"
click node_connection "https://github.com/microsoft/mssql-python/blob/main/mssql_python/connection.py"
click node_cursor "https://github.com/microsoft/mssql-python/blob/main/mssql_python/cursor.py"
click node_rows "https://github.com/microsoft/mssql-python/blob/main/mssql_python/row.py"
click node_parser "https://github.com/microsoft/mssql-python/blob/main/mssql_python/connection_string_parser.py"
click node_builder "https://github.com/microsoft/mssql-python/blob/main/mssql_python/connection_string_builder.py"
click node_auth "https://github.com/microsoft/mssql-python/blob/main/mssql_python/auth.py"
click node_pooling "https://github.com/microsoft/mssql-python/blob/main/mssql_python/pooling.py"
click node_provider "https://github.com/microsoft/mssql-python/blob/main/mssql_python/odbc_provider.py"
click node_binding_loader "https://github.com/microsoft/mssql-python/blob/main/mssql_python/ddbc_bindings.py"
click node_native_api "https://github.com/microsoft/mssql-python/blob/main/mssql_python/pybind/ddbc_bindings.cpp"
click node_native_connection "https://github.com/microsoft/mssql-python/blob/main/mssql_python/pybind/connection/connection.cpp"
click node_async_connection "https://github.com/microsoft/mssql-python/blob/main/mssql_python/async_query/async_connection.py"
click node_async_cursor "https://github.com/microsoft/mssql-python/blob/main/mssql_python/async_query/async_cursor.py"
click node_async_execute "https://github.com/microsoft/mssql-python/blob/main/mssql_python/async_query/async_execute.py"
click node_async_fetch "https://github.com/microsoft/mssql-python/blob/main/mssql_python/async_query/async_fetch.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_connection,node_cursor,node_rows toneBlue
class node_parser,node_builder,node_auth,node_pooling,node_provider,node_sql_server toneAmber
class node_binding_loader,node_native_api,node_native_connection toneMint
class node_async_connection,node_async_cursor,node_async_execute,node_async_fetch,node_rs_provider toneRose
class node_application toneIndigo
```

## Components

### Python driver API

- [DB-API exports](https://github.com/microsoft/mssql-python/blob/main/mssql_python/__init__.py): `mssql_python/__init__.py`
- [Connection lifecycle](https://github.com/microsoft/mssql-python/blob/main/mssql_python/connection.py): `mssql_python/connection.py`
- [Query and fetch](https://github.com/microsoft/mssql-python/blob/main/mssql_python/cursor.py): `mssql_python/cursor.py`
- [Row results](https://github.com/microsoft/mssql-python/blob/main/mssql_python/row.py): `mssql_python/row.py`

### Connection setup

- [Connection parsing](https://github.com/microsoft/mssql-python/blob/main/mssql_python/connection_string_parser.py): `mssql_python/connection_string_parser.py`
- [Connection building](https://github.com/microsoft/mssql-python/blob/main/mssql_python/connection_string_builder.py): `mssql_python/connection_string_builder.py`
- [Entra authentication](https://github.com/microsoft/mssql-python/blob/main/mssql_python/auth.py): `mssql_python/auth.py`
- [Connection pooling](https://github.com/microsoft/mssql-python/blob/main/mssql_python/pooling.py): `mssql_python/pooling.py`
- [ODBC provider selection](https://github.com/microsoft/mssql-python/blob/main/mssql_python/odbc_provider.py): `mssql_python/odbc_provider.py`

### Native execution

- [Binding loader](https://github.com/microsoft/mssql-python/blob/main/mssql_python/ddbc_bindings.py): `mssql_python/ddbc_bindings.py`
- [Native DDBC bindings](https://github.com/microsoft/mssql-python/blob/main/mssql_python/pybind/ddbc_bindings.cpp): `mssql_python/pybind/ddbc_bindings.cpp`
- [Native connection](https://github.com/microsoft/mssql-python/blob/main/mssql_python/pybind/connection/connection.cpp): `mssql_python/pybind/connection/connection.cpp`

### Async and providers

- [Async connection](https://github.com/microsoft/mssql-python/blob/main/mssql_python/async_query/async_connection.py): `mssql_python/async_query/async_connection.py`
- [Async cursor](https://github.com/microsoft/mssql-python/blob/main/mssql_python/async_query/async_cursor.py): `mssql_python/async_query/async_cursor.py`
- [Async execution](https://github.com/microsoft/mssql-python/blob/main/mssql_python/async_query/async_execute.py): `mssql_python/async_query/async_execute.py`
- [Async fetching](https://github.com/microsoft/mssql-python/blob/main/mssql_python/async_query/async_fetch.py): `mssql_python/async_query/async_fetch.py`
- **Rust ODBC provider**

### Other components

- **Python application**
- **SQL Server / Azure SQL**

## Connections

- Python application → DB-API exports: uses (evidence: `README.md`)
- DB-API exports → Connection lifecycle: creates (evidence: `mssql_python/__init__.py`)
- Connection lifecycle → Connection parsing: parses (evidence: `mssql_python/connection.py`)
- Connection lifecycle → Connection building: builds (evidence: `mssql_python/connection.py`)
- Connection lifecycle → Entra authentication: authenticates (evidence: `mssql_python/connection.py`)
- Connection lifecycle → Connection pooling: uses (evidence: `mssql_python/connection.py`)
- Connection lifecycle → ODBC provider selection: selects (evidence: `README.md`)
- Connection lifecycle → Query and fetch: creates (evidence: `mssql_python/connection.py`)
- Query and fetch → Row results: returns (evidence: `mssql_python/cursor.py`)
- Connection lifecycle → Binding loader: calls (evidence: `mssql_python/connection.py`)
- Query and fetch → Binding loader: calls (evidence: `mssql_python/cursor.py`)
- Binding loader → Native DDBC bindings: loads (evidence: `README.md`)
- Native DDBC bindings → Native connection: uses (evidence: `mssql_python/pybind/ddbc_bindings.cpp`)
- Native connection → SQL Server / Azure SQL: connects (evidence: `README.md`)
- Python application → Async connection: uses (evidence: `README.md`)
- Async connection → Async cursor: creates (evidence: `mssql_python/async_query/async_connection.py`)
- Async cursor → Async execution: delegates (evidence: `mssql_python/async_query/async_cursor.py`)
- Async cursor → Async fetching: delegates (evidence: `mssql_python/async_query/async_cursor.py`)
- ODBC provider selection → Rust ODBC provider: selects optionally (evidence: `README.md`)
