snowflakedb/snowflake-connector-python

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.