snowflake Adapter¶

from sqlspec.adapters.snowflake import (
    SnowflakeConfig,
    SnowflakeConnectionParams,
    SnowflakeConnectionPool,
    SnowflakeDriver,
    SnowflakeDriverFeatures,
    SnowflakeExceptionHandler,
    SnowflakePoolParams,
    SnowflakeSessionAttributeStrategy,
    SnowflakeSyncDataDictionary,
    SnowflakeSyncMigrationTracker,
)

Synchronous Snowflake adapter built on snowflake-connector-python, with bounded pooling, native Arrow batches, and Parquet stage loads. Scripts use SQLSpec's Snowflake splitter and a managed cursor per statement. Transaction checks use server CURRENT_TRANSACTION(); aware datetime binds preserve timezone offsets in server binding modes. Inherited query and transaction methods are documented on SyncDriverAdapterBase. See the Snowflake setup guide and Snowflake catalog reference.

Configuration and Parameters¶

SnowflakeConfig ¶

Bases: SyncDatabaseConfig[SnowflakeConnection, SnowflakeConnectionPool, SnowflakeDriver]

Configure Snowflake sessions, authentication, and bounded pooling.

`SnowflakeConnectionParams` ¶

Bases: TypedDict

Connection options forwarded to the Snowflake Python connector.

Attributes:

Name	Type	Description
`account`	`NotRequired[str]`	Snowflake account identifier, including organization when needed.
`user`	`NotRequired[str]`	Snowflake login user name.
`username`	`NotRequired[str]`	Alias for `user` when the canonical key is absent.
`password`	`NotRequired[str]`	Password for password-based authentication.
`host`	`NotRequired[str]`	Explicit Snowflake endpoint host name.
`port`	`NotRequired[int]`	Endpoint port, normally `443`.
`protocol`	`NotRequired[str]`	Endpoint transport protocol.
`warehouse`	`NotRequired[str]`	Warehouse selected for the connection.
`database`	`NotRequired[str]`	Database selected for the connection.
`schema`	`NotRequired[str]`	Schema selected for the connection.
`role`	`NotRequired[str]`	Role selected for the connection.
`auth_type`	`NotRequired[str]`	Authentication shorthand such as `jwt`, `pat`, `workload_identity`, or `oauth`.
`authenticator`	`NotRequired[str]`	Connector authenticator name or HTTPS Okta endpoint.
`token`	`NotRequired[str]`	Access token for token-based authentication.
`token_file_path`	`NotRequired[str \| Path]`	Path containing a workload identity token.
`auth_token_provider`	`NotRequired[Callable[[], str]]`	Callback producing a fresh credential for each physical connection.
`private_key`	`NotRequired[Any]`	PKCS#8 DER bytes, PEM text, key path, or a private key object.
`private_key_file`	`NotRequired[str \| Path]`	Path to an optionally encrypted private key file.
`private_key_passphrase`	`NotRequired[str \| bytes]`	Passphrase decrypting an in-memory PEM key or private key file.
`private_key_file_pwd`	`NotRequired[str \| bytes]`	Connector passphrase for an encrypted private key file.
`workload_identity_provider`	`NotRequired[str]`	Cloud identity provider used for workload identity authentication.
`workload_identity_entra_resource`	`NotRequired[str]`	Microsoft Entra resource requested during Azure token exchange.
`workload_identity_impersonation_path`	`NotRequired[str \| Sequence[str]]`	Ordered identity impersonation chain.
`connection_name`	`NotRequired[str]`	Named profile loaded from the connector connections file.
`connections_file_path`	`NotRequired[str \| Path]`	Custom path to the connector TOML connections file.
`paramstyle`	`NotRequired[Literal['qmark', 'numeric', 'pyformat', 'format']]`	Connector parameter binding mode; defaults to `qmark`.
`autocommit`	`NotRequired[bool]`	Whether Snowflake commits statements automatically.
`timezone`	`NotRequired[str]`	Initial session time zone, unless supplied in `session_parameters`.
`query_tag`	`NotRequired[str]`	Initial `QUERY_TAG`, unless supplied in `session_parameters`.
`session_parameters`	`NotRequired[Mapping[str, Any]]`	Session settings applied together when connecting.
`login_timeout`	`NotRequired[int \| float]`	Maximum login duration in seconds.
`network_timeout`	`NotRequired[int \| float]`	Maximum network retry duration in seconds.
`socket_timeout`	`NotRequired[int \| float]`	Socket timeout in seconds.
`application`	`NotRequired[str]`	Application identifier recorded by Snowflake.
`client_session_keep_alive`	`NotRequired[bool]`	Keep the session alive while the connection is idle.
`ocsp_fail_open`	`NotRequired[bool]`	Allow connections when certificate revocation checks are unavailable.
`insecure_mode`	`NotRequired[bool]`	Disable connector certificate revocation checks.
`validate_default_parameters`	`NotRequired[bool]`	Validate database, schema, and warehouse names when connecting.
`extra`	`NotRequired[Mapping[str, Any]]`	Additional connector options, with explicit modeled options taking precedence.

`SnowflakePoolParams` ¶

Bases: SnowflakeConnectionParams

Snowflake connection options and bounded pool settings.

Attributes:

Name	Type	Description
`pool_min_size`	`NotRequired[int]`	Number of physical sessions opened when constructing the pool; defaults to `0`.
`pool_max_size`	`NotRequired[int]`	Maximum number of simultaneously owned sessions; defaults to `5`.
`pool_timeout`	`NotRequired[float]`	Maximum seconds waiting for an available pool slot; defaults to `30`.
`pool_recycle_seconds`	`NotRequired[int]`	Maximum connection lifetime in seconds; `0` disables recycling.
`health_check_interval`	`NotRequired[float]`	Idle seconds between connection health checks; defaults to `60`.

`SnowflakeDriverFeatures` ¶

Bases: TypedDict

Snowflake codec, bulk transfer, and event settings.

Attributes:

Name	Type	Description
`json_serializer`	`NotRequired[Callable[[Any], str]]`	Serialize structured parameters to JSON text.
`json_deserializer`	`NotRequired[Callable[[str], Any]]`	Decode Snowflake semi-structured result values.
`on_connection_create`	`NotRequired[Callable[[SnowflakeConnection], None]]`	Callback invoked for each newly opened physical connection.
`enable_lowercase_column_names`	`NotRequired[bool]`	Lowercase implicitly uppercase result names while preserving mixed-case aliases.
`enable_stage_parquet_load`	`NotRequired[bool]`	Enable temporary-stage Parquet uploads for large Arrow loads.
`stage_parquet_threshold_rows`	`NotRequired[int]`	Minimum row count selecting stage-based loads; defaults to `1000`.
`enable_json_deserialization`	`NotRequired[bool]`	Decode VARIANT, OBJECT, and ARRAY result values with `json_deserializer`; defaults to `True`.
`enable_query_tag_correlation`	`NotRequired[bool]`	Attach statement correlation information to Snowflake query tags.
`enable_events`	`NotRequired[bool]`	Enable SQLSpec table-backed event channels.
`events_backend`	`NotRequired[Literal['poll_queue']]`	Event backend used for Snowflake table queues (`'poll_queue'`).
`tenant_strategy`	`NotRequired[SyncTenantStrategy \| TenantStrategyShorthand \| None]`	Opt-in tenant strategy, or the `"session_attributes"` shorthand, applied to every session and connection lease.

Driver, Pool, and Data Dictionary¶

SnowflakeDriver ¶

Bases: SyncDriverAdapterBase

Execute Snowflake SQL with explicit transactions and zero-pandas Arrow I/O.

execute_async_query ¶

execute_async_query(statement, /, *parameters, statement_config=None, **kwargs)

Submit a warehouse job and return its query identifier.

fetch_async_query_result ¶

fetch_async_query_result(query_id, *, statement_config=None)

Wait for a submitted job and materialize its result.

The result reports the submitted statement when this driver submitted the job, and otherwise the equivalent RESULT_SCAN query for query_id.

SnowflakeExceptionHandler ¶

Bases: BaseSyncExceptionHandler

Capture mapped connector exceptions outside compiled context-manager frames.

SnowflakeConnectionPool ¶

Own bounded exclusive sessions and reuse healthy handles between leases.

SnowflakeSyncDataDictionary ¶

Bases: SyncDataDictionaryBase

Reflect tables, typed columns, SHOW keys and native GET_DDL definitions.

SnowflakeSyncMigrationTracker ¶

Bases: SyncMigrationTracker

Track migrations with Snowflake types and explicit lowercase result aliases.

Tenant Strategies¶

Set driver_features={"tenant_strategy": "rls"}; "session_attributes", "default", and True select the same strategy. The strategy writes the tenant identity into an immutable session attribute that row access policies read with SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', 'tenant_id'). Pass tenant_attribute= and variable_keys= to an explicit strategy to use other attribute names. Names are validated as identifiers and keep their case, because Snowflake attribute names are case-sensitive; values are always bound.

Checkout requires the owned attributes to be unset, binds each one with CALL SET_SYS_CONTEXT, and reads them back before the session is used. Snowflake cannot overwrite or clear an immutable attribute, so each lease opens one standalone connection and closes it on release, verifying that it closed; tenant sessions never return to the pool. Sessions roll back unfinished work before release, as they do without a tenant strategy. Standalone create_connection() is rejected in tenant mode.

Missing tenant identity raises TenantContextError before acquisition. Failed cleanup raises TenantCleanupError when no body exception is pending; otherwise the body error keeps its identity and receives a cleanup note. See Multi-Tenancy and Tenant Operations.

SnowflakeSessionAttributeStrategy ¶

Set and verify immutable Snowflake session attributes on a fresh connection.

Row access policies read the values with SYS_CONTEXT('SNOWFLAKE$SESSION_ATTRIBUTES', '<name>'). Snowflake cannot overwrite or clear an immutable attribute, so the session is never reused: the tenant lease opens one connection per lease and closes it on release.

init ¶

__init__(
    *, tenant_attribute=DEFAULT_SNOWFLAKE_TENANT_ATTRIBUTE, variable_keys=None
)

Configure the owned session attributes.

Parameters:

Name	Type	Description	Default
`tenant_attribute`	`object`	Session attribute receiving the tenant identity.	`DEFAULT_SNOWFLAKE_TENANT_ATTRIBUTE`
`variable_keys`	`Mapping[str, str] \| None`	Payload variable names mapped to session attribute names.	`None`

Raises:

Type	Description
`ImproperConfigurationError`	A name is invalid or two keys target the same attribute.

checkout ¶

checkout(connection, payload)

Require unset attributes, bind the payload, and verify the session values.

Raises:

Type	Description
`TenantContextError`	The session already carries an owned attribute, or binding or verification failed.

checkin ¶

checkin(connection, state)

Leave the immutable attributes in place; the lease closes the session instead.

Extension Stores¶

SnowflakeStore ¶

Bases: BaseSQLSpecStore[SnowflakeConfig]

Persist session bytes in Snowflake BINARY columns.

SnowflakeEventQueueStore ¶

Bases: BaseEventQueueStore[SnowflakeConfig]

Store queue payloads in VARIANT without secondary indexes.

SnowflakeADKStore ¶

Bases: BaseSyncADKStore[SnowflakeConfig]

Store ADK sessions and events in Snowflake VARIANT columns.

SnowflakeADKMemoryStore ¶

Bases: BaseSyncADKMemoryStore[SnowflakeConfig]

Store ADK memories with event deduplication and ILIKE text recall.

snowflake Adapter¶

Configuration and Parameters¶

SnowflakeConfig ¶

SnowflakeConnectionParams ¶

SnowflakePoolParams ¶

SnowflakeDriverFeatures ¶

Driver, Pool, and Data Dictionary¶

SnowflakeDriver ¶

execute_async_query ¶

fetch_async_query_result ¶

SnowflakeExceptionHandler ¶

SnowflakeConnectionPool ¶

SnowflakeSyncDataDictionary ¶

SnowflakeSyncMigrationTracker ¶

Tenant Strategies¶

SnowflakeSessionAttributeStrategy ¶

__init__ ¶

checkout ¶

checkin ¶

Extension Stores¶

SnowflakeStore ¶

SnowflakeEventQueueStore ¶

SnowflakeADKStore ¶

SnowflakeADKMemoryStore ¶

`SnowflakeConnectionParams` ¶

`SnowflakePoolParams` ¶

`SnowflakeDriverFeatures` ¶

init ¶