pypi / snowflake-sqlalchemy
snowflake-sqlalchemy
What changed in snowflake-sqlalchemy 1 to 2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-25.
15 breaking5 security16 new APIs and options1 performance13 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initsnowflake-sqlalchemy 238 changes
Breaking changes 11
This connection parameter is now blocked from the URL query string.
The
/operator always performs true division, while//always compiles to FLOOR(left / right), including integer floor division.Structured-type JSON handling is enabled by default: reads deserialize JSON into native Python values, and writes serialize native values. Setting the flag to False restores raw JSON strings and emits a DeprecationWarning.
The dialect flag is removed, and passing it to create_engine() raises TypeError. Division operators now have fixed true-division and floor-division semantics.
The async dialect checks for greenlet when the engine is created and raises an ImportError with installation instructions if it is unavailable.
The legacy URL parameter opt-out is removed, and passing it to create_engine() raises TypeError; sensitive connection parameters must be passed via connect_args=.
Supported Python versions are now 3.11–3.14; Python 3.8, 3.9, and 3.10 are dropped because connector 5.x requires Python 3.11 or newer.
Connector 4.x is no longer supported; the dialect requires connector 5.x, which provides the async driver.
The environment variable is removed and has no effect; sensitive connection parameters must be passed via connect_args=.
SQLAlchemy 1.4 is no longer supported; the dialect requires SQLAlchemy>=2.0.44,<2.1 because SQLAlchemy 2.1 removed APIs used by the dialect.
This connection parameter is now blocked from the URL query string.
Security 1
ExternalStage paths, including sub-paths created with from_parent_stage, are safely escaped when quoting is required in compiled COPY INTO and staged-file SQL.
New APIs and options 15
The dialect implements SQLAlchemy's asyncio extension. Use create_async_engine() with the usual snowflake:// URL to obtain an AsyncEngine / AsyncSession for non-blocking database access.
CreateFileFormat gains a comment option for closer parity with Snowflake's CREATE FILE FORMAT.
CreateFileFormat gains an if_not_exists option for closer parity with Snowflake's CREATE FILE FORMAT.
The asdecimal parameter allows opting into float conversion of numeric results instead of Decimal; the default remains Decimal.
This opt-in dialect flag renders generic Uuid and Mapped[uuid.UUID] as native Snowflake UUID and supports uuid.UUID in semi-structured payloads; it is off by default because it changes existing column DDL.
The new custom command supports Snowflake multi-table INSERT ALL and INSERT FIRST statements, including conditional when/else_, OVERWRITE, and per-target column/value mapping.
create_engine supports the json_deserializer parameter, matching the built-in SQLAlchemy dialects.
create_engine supports the json_serializer parameter, matching the built-in SQLAlchemy dialects.
JSONFormatter supports the full Snowflake TYPE=JSON option set, including date, time, timestamp, binary, null, duplicate, and invalid-character handling options.
Snowflake custom types gain a python_type property for SQLAlchemy compatibility.
Opt-in snowflake_rely=True renders RELY on PRIMARY KEY, FOREIGN KEY, and UNIQUE constraints so the optimizer can trust them for query rewrites such as join elimination.
This environment variable enables strict host-name mode, which stops host-name domain inference and forwards connection parameters unvalidated.
SnowflakeTable accepts a row_access_policy parameter whose policy name may be a string, optionally fully qualified, or a snowflake.sqlalchemy.FQN.
Strict host-name mode stops inferring or appending domains and forwards connection parameters, including connection_name profiles, to the connector unvalidated; explicit stage endpoints are supported.
Bracket access with col["key"] and col[index] compiles to Snowflake's native accessor for VARIANT, OBJECT, ARRAY, and MAP columns, including nested chains.
Fixes and other changes 11
Account derivation now uses the Snowflake Connector's parse_account, fixing dashed org-style PrivateLink account parsing and matching the driver's handling of host notations.
Expression-level collation now renders the collation as a single-quoted Snowflake string literal instead of an invalid double-quoted identifier.
repr() now works when unloading into an ExternalStage or cloud location by using the target's secret-masking repr().
The dialect explicitly sets this connector option on new connections to pin its present default and silence the connector's FutureWarning; URL or connect_args values take precedence.
Hybrid table index reflection now handles filter_names=None and returns indexes for all Hybrid Tables in the schema; reflected names, result keys, and empty INCLUDE columns are also normalized for correct reflection.
Object-listing SHOW commands used for reflection now paginate, fixing reflection failures on schemas or databases with more than 10,000 objects.
A SELECT with OFFSET but no LIMIT now emits LIMIT NULL OFFSET ... instead of invalid LIMIT -1 SQL.
Backslash breakout in COPY FILE_FORMAT options is fixed.
Expired-session/token and closed-connection errors, including error code 390195, are detected as disconnects so connection_invalidated is set and pooled connections are recycled.
Column-type collation now renders the collation as a single-quoted Snowflake string literal instead of an invalid double-quoted identifier.
Passwords containing [, ], ?, or # are now encoded correctly so generated connection strings can be parsed.
snowflake-sqlalchemy 112 changes
Breaking changes 4
The
/operator always emits true division, regardless of the flag; the flag now gates a deprecation warning.Raises TypeError at DDL compile time for expression elements that are neither str nor TextClause, rather than silently coercing them to malformed DDL.
Account and region are validated against DNS-safe characters, and user values are percent-encoded before URL construction to prevent delimiter misinterpretation.
The listed connector kwargs can no longer be supplied via the URL query string; pass them via connect_args= in create_engine() instead.
Security 4
repr() masks cloud secrets as '***'; compiled SQL is unchanged.
Escapes single quotes and backslashes in view names before embedding them in SHOW VIEWS LIKE, so such views are found correctly and crafted names cannot manipulate the query.
Snowflake SQLAlchemy affected by SQL injection and local file disclosure vulnerabilities
An opt-in logging redactor is available for engine logs that contain inline credentials.
New APIs and options 1
Setting this environment variable to 1 provides a legacy URL-parameter behavior option if you encounter a possible behavioral change.
Performance 1
Reflecting one table no longer scans the entire schema, reducing latency and Snowflake credit usage for targeted Inspector calls.
Fixes and other changes 2
Caller-supplied identifiers in DDL are routed through the identifier preparer; quote=False labels are quoted when their characters require it.
Cloud-storage URIs, credentials, encryption clauses, file entries, and FILE_FORMAT option strings use dialect-standard escaping in compiled SQL.