Snowflake Connector for Python

There are three primary ways to establish an asynchronous connection to Snowflake. The Async context manager is the recommended pattern for ensuring connections are properly closed.

Pattern 1: Async context manager (Recommended)

async with connect(user='...', password='...', account='...') as conn:
   # Use connection
   pass

Pattern 2: Direct await

conn = await connect(user='...', password='...', account='...')
await conn.close()

Pattern 3: Manual

conn = SnowflakeConnection(user='...', password='...', account='...')
await conn.connect()
await conn.close()

# Pattern 1: Async context manager (recommended)
async with connect(user='...', password='...', account='...') as conn:
   # Use connection
   pass

To ensure authenticity and integrity, use cosign to verify the package signature.

1. Install cosign.
2. Download the package file (e.g., from PyPI).
3. Download the corresponding signature files from the specific release tag on GitHub.
4. Run cosign verify-blob using the package file, the public key, and the signature file.

# replace the version number with the version you are verifying
./cosign verify-blob snowflake_connector_python-3.12.2.tar.gz \
--key snowflake-connector-python-v3.12.2.pub \
--signature resources.linux.snowflake_connector_python-3.12.2.tar.gz.sig

By default, the connector collects telemetry data to improve the product. You can disable this collection using one of two methods:

1. During connection: Pass CLIENT_TELEMETRY_ENABLED set to False within the session_parameters dictionary in the snowflake.connector.connect() call.
2. After connection: Set the telemetry_enabled property of the SnowflakeConnection object to False.

# Method 1: Via session_parameters
import snowflake.connector
conn = snowflake.connector.connect(
    user='XXXX',
    password='XXXX',
    account='XXXX',
    session_parameters={
      "CLIENT_TELEMETRY_ENABLED": False,
    }
)

# Method 2: Via connection property
import snowflake.connector
conn = snowflake.connector.connect(
    user='XXXX',
    password='XXXX',
    account='XXXX',
)
conn.telemetry_enabled = False

You can use the provided Dockerized build script to compile the connector. The built wheel files will be found in dist/repaired_wheels. You can specify particular Python versions to compile by passing them as arguments to the script.

# Build using the Docker script
./ci/build_docker.sh

# Example: Build for specific Python versions
./ci/build_docker.sh "3.10 3.11"

Customers can use the provided requirements files to reproduce the exact environment used by Snowflake to run tests. These files can be installed using pip just like any standard requirements file.

python -m pip install -r requirements_37.reqs

To create a wheel package locally using PEP-517, ensure you have a supported Python version installed, then clone the repository and run the build commands. The resulting .whl file will be located in the ./dist directory.

git clone git@github.com:snowflakedb/snowflake-connector-python.git
cd snowflake-connector-python
python -m pip install -U pip setuptools wheel build
python -m build --wheel .

The snowflake.connector.aio module is a Preview feature provided for experimental purposes and is not intended for production environments. It is not supported by Snowflake Support.

To use the async version, you must install the aiohttp dependency in addition to the standard connector requirements.

To use the async API, import from the aio subpackage instead of the standard snowflake.connector package:

# Use the aio subpackage for async support
from snowflake.connector.aio import connect, SnowflakeConnection, DictCursor

The Snowflake Connector for Python uses several optional dependencies for specific features (e.g., pandas for dataframes, boto3 for AWS integration, keyring for SSO). If these dependencies are not installed, the connector provides placeholder objects that mimic the missing modules.

If you attempt to access an attribute or function on one of these placeholder objects, the connector will raise a snowflake.connector.errors.MissingDependencyError specifying which dependency is missing. This allows the library to remain lightweight while providing clear error messages when a user attempts to use a feature requiring an uninstalled package.

The Snowflake Python connector supports Workload Identity Federation (WIF) through several providers. When configuring your connection, you can specify one of the following AttestationProvider values:

• AWS: Uses the current workload's IAM role to build an encoded pre-signed GetCallerIdentity request or an outbound token.
• AZURE: Requests an OAuth access token for the workload's managed identity (supports AKS Workload Identity and Azure Functions).
• GCP: Requests an ID token for the workload's attached service account via the GCP metadata server.
• OIDC: Uses a provided OpenID Connect (OIDC) ID token.

If you are passing the provider as a string in a configuration object, it is case-insensitive.

The AuthByPlugin class is the abstract base class for all external authenticators. While end-users typically consume specific implementations (like AuthByKeyPair), understanding this interface is useful for troubleshooting how authentication lifecycle events occur.

Key lifecycle methods include:

• prepare(...): Used to reach out to 3rd-party services before authenticating with Snowflake.
• update_body(body): Modifies the authentication request body.
• reauthenticate(...): Re-performs authentication after secrets have been cleared from memory.
• reset_secrets(): Clears sensitive information from the authenticator instance.

Note on Timeouts: Authenticators can override the connection's socket_timeout by setting an internal _socket_timeout. This is common in JWT-based authentication (e.g., AuthByKeyPair) to ensure tokens are refreshed in time.

GCP Workload Identity can be used in two ways:

1. Direct: Uses the identity token of the attached service account.
2. Impersonation: Uses an impersonation_path (a list of service account email addresses) to generate an identity token for a target service account via the iamcredentials.googleapis.com API.

When using impersonation, the driver first fetches an access token for the current service account and then calls generateIdToken for the target account.

The connect function in snowflake.connector.aio returns a _AsyncConnectContextManager instance. This instance implements the HybridCoroutineContextManager protocol, which combines the full Coroutine protocol (PEP 492) with the Async Context Manager protocol (PEP 343).

This design ensures that:

1. Metadata Preservation: The connect function is decorated with @wraps(SnowflakeConnection.__init__), meaning it preserves the signature, documentation, and type information of the original connection class for IDE autocomplete and static type checkers.
2. Dual Compatibility: By implementing both __await__ and __aenter__/__aexit__, the same object can be used as either a coroutine or a context manager.
3. Lifecycle Safety: When used as a context manager, the __aenter__ method awaits the connection coroutine and then calls the connection's own __aenter__ method.