# snowflakedb/snowflake-connector-python architecture

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

- Interactive diagram: https://gitdiagram.com/snowflakedb/snowflake-connector-python
- Repository: https://github.com/snowflakedb/snowflake-connector-python

## Overview

#### Purpose and entry points
This is the Snowflake Python connector: a Python 3.10+ DB-API 2.0 driver for connecting to Snowflake, executing SQL, transferring staged files, and materializing results. Public synchronous entry points are `snowflake.connector` and DB-API connection creation in `src/snowflake/connector/__init__.py` and `src/snowflake/connector/dbapi.py`; the primary lifecycle implementation is `src/snowflake/connector/connection.py`. An async API is independently implemented under `src/snowflake/connector/aio/__init__.py`.

#### Connection, session, and query control
`SnowflakeConnection` establishes a Snowflake session, owns session parameters/state, coordinates authentication and HTTP operations, and creates cursors. Cursors submit SQL, handle bindings and multi-statement execution, expose fetch APIs, and manage query cancellation/status boundaries.
Paths: `src/snowflake/connector/connection.py`, `src/snowflake/connector/cursor.py`, `src/snowflake/connector/session_manager.py`.

#### Authentication boundary
Authentication is strategy/plugin based: the connection delegates credentials and login-token acquisition to plugins for password/MFA, key pair/JWT, OAuth variants, PAT, external browser/Okta, and workload identity. Token caching and browser callback handling are adjacent concerns.
Paths: `src/snowflake/connector/auth/by_plugin.py`, `src/snowflake/connector/auth/keypair.py`, `src/snowflake/connector/auth/workload_identity.py`.

#### Network and transport security
The network layer sends Snowflake REST requests, applies retry/backoff, proxy configuration, redirects, TLS hardening, and session renewal. Certificate validation includes OCSP/CRL support; a vendored Requests/urllib3 stack supplies core HTTP transport behavior.
Paths: `src/snowflake/connector/network.py`, `src/snowflake/connector/ocsp_snowflake.py`, `src/snowflake/connector/vendored/requests/sessions.py`.

#### Results and Python type conversion
Query responses become result batches/result sets, then cursor fetches. The converter layer maps Snowflake wire values to Python types and supports alternate conversion modes. Arrow context and bundled C++/Cython nanoarrow iterators form the performance-critical Arrow decoding path, including Pandas-oriented consumption.
Paths: `src/snowflake/connector/result_set.py`, `src/snowflake/connector/converter.py`, `src/snowflake/connector/nanoarrow_cpp/ArrowIterator/nanoarrow_arrow_iterator.pyx`.

#### File staging and cloud storage
PUT/GET and bind-upload flows pass through a file-transfer orchestration layer that compresses/encrypts files and selects storage clients. Implementations target S3, Azure Blob Storage, GCS, and local storage; these are an external-data-plane boundary distinct from Snowflake query REST traffic.
Paths: `src/snowflake/connector/file_transfer_agent.py`, `src/snowflake/connector/storage_client.py`, `src/snowflake/connector/s3_storage_client.py`.

#### Async parity and observability
The `aio` package mirrors core connection, cursor, auth, network, results, telemetry, and cloud-storage flows using async implementations rather than wrapping the synchronous path. Telemetry is emitted from connector activity and can be disabled through connection/session settings; out-of-band telemetry is separated explicitly.
Paths: `src/snowflake/connector/aio/_connection.py`, `src/snowflake/connector/aio/_file_transfer_agent.py`, `src/snowflake/connector/telemetry.py`.

#### Runtime, native artifacts, and delivery
Primary runtime is Python, packaged through PEP 517/setuptools (`pyproject.toml`, `setup.py`). Native pieces include nanoarrow C++/Cython sources and platform-specific Rust `sf_mini_core` binaries used by the driver. CI builds wheels across Linux, macOS, and Windows, including Dockerized and FIPS/Lambda-oriented environments.
Paths: `pyproject.toml`, `src/snowflake/connector/minicore/`, `ci/build_docker.sh`.

Main entry points: [`src/snowflake/connector/connection.py`](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/connection.py) (SnowflakeConnection), [`src/snowflake/connector/network.py`](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/network.py) (Network layer), [`src/snowflake/connector/cursor.py`](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/cursor.py) (Cursor), [`src/snowflake/connector/auth/by_plugin.py`](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/auth/by_plugin.py) (Auth plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sync["Synchronous connector"]
  node_public_api["DB-API public API<br/>Python API<br/>[__init__.py]"]
  node_connection["SnowflakeConnection<br/>connection lifecycle<br/>[connection.py]"]
  node_session_manager["Session manager<br/>session control<br/>[session_manager.py]"]
  node_cursor["Cursor<br/>query control<br/>[cursor.py]"]
  node_auth_plugins{{"Auth plugins<br/>authentication strategies<br/>[by_plugin.py]"}}
  node_keypair_auth["Key pair JWT<br/>auth strategy<br/>[keypair.py]"]
  node_workload_identity["Workload identity<br/>auth strategy"]
  node_network["Network layer<br/>REST transport<br/>[network.py]"]
  node_ocsp["OCSP and CRL validation<br/>certificate validation<br/>[ocsp_snowflake.py]"]
  node_http_stack["Vendored HTTP stack<br/>Requests/urllib3<br/>[sessions.py]"]
  node_telemetry["Telemetry<br/>observability<br/>[telemetry.py]"]
end

subgraph group_async["Async connector"]
  node_async_api["Async connection API<br/>async connector<br/>[_connection.py]"]
  node_async_transfer["Async file transfer<br/>async staging"]
end

subgraph group_data["Results and staging"]
  node_result_set["Result sets and batches<br/>result materialization<br/>[result_set.py]"]
  node_converter["Python converter<br/>wire type conversion<br/>[converter.py]"]
  node_nanoarrow["Nanoarrow iterator<br/>Cython/Arrow decoder"]
  node_file_transfer["File transfer agent<br/>staging orchestration"]
  node_storage_client["Storage clients<br/>cloud data plane<br/>[storage_client.py]"]
  node_s3_client["S3 storage client<br/>storage implementation"]
end

subgraph group_delivery["Build and native runtime"]
  node_packaging["PEP 517 packaging<br/>Python distribution<br/>[pyproject.toml]"]
  node_minicore["sf_mini_core binaries<br/>Rust native runtime"]
  node_wheel_ci["Cross-platform wheel CI<br/>build pipeline<br/>[build_docker.sh]"]
end

node_snowflake_service(("Snowflake service<br/>external control plane"))
node_cloud_storage(("Cloud storage<br/>external data plane"))

node_public_api -->|"creates"| node_connection
node_connection -->|"manages session"| node_session_manager
node_connection -->|"creates"| node_cursor
node_connection -->|"authenticates through"| node_auth_plugins
node_auth_plugins -->|"uses"| node_keypair_auth
node_auth_plugins -->|"uses"| node_workload_identity
node_connection -->|"uses"| node_network
node_network -->|"validates certificates"| node_ocsp
node_network -->|"sends via"| node_http_stack
node_network -->|"REST requests"| node_snowflake_service
node_cursor -->|"executes SQL"| node_network
node_cursor -->|"materializes responses"| node_result_set
node_result_set -->|"converts values"| node_converter
node_result_set -->|"Arrow decoding"| node_nanoarrow
node_cursor -->|"PUT/GET and bind upload"| node_file_transfer
node_file_transfer -->|"selects backend"| node_storage_client
node_storage_client -->|"implements"| node_s3_client
node_storage_client -->|"transfers files"| node_cloud_storage
node_connection -.->|"emits activity"| node_telemetry
node_async_api -->|"async REST flows"| node_snowflake_service
node_async_api -->|"staging operations"| node_async_transfer
node_async_transfer -->|"async transfers"| node_cloud_storage
node_packaging -->|"packages"| node_minicore
node_wheel_ci -->|"builds wheels"| node_packaging

click node_public_api "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/__init__.py"
click node_connection "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/connection.py"
click node_session_manager "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/session_manager.py"
click node_cursor "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/cursor.py"
click node_auth_plugins "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/auth/by_plugin.py"
click node_keypair_auth "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/auth/keypair.py"
click node_workload_identity "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/auth/workload_identity.py"
click node_network "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/network.py"
click node_ocsp "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/ocsp_snowflake.py"
click node_http_stack "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/vendored/requests/sessions.py"
click node_result_set "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/result_set.py"
click node_converter "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/converter.py"
click node_nanoarrow "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/nanoarrow_cpp/ArrowIterator/nanoarrow_arrow_iterator.pyx"
click node_file_transfer "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/file_transfer_agent.py"
click node_storage_client "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/storage_client.py"
click node_s3_client "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/s3_storage_client.py"
click node_telemetry "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/telemetry.py"
click node_async_api "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/aio/_connection.py"
click node_async_transfer "https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/aio/_file_transfer_agent.py"
click node_packaging "https://github.com/snowflakedb/snowflake-connector-python/blob/main/pyproject.toml"
click node_wheel_ci "https://github.com/snowflakedb/snowflake-connector-python/blob/main/ci/build_docker.sh"

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_session_manager,node_cursor,node_auth_plugins,node_keypair_auth,node_workload_identity,node_network,node_ocsp,node_http_stack,node_telemetry toneBlue
class node_async_api,node_async_transfer toneAmber
class node_result_set,node_converter,node_nanoarrow,node_file_transfer,node_storage_client,node_s3_client toneMint
class node_packaging,node_minicore,node_wheel_ci toneRose
class node_snowflake_service,node_cloud_storage toneNeutral
```

## Components

### Synchronous connector

- [DB-API public API](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/__init__.py): Python API · Synchronous connection entry points. · `src/snowflake/connector/__init__.py`
- [SnowflakeConnection](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/connection.py): connection lifecycle · Owns session state, authentication, HTTP operations, and cursors. · `src/snowflake/connector/connection.py`
- [Session manager](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/session_manager.py): session control · `src/snowflake/connector/session_manager.py`
- [Cursor](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/cursor.py): query control · Submits SQL and exposes fetch, status, and cancellation APIs. · `src/snowflake/connector/cursor.py`
- [Auth plugins](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/auth/by_plugin.py): authentication strategies · Credentials and login tokens for password, OAuth, key pair, and identity flows. · `src/snowflake/connector/auth/by_plugin.py`
- [Key pair JWT](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/auth/keypair.py): auth strategy · `src/snowflake/connector/auth/keypair.py`
- [Workload identity](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/auth/workload_identity.py): auth strategy · `src/snowflake/connector/auth/workload_identity.py`
- [Network layer](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/network.py): REST transport · Handles retries, proxies, redirects, TLS, and session renewal. · `src/snowflake/connector/network.py`
- [OCSP and CRL validation](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/ocsp_snowflake.py): certificate validation · `src/snowflake/connector/ocsp_snowflake.py`
- [Vendored HTTP stack](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/vendored/requests/sessions.py): Requests/urllib3 · `src/snowflake/connector/vendored/requests/sessions.py`
- [Telemetry](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/telemetry.py): observability · Emits separately controllable connector activity telemetry. · `src/snowflake/connector/telemetry.py`

### Async connector

- [Async connection API](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/aio/_connection.py): async connector · Independent async implementation mirroring core connector flows. · `src/snowflake/connector/aio/_connection.py`
- [Async file transfer](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/aio/_file_transfer_agent.py): async staging · `src/snowflake/connector/aio/_file_transfer_agent.py`

### Results and staging

- [Result sets and batches](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/result_set.py): result materialization · `src/snowflake/connector/result_set.py`
- [Python converter](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/converter.py): wire type conversion · Maps Snowflake values to Python types. · `src/snowflake/connector/converter.py`
- [Nanoarrow iterator](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/nanoarrow_cpp/ArrowIterator/nanoarrow_arrow_iterator.pyx): Cython/Arrow decoder · Performance-critical Arrow and Pandas result decoding. · `src/snowflake/connector/nanoarrow_cpp/ArrowIterator/nanoarrow_arrow_iterator.pyx`
- [File transfer agent](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/file_transfer_agent.py): staging orchestration · Coordinates PUT, GET, bind upload, compression, and encryption. · `src/snowflake/connector/file_transfer_agent.py`
- [Storage clients](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/storage_client.py): cloud data plane · Selects S3, Azure, GCS, or local storage implementations. · `src/snowflake/connector/storage_client.py`
- [S3 storage client](https://github.com/snowflakedb/snowflake-connector-python/blob/main/src/snowflake/connector/s3_storage_client.py): storage implementation · `src/snowflake/connector/s3_storage_client.py`

### Build and native runtime

- [PEP 517 packaging](https://github.com/snowflakedb/snowflake-connector-python/blob/main/pyproject.toml): Python distribution · `pyproject.toml`
- **sf_mini_core binaries**: Rust native runtime · Platform-specific native artifacts used by the driver.
- [Cross-platform wheel CI](https://github.com/snowflakedb/snowflake-connector-python/blob/main/ci/build_docker.sh): build pipeline · Builds Linux, macOS, and Windows wheels, including specialized environments. · `ci/build_docker.sh`

### Other components

- **Snowflake service**: external control plane
- **Cloud storage**: external data plane

## Connections

- DB-API public API → SnowflakeConnection: creates
- SnowflakeConnection → Session manager: manages session
- SnowflakeConnection → Cursor: creates
- SnowflakeConnection → Auth plugins: authenticates through
- Auth plugins → Key pair JWT: uses
- Auth plugins → Workload identity: uses
- SnowflakeConnection → Network layer: uses
- Network layer → OCSP and CRL validation: validates certificates
- Network layer → Vendored HTTP stack: sends via
- Network layer → Snowflake service: REST requests
- Cursor → Network layer: executes SQL
- Cursor → Result sets and batches: materializes responses
- Result sets and batches → Python converter: converts values
- Result sets and batches → Nanoarrow iterator: Arrow decoding
- Cursor → File transfer agent: PUT/GET and bind upload
- File transfer agent → Storage clients: selects backend
- Storage clients → S3 storage client: implements
- Storage clients → Cloud storage: transfers files
- SnowflakeConnection → Telemetry: emits activity
- Async connection API → Snowflake service: async REST flows
- Async connection API → Async file transfer: staging operations
- Async file transfer → Cloud storage: async transfers
- PEP 517 packaging → sf_mini_core binaries: packages
- Cross-platform wheel CI → PEP 517 packaging: builds wheels