Install & Compatibility
Where this runs
tested against v4.3.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 7.3s · import 0.014s · 95MB
95MB installed
● package 95MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
schemachange
✓ import schemachange
✗ import subprocess
This quickstart demonstrates how to set up a basic `schemachange` project and run a deployment using Python's `subprocess` module to execute the `schemachange` CLI. It creates a dummy `migrations` folder and an initial SQL script, then attempts to deploy it to a Snowflake instance using credentials provided via environment variables. The `--create-change-history-table` flag is included to automatically create the change history table if it doesn't exist. Ensure your Snowflake account, user, password, role, warehouse, and database environment variables are correctly set for authentication.
import os
import subprocess
# Create a dummy migrations folder and script for demonstration
if not os.path.exists('migrations'):
os.makedirs('migrations')
with open('migrations/V1.0.0__initial_setup.sql', 'w') as f:
f.write("CREATE SCHEMA IF NOT EXISTS MY_APP;\n")
f.write("CREATE TABLE IF NOT EXISTS MY_APP.CUSTOMERS (ID INTEGER, NAME VARCHAR(100));")
# Set environment variables for Snowflake connection (replace with your actual details)
# For production, use secure methods like secrets management or connections.toml
# NOTE: For quickstart, ensure these are actual values or use a dummy Snowflake connection if possible
env = os.environ.copy()
env['SNOWFLAKE_ACCOUNT'] = os.environ.get('SNOWFLAKE_ACCOUNT', 'your_account_identifier')
env['SNOWFLAKE_USER'] = os.environ.get('SNOWFLAKE_USER', 'your_user')
env['SNOWFLAKE_PASSWORD'] = os.environ.get('SNOWFLAKE_PASSWORD', 'your_password')
env['SNOWFLAKE_ROLE'] = os.environ.get('SNOWFLAKE_ROLE', 'SYSADMIN')
env['SNOWFLAKE_WAREHOUSE'] = os.environ.get('SNOWFLAKE_WAREHOUSE', 'COMPUTE_WH')
env['SNOWFLAKE_DATABASE'] = os.environ.get('SNOWFLAKE_DATABASE', 'DEMO_DB')
env['SCHEMACHANGE_CHANGE_HISTORY_TABLE'] = os.environ.get('SCHEMACHANGE_CHANGE_HISTORY_TABLE', 'DEMO_DB.SCHEMACHANGE.CHANGE_HISTORY')
print("Running schemachange deploy...")
try:
result = subprocess.run(
[
"schemachange",
"deploy",
"-f", "./migrations",
"--create-change-history-table",
"--verbose"
],
env=env, # Pass environment variables to the subprocess
check=True, # Raise an exception for non-zero exit codes
capture_output=True, # Capture stdout and stderr
text=True # Decode stdout/stderr as text
)
print("Schemachange deployment successful.")
print("STDOUT:", result.stdout)
if result.stderr:
print("STDERR:", result.stderr)
except subprocess.CalledProcessError as e:
print(f"Schemachange deployment failed with error: {e}")
print("STDOUT:", e.stdout)
print("STDERR:", e.stderr)
except FileNotFoundError:
print("Error: 'schemachange' command not found. Is schemachange installed and in your PATH?")
schemachange --version
Debug
Known issues
breakingChecksum drift for scripts ending with a semicolon when upgrading from v4.3.0/v4.3.1 to v4.3.2. A regression in v4.3.0 accidentally removed trailing semicolon stripping, causing checksum mismatches.fixUpgrade directly to v4.3.2. If coming from 4.3.0/4.3.1, expect a one-time 'checksum has drifted' warning for affected V-scripts or potential re-execution for R-scripts.
affects: 4.3.0, 4.3.1
breakingMinimum `snowflake-connector-python` version was bumped to `>=3.0.0` in v4.3.0, dropping support for `snowflake-connector-python` 2.x.fixEnsure `snowflake-connector-python` is updated to a version 3.x or higher before upgrading to schemachange v4.3.0 or later.
affects: <4.3.0
gotchaSchemachange, by default, will not create the change history table and will fail if it doesn't exist. It also won't create the database for this table.fixEither manually create the `METADATA.SCHEMACHANGE.CHANGE_HISTORY` table (or your configured table) in Snowflake, or run `schemachange deploy` with the `--create-change-history-table` flag, or set `create-change-history-table: true` in your `schemachange-config.yml`. Ensure the database for the history table already exists.
affects: All versions
gotchaNew CLI authentication parameters (`--snowflake-authenticator`, `--snowflake-private-key-file`, `--snowflake-token-file-path`) were added in v4.1.0, but `--snowflake-private-key-file-pwd` (passphrase) is *intentionally not supported* via CLI for security reasons.fixFor sensitive credentials like private key passphrases, use environment variables (e.g., `SNOWFLAKE_PRIVATE_KEY_PASSPHRASE`) or define them in a `connections.toml` file to avoid exposure in process lists or shell history. Generic `SNOWFLAKE_*` environment variables are also passed through.
affects: 4.1.0 and later
gotchaOut-of-Order Execution, introduced in v4.3.0, changes how versioned scripts are applied. If enabled, scripts can be applied even if their version is older than the maximum applied version.fixUnderstand the implications of `--out-of-order` (or `SCHEMACHANGE_OUT_OF_ORDER=true` / `out-of-order: true` in config) for your deployment strategy, especially in parallel development workflows. It is recommended to use timestamp-based versioning to minimize collisions.
affects: 4.3.0 and later
deprecatedThe `--verbose` flag for command-line output was deprecated.fixWhile still functional, consider using alternative logging configurations if precise control over verbosity is needed.
affects: 4.1.0 and later
deprecatedParameters `private_key_path` and `private_key_passphrase` are slated for removal in the upcoming v5.0.0 major release.fixPlan to migrate to the newer `--snowflake-private-key-file` and environment variables for passphrases (`SNOWFLAKE_PRIVATE_KEY_PASSPHRASE`) or `connections.toml` configurations.
affects: All versions (deprecation warning in 4.x, removal in 5.0)
Upgrade
Version history
4.3.3latest on PyPI · released Apr 20, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or higher.
snowflake-connector-pythonrequiredCore dependency for connecting to Snowflake. Minimum version was bumped to 3.0.0 in schemachange v4.3.0.
structlogrequiredAdded in v4.0.0 for standard log outputs.
coloramarequiredFixed a missing dependency on Windows in v4.2.0.