### Example: Documenting Strategic Decisions

Source: https://github.com/snowflake-labs/schemachange/blob/master/experiments/README.md

Shows an example of using the experiments/ folder to document strategic decisions, focusing on explaining the 'why' behind choices for future reference.

```bash
# Document "why" for future:
experiments/
└── CONFIGURATION_STRATEGY.md  ← Explains why we do things this way
```

--------------------------------

### Setup Release Milestones Script

Source: https://github.com/snowflake-labs/schemachange/blob/master/docs/maintainers/scripts/README.md

This script automates the one-time setup of release milestones for the schemachange project. It requires the GitHub CLI to be installed and authenticated. The script creates milestones with specified versions, due dates, and descriptions, and will skip creation if a milestone already exists.

```bash
cd /path/to/schemachange
./docs/maintainers/scripts/setup-milestones.sh
```

--------------------------------

### Provision test environment

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Initializes the Snowflake environment by running setup SQL scripts.

```bash
# Run these in Snowflake (via Snowflake CLI, Snowsight, or any SQL client)
# 1. Creates database, warehouse, and roles
cd provision
snow sql -f initialize.sql

# 2. Creates the SCHEMACHANGE schema for tracking
snow sql -f setup_schemachange_schema.sql
```

--------------------------------

### Install Schemachange

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Install the Schemachange tool using pip.

```bash
pip install schemachange
```

--------------------------------

### CLI Configuration Override Example

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Demonstrates how CLI arguments take precedence over environment variables and configuration files.

```bash
# connections.toml has: user = "toml_user"
# YAML has: snowflake-user: yaml_user
export SNOWFLAKE_USER=env_user
schemachange deploy -C dev --snowflake-user cli_user

# Result: Connects as "cli_user" (CLI wins all)
```

--------------------------------

### Example of Files Acceptable to Commit

Source: https://github.com/snowflake-labs/schemachange/blob/master/experiments/README.md

Shows examples of files that provide lasting value and may be committed from the experiments folder, such as consolidated release notes and test coverage references.

```bash
experiments/
├── COMPREHENSIVE_4.2.0_RELEASE_NOTES.md  # Consolidated, timeless
├── TEST_COVERAGE_REFERENCE.md            # Lasting value for regression protection
└── README.md                             # This guide
```

--------------------------------

### Valid Version String Examples

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Provides examples of acceptable version string formats for versioned change scripts. Consistency in the chosen format is key.

```plaintext
1.1
1_1
1.2.3
1_2_3
```

--------------------------------

### Example: Release Preparation Workflow

Source: https://github.com/snowflake-labs/schemachange/blob/master/experiments/README.md

Illustrates the typical workflow for preparing release notes within the experiments/ folder, showing the transition from multiple iteration files to a single consolidated document for potential commit.

```bash
# During development (local only):
experiments/
  ├── issue_388_investigation.md
  ├── issue_388_v2.md
  ├── issue_388_final_fix.md
  ├── test_coverage_notes.md
└── my_analysis.md

# Before release (consolidate, then commit):
experiments/
└── COMPREHENSIVE_4.2.0_RELEASE_NOTES.md  ← Commit this
```

--------------------------------

### Versioned Migration Script Example

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Example of a versioned migration script (V) for creating tables. Follows the naming convention V<version>__<description>.sql.

```sql
-- File: V1.0.0__create_customers_table.sql
-- Naming convention: V<version>__<description>.sql

CREATE SCHEMA IF NOT EXISTS my_app;

CREATE TABLE IF NOT EXISTS my_app.customers (
    id INTEGER AUTOINCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(255) UNIQUE,
    created_at TIMESTAMP_LTZ DEFAULT CURRENT_TIMESTAMP()
);

CREATE TABLE IF NOT EXISTS my_app.orders (
    id INTEGER AUTOINCREMENT PRIMARY KEY,
    customer_id INTEGER REFERENCES my_app.customers(id),
    total_amount DECIMAL(10,2),
    order_date DATE DEFAULT CURRENT_DATE()
);
```

--------------------------------

### Example: Test Coverage Reference

Source: https://github.com/snowflake-labs/schemachange/blob/master/experiments/README.md

Demonstrates how to use the experiments/ folder to document test coverage, emphasizing the creation of a file with lasting value to prevent future regressions.

```bash
# Document what tests protect (lasting value):
experiments/
└── TEST_COVERAGE_REFERENCE.md  ← Helps prevent regressions
```

--------------------------------

### Private Key Authentication Setup

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Commands to generate RSA key pairs and configure Snowflake for JWT-based authentication.

```bash
# Generate encrypted private key
openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 aes256 -inform PEM -out snowflake_key.p8

# Extract public key
openssl rsa -in snowflake_key.p8 -pubout -out snowflake_key.pub

# Store private key securely
mkdir -p ~/.ssh
mv snowflake_key.p8 ~/.ssh/
chmod 600 ~/.ssh/snowflake_key.p8
```

```sql
-- In Snowflake: Assign public key to user
ALTER USER deploy_service SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
```

```bash
# Deploy using JWT authentication
export SNOWFLAKE_AUTHENTICATOR="snowflake_jwt"
export SNOWFLAKE_PRIVATE_KEY_FILE="~/.ssh/snowflake_key.p8"
export SNOWFLAKE_PRIVATE_KEY_FILE_PWD="your_passphrase"

schemachange deploy -f ./migrations
```

--------------------------------

### Example connections.toml file

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Defines connection profiles for development and production environments, including authentication details and session parameters.

```toml
# Development environment
[dev]
account = "myorg-dev"
user = "developer"
role = "DEV_ROLE"
warehouse = "DEV_WH"
database = "DEV_DB"

# Production environment (using JWT authentication)
[prod]
account = "myorg-prod"
user = "deploy_service"
authenticator = "snowflake_jwt"
private_key_file = "~/.ssh/snowflake_prod.p8"  # Recommended parameter name (matches Snowflake connector)
private_key_file_pwd = "my_secure_passphrase"   # Recommended parameter name (matches Snowflake connector)
role = "DEPLOY_ROLE"
warehouse = "PROD_WH"
database = "PROD_DB"

# NOTE: private_key_path is deprecated but still supported for backwards compatibility
# Please migrate to private_key_file to match Snowflake Python Connector naming

# Optional: Set session parameters for this connection
[prod.parameters]
QUERY_TAG = "my_app_prod"
QUOTED_IDENTIFIERS_IGNORE_CASE = false
```

--------------------------------

### Handle Unknown YAML Configuration Keys

Source: https://github.com/snowflake-labs/schemachange/blob/master/TROUBLESHOOTING.md

Example of a YAML configuration file containing both valid and ignored keys.

```yaml
# This YAML has unknown keys but will work in 4.2.0+
schemachange:
  root-folder: ./migrations
  my-custom-metadata: "for my CI tool"  # Unknown, but ignored

snowflake:
  account: myaccount
  warehose: MY_WH  # Typo! Will be ignored (and you'll see a warning)
  warehouse: MY_WH  # Correct - this will be used
```

--------------------------------

### Verify Filename Patterns

Source: https://github.com/snowflake-labs/schemachange/blob/master/TROUBLESHOOTING.md

Examples of correct and incorrect filename formatting for migration scripts.

```text
✅ V1.0.0__create_table.SQL     (correct)
❌ V1.0.0_create_table.SQL      (wrong - only 1 underscore)
❌ V1.0.0___create_table.SQL    (wrong - 3 underscores)
```

--------------------------------

### Connections TOML Configuration

Source: https://github.com/snowflake-labs/schemachange/blob/master/SECURITY.md

Example of a secure connections.toml file structure.

```toml
# ~/.snowflake/connections.toml (chmod 600)
[production]
account = "myaccount.us-east-1"
user = "service_account"
authenticator = "snowflake_jwt"
private_key_file = "~/.ssh/snowflake_key.p8"
# private_key_file_pwd = "passphrase"  # Only if key is encrypted
role = "DEPLOYMENT_ROLE"
warehouse = "DEPLOYMENT_WH"
```

--------------------------------

### Schema Change Project Folder Structure Example

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Illustrates the flexible directory layout for organizing SQL and CLI migration scripts within the project root. Subfolders can be nested arbitrarily.

```tree
(project_root)
| 
|-- folder_1
    |-- V1.1.1__first_change.sql
    |-- V1.1.2__second_change.sql
    |-- V1.1.3__deploy_dbt_project.cli.yml
    |-- R__sp_add_sales.sql
    |-- R__fn_get_timezone.sql
|-- folder_2
    |-- folder_3
        |-- V1.1.4__third_change.sql
        |-- R__fn_sort_ascii.sql
        |-- A__run_cleanup.cli.yml
```

--------------------------------

### Create Custom Milestone Status Script

Source: https://github.com/snowflake-labs/schemachange/blob/master/docs/maintainers/scripts/README.md

An example script to view the status of a specific release milestone using the GitHub CLI. Ensure the GitHub CLI is installed and authenticated. This script can be extended for other maintenance tasks.

```bash
# Example: milestone-status.sh
#!/bin/bash
echo "📊 Current Release Status"
gh milestone view "4.2.0"
```

--------------------------------

### Execute Milestone Setup Script

Source: https://github.com/snowflake-labs/schemachange/blob/master/docs/maintainers/GITHUB_MANAGEMENT_WITHOUT_PROJECTS.md

Runs the maintenance script to verify the current status of project milestones.

```bash
docs/maintainers/scripts/setup-milestones.sh
```

--------------------------------

### Create an Always Migration Script

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Use the A__ prefix for scripts that execute on every run, ideal for environment setup and role permissions.

```sql
-- File: A__grant_permissions.sql
-- Naming convention: A__<description>.sql
-- Runs every time

USE ROLE ACCOUNTADMIN;

-- Grant usage on warehouse
GRANT USAGE ON WAREHOUSE COMPUTE_WH TO ROLE DATA_ANALYST;

-- Grant read access to analytics schema
GRANT USAGE ON DATABASE ANALYTICS_DB TO ROLE DATA_ANALYST;
GRANT USAGE ON SCHEMA ANALYTICS_DB.PUBLIC TO ROLE DATA_ANALYST;
GRANT SELECT ON ALL TABLES IN SCHEMA ANALYTICS_DB.PUBLIC TO ROLE DATA_ANALYST;
GRANT SELECT ON FUTURE TABLES IN SCHEMA ANALYTICS_DB.PUBLIC TO ROLE DATA_ANALYST;
```

--------------------------------

### Execute schemachange via CLI

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Run the schemachange script directly or via the installed deploy command.

```bash
python schemachange/cli.py [-h] [--config-folder CONFIG_FOLDER] [-f ROOT_FOLDER] [-c CHANGE_HISTORY_TABLE] [-V VARS] [--create-change-history-table] [-ac] [-L LOG_LEVEL] [--dry-run] [-Q QUERY_TAG] [--connections-file-path CONNECTIONS_FILE_PATH] [-C CONNECTION_NAME]
```

```bash
schemachange deploy [-h] [--config-folder CONFIG_FOLDER] [-f ROOT_FOLDER] [-c CHANGE_HISTORY_TABLE] [-V VARS] [--create-change-history-table] [-ac] [-L LOG_LEVEL] [--dry-run] [-Q QUERY_TAG] [--connections-file-path CONNECTIONS_FILE_PATH] [-C CONNECTION_NAME]
```

--------------------------------

### User Help Workflow

Source: https://github.com/snowflake-labs/schemachange/blob/master/docs/maintainers/REPOSITORY_ECOSYSTEM.md

This flowchart outlines the recommended steps for users seeking help with schemachange, starting from self-service options to community support and issue creation.

```text
User needs help
    ↓
[Try schemachange verify command]
    ↓
[Search Discussions Q&A]
    ↓
[Check TROUBLESHOOTING.md]
    ↓
[Ask in Q&A Discussion]
    ↓
[If bug: Create Issue]
```

--------------------------------

### Embed Project in Markdown

Source: https://github.com/snowflake-labs/schemachange/blob/master/docs/maintainers/PROJECT_SETUP.md

Example of how to link a public project board within a GitHub discussion or README.

```markdown
## 📊 Visual Roadmap

See all planned work organized by release:

https://github.com/orgs/Snowflake-Labs/projects/X

### Quick Links to Views:
- [📍 Current Release](link) - What's in progress now
- [🔜 Next Release](link) - What's coming next
- [🗺️ Roadmap Board](link) - All releases at a glance
- [🤝 Community PRs](link) - Community contributions
```

--------------------------------

### Example session parameters in connections.toml

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Configures session-level parameters for a specific connection, such as query tags and timestamp formats.

```toml
[my_connection.parameters]
QUERY_TAG = "my_app"
TIMESTAMP_OUTPUT_FORMAT = "YYYY-MM-DD HH24:MI:SS"
```

--------------------------------

### Password and MFA Authentication

Source: https://github.com/snowflake-labs/schemachange/blob/master/SECURITY.md

Example of password-based authentication which requires manual MFA input.

```bash
# ⚠️ Works for human users but requires MFA prompts (not suitable for automation)
export SNOWFLAKE_PASSWORD="my_login_password"
schemachange deploy  # Will prompt for MFA (blocks automation)
```

--------------------------------

### Insecure YAML Configuration

Source: https://github.com/snowflake-labs/schemachange/blob/master/SECURITY.md

Example of an insecure configuration file that exposes credentials.

```yaml
# BAD - Never store passwords in YAML!
config-version: 2

snowflake:
  account: myaccount.us-east-1
  user: my_user
  password: "my_secret_password"  # ❌ INSECURE!
```

--------------------------------

### Example of QUERY_TAG merging across sources

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Demonstrates how QUERY_TAG values are appended with semicolons from different configuration sources, including connections.toml, environment variables, and CLI arguments.

```bash
# connections.toml has QUERY_TAG = "my_app"
export SNOWFLAKE_SESSION_PARAMETERS='{"QUERY_TAG": "ci_pipeline"}'
schemachange deploy -C prod --query-tag "release-v2.0"
```

--------------------------------

### Example of Files to NOT Commit

Source: https://github.com/snowflake-labs/schemachange/blob/master/experiments/README.md

Illustrates a typical structure of files that should remain local within the experiments folder, including analysis drafts, temporary scripts, and personal notes.

```bash
experiments/
├── issue_388_analysis_v1.md
├── issue_388_analysis_v2.md
├── issue_388_final.md
├── PASSPHRASE_FIX_2025-11-15.md
├── TODO_review.md
└── my_local_test.sh
```

--------------------------------

### Run deployment demos

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Executes deployment commands for different demo configurations using either connection files or environment variables.

```bash
# If using connections.toml:
schemachange deploy -C demo --config-folder ./demo/basics_demo

# If using environment variables:
schemachange deploy --config-folder ./demo/basics_demo
```

```bash
schemachange deploy --config-folder ./demo/basics_demo
```

```bash
schemachange deploy --config-folder ./demo/citibike_demo
```

```bash
schemachange deploy --config-folder ./demo/citibike_demo_jinja
```

--------------------------------

### Deploy using current best practice arguments

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Execute deployment using the recommended prefixed CLI arguments introduced in 4.1.0.

```bash
# CLI with new prefixed arguments
schemachange deploy \
  --config-folder ./demo/basics_demo \
  --schemachange-config-vars '{"env": "prod"}' \
  --schemachange-log-level INFO \
  --snowflake-account "myaccount" \
  --snowflake-user "deploy_user" \
  --snowflake-password "${SNOWFLAKE_PASSWORD}" \
  --snowflake-role "DEPLOY_ROLE" \
  --snowflake-warehouse "DEPLOY_WH" \
  --snowflake-database "PROD_DB"
```

--------------------------------

### Install SchemaChange v4.3.2

Source: https://github.com/snowflake-labs/schemachange/blob/master/TROUBLESHOOTING.md

Use this bash command to install or upgrade SchemaChange to version 4.3.2, which resolves checksum drift issues.

```bash
pip install schemachange==4.3.2
```

--------------------------------

### Deploy using connections.toml

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Execute deployment using a pre-configured connection profile.

```bash
# Passphrase must be in ENV (not in connections.toml for security)
export SNOWFLAKE_PRIVATE_KEY_FILE_PWD="your_passphrase"
schemachange deploy -C demo_jwt --config-folder ./demo/basics_demo
```

--------------------------------

### Configure Local Development with connections.toml

Source: https://github.com/snowflake-labs/schemachange/blob/master/SECURITY.md

Use a connections.toml file with a PAT token for local development to avoid MFA prompts and keep credentials out of version control.

```bash
# Use connections.toml with PAT token
cat > ~/.snowflake/connections.toml << EOF
[dev]
account = "dev-account.us-east-1"
user = "dev_user"
password = "<your_pat_token>"  # PAT token, NOT your login password
role = "DEVELOPER"
warehouse = "DEV_WH"
EOF

chmod 600 ~/.snowflake/connections.toml

# Deploy using connection profile
schemachange deploy -C dev
```

--------------------------------

### Demonstrate configuration priority

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Illustrates how CLI arguments override environment variables, which in turn override connections.toml settings.

```bash
# connections.toml
[prod]
database = "PROD_DB"
warehouse = "SMALL_WH"

# ENV variable overrides connections.toml
export SNOWFLAKE_WAREHOUSE="LARGE_WH"

# CLI overrides both ENV and connections.toml
schemachange deploy \
  -C prod \
  --snowflake-database "TEST_DB"

# Result: database=TEST_DB, warehouse=LARGE_WH
```

--------------------------------

### Deploy using CLI arguments

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Useful for quick tests, providing configuration directly via command-line flags.

```bash
# Password must be set as environment variable
export SNOWFLAKE_PASSWORD="your_password_or_pat"

schemachange deploy \
  -f migrations \
  -a myaccount.us-east-1.aws \
  -u my_user \
  -r MY_ROLE \
  -w MY_WH \
  -d MY_DB
```

--------------------------------

### Configure private key authentication via connections.toml

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Recommended for local development. Ensure the file has restricted permissions.

```toml
[production]
account = "myaccount.us-east-1.aws"
user = "service_account"
authenticator = "snowflake_jwt"
private_key_file = "~/.ssh/snowflake_key.p8"  # Recommended parameter name (matches Snowflake connector)
private_key_file_pwd = "my_passphrase"         # Recommended parameter name (matches Snowflake connector)
```

```bash
chmod 600 ~/.snowflake/connections.toml
```

```bash
schemachange deploy -C production
```

--------------------------------

### Snowflake Account Identifier Formats

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Examples of legacy account locator and organization-based account identifier formats.

```text
<account_locator>.<region>.<cloud>
```

```text
<orgname>-<account_name>
```

--------------------------------

### Create migration script

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Create a directory and an initial SQL migration script.

```bash
mkdir -p migrations
cat > migrations/V1.0.0__initial_setup.sql << 'EOF'
CREATE SCHEMA IF NOT EXISTS my_app;
CREATE TABLE IF NOT EXISTS my_app.customers (
    id INTEGER,
    name VARCHAR(100)
);
EOF
```

--------------------------------

### Insecure CLI Argument Usage

Source: https://github.com/snowflake-labs/schemachange/blob/master/SECURITY.md

Example of an insecure command that exposes passwords in shell history and process lists.

```bash
# BAD - CLI arguments are visible in process list and shell history!
schemachange deploy --snowflake-password "my_secret_password"  # ❌ INSECURE!
```

--------------------------------

### Configure schemachange with Environment Variables

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Set environment variables to define connection parameters and execute the deployment command.

```bash
# Environment Variables
export SNOWFLAKE_ACCOUNT="myaccount.us-east-1.aws"
export SNOWFLAKE_CLIENT_SESSION_KEEP_ALIVE="true"
export SNOWFLAKE_LOGIN_TIMEOUT="60"
export SNOWFLAKE_NETWORK_TIMEOUT="120"

schemachange deploy
```

--------------------------------

### Execute Release Workflow

Source: https://github.com/snowflake-labs/schemachange/blob/master/docs/maintainers/GITHUB_MANAGEMENT_WITHOUT_PROJECTS.md

Steps to verify, tag, and publish a new project release.

```bash
# 1. Verify milestone completion
gh milestone view "4.2.0"

# 2. Create release branch (if using branching strategy)
git checkout -b rc4.2.0

# 3. Tag release
git tag -a v4.2.0 -m "Release 4.2.0"
git push origin v4.2.0

# 4. Create GitHub release
gh release create v4.2.0 \
  --title "v4.2.0 - Stabilization Release" \
  --notes-file CHANGELOG.md \
  --latest

# 5. Close milestone
gh milestone close "4.2.0"

# 6. Update roadmap issue
# Edit pinned issue: Move 4.3.0 to "Current", update dates

# 7. Celebrate! 🎉
```

--------------------------------

### Deploy with OAuth Token

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Use OAuth tokens for platform integrations.

```bash
# 1. Get OAuth token from your platform and save it
echo "your_oauth_token" > ~/.snowflake/oauth_token.txt
chmod 600 ~/.snowflake/oauth_token.txt

# 2. Run schemachange with OAuth (using ENV variables)
# NOTE: SNOWFLAKE_* and authentication params are NEW in 4.1.0
export SNOWFLAKE_ACCOUNT="myaccount.us-east-1"
export SNOWFLAKE_USER="my_user"
export SNOWFLAKE_AUTHENTICATOR="oauth"
export SNOWFLAKE_TOKEN_FILE_PATH="~/.snowflake/oauth_token.txt"
export SNOWFLAKE_ROLE="SCHEMACHANGE_DEMO-DEPLOY"
export SNOWFLAKE_WAREHOUSE="SCHEMACHANGE_DEMO_WH"
export SNOWFLAKE_DATABASE="SCHEMACHANGE_DEMO"

schemachange deploy --config-folder ./demo/basics_demo
```

```bash
schemachange deploy \
  --config-folder ./demo/basics_demo \
  --snowflake-account "myaccount.us-east-1" \
  --snowflake-user "my_user" \
  --snowflake-authenticator "oauth" \
  --snowflake-token-file-path "~/.snowflake/oauth_token.txt" \
  --snowflake-role "SCHEMACHANGE_DEMO-DEPLOY" \
  --snowflake-warehouse "SCHEMACHANGE_DEMO_WH" \
  --snowflake-database "SCHEMACHANGE_DEMO"
```

--------------------------------

### Deploy using Connection Profile

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Command to deploy database changes using a specified connection profile from the connections.toml file.

```bash
# Deploy using a connection profile
schemachange deploy -f ./migrations -C production

# Verify connection profile
schemachange verify -C production
```

--------------------------------

### Access GitHub Label Help

Source: https://github.com/snowflake-labs/schemachange/blob/master/docs/maintainers/GITHUB_MANAGEMENT_WITHOUT_PROJECTS.md

Displays help documentation for label management via the GitHub CLI.

```bash
gh label --help
```

--------------------------------

### Manage GitHub Issues and PRs via CLI

Source: https://github.com/snowflake-labs/schemachange/blob/master/docs/maintainers/REPOSITORY_ECOSYSTEM.md

Use these commands to triage, review, and merge contributions efficiently. Requires the GitHub CLI (gh) to be installed and authenticated.

```bash
# 1. Check items ready for review (5 min)
gh pr list --label "status: needs-review"
gh issue list --label "status: needs-review"

# 2. Check critical items (2 min)
gh issue list --label "priority: critical"

# 3. Review and merge PRs (8 min)
gh pr review <number> --approve --body "LGTM! Thanks!"
gh pr merge <number> --squash --delete-branch
```

--------------------------------

### Configure private key authentication via environment variables

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Recommended for CI/CD pipelines to securely pass the private key passphrase.

```bash
export SNOWFLAKE_PRIVATE_KEY_FILE_PWD="my_passphrase"
schemachange deploy \
  --snowflake-authenticator snowflake_jwt \
  --snowflake-private-key-file ~/.ssh/snowflake_key.p8
```

--------------------------------

### Deploy Command with Environment Variables

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Perform a basic deployment using environment variables for Snowflake connection details. Ensure all required variables are set before running.

```bash
# Basic deployment with environment variables
export SNOWFLAKE_ACCOUNT="myaccount.us-east-1.aws"
export SNOWFLAKE_USER="my_user"
export SNOWFLAKE_PASSWORD="my_password_or_pat"
export SNOWFLAKE_ROLE="MY_ROLE"
export SNOWFLAKE_WAREHOUSE="MY_WH"
export SNOWFLAKE_DATABASE="MY_DB"

schemachange deploy -f ./migrations --create-change-history-table
```

--------------------------------

### GitHub Actions CI/CD Configuration

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Example of setting environment variables for Snowflake connection and configuration within a GitHub Actions workflow. Secrets are managed via GitHub's secrets system.

```yaml
# .github/workflows/deploy.yml
env:
  SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
  SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
  SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_PAT }}  # Use a PAT!
  SNOWFLAKE_ROLE: DEPLOY_ROLE
  SNOWFLAKE_WAREHOUSE: DEPLOY_WH
  SNOWFLAKE_DATABASE: ${{ vars.TARGET_DATABASE }}  # Environment-specific

steps:
  - run: schemachange deploy -f migrations
```

--------------------------------

### Docker Container Environment Variables

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Example of running schemachange within a Docker container, passing Snowflake connection details and other configurations as environment variables. Mounts the current directory and sets the working directory.

```bash
docker run --rm \
  -e SNOWFLAKE_ACCOUNT \
  -e SNOWFLAKE_USER \
  -e SNOWFLAKE_PASSWORD \
  -e SNOWFLAKE_ROLE \
  -v "$PWD":/workspace \
  -w /workspace \
  schemachange/schemachange:latest deploy -f migrations
```

--------------------------------

### Production Deployment with JWT

Source: https://github.com/snowflake-labs/schemachange/blob/master/SECURITY.md

Steps to generate a key pair and perform a production deployment using JWT authentication.

```bash
# 1. Generate key pair (one-time setup)
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out snowflake_key.p8 -nocrypt

# 2. Configure Snowflake user with public key
# (Upload public key to Snowflake user)

# 3. Store private key securely
chmod 600 snowflake_key.p8

# 4. Deploy
export SNOWFLAKE_ACCOUNT="prod-account.us-east-1"
export SNOWFLAKE_USER="deployment_service_account"
export SNOWFLAKE_AUTHENTICATOR="snowflake_jwt"
export SNOWFLAKE_PRIVATE_KEY_FILE="./snowflake_key.p8"

schemachange deploy
```

--------------------------------

### Access GitHub Milestone Help

Source: https://github.com/snowflake-labs/schemachange/blob/master/docs/maintainers/GITHUB_MANAGEMENT_WITHOUT_PROJECTS.md

Displays help documentation for milestone management via the GitHub CLI.

```bash
gh milestone --help
```

--------------------------------

### Multi-Environment Deployment with PAT

Source: https://github.com/snowflake-labs/schemachange/blob/master/SECURITY.md

Environment variable configuration for deploying to production using PAT authentication.

```bash
# Production
export SNOWFLAKE_ACCOUNT="prod-account.us-east-1"
export SNOWFLAKE_USER="prod_deployment"
export SNOWFLAKE_PASSWORD="<prod_pat_token>"  # PAT, not password
export SNOWFLAKE_DATABASE="PRODUCTION_DB"

schemachange deploy --config-folder ./config
```

--------------------------------

### Deploy using environment variables

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Recommended for CI/CD pipelines, this method uses environment variables for authentication and configuration.

```bash
export SNOWFLAKE_ACCOUNT="myaccount.us-east-1.aws"
export SNOWFLAKE_USER="my_user"
export SNOWFLAKE_PASSWORD="my_password"  # Or use a PAT token
export SNOWFLAKE_ROLE="MY_ROLE"
export SNOWFLAKE_WAREHOUSE="MY_WH"
export SNOWFLAKE_DATABASE="MY_DB"

schemachange deploy -f migrations
```

--------------------------------

### Configure Local Authentication with connections.toml

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Use a local TOML file to store connection details for development environments.

```bash
cat > ~/.snowflake/connections.toml << EOF
[demo]
account = "myaccount.us-east-1"
user = "my_user"
password = "my_password_or_pat"
role = "SCHEMACHANGE_DEMO-DEPLOY"
warehouse = "SCHEMACHANGE_DEMO_WH"
database = "SCHEMACHANGE_DEMO"
EOF

chmod 600 ~/.snowflake/connections.toml
schemachange deploy -C demo --config-folder ./demo/basics_demo
```

--------------------------------

### Deploy using connection name

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Deploys migrations using a specified connection profile from `connections.toml`.

```bash
schemachange deploy -f migrations -C dev
```

```bash
schemachange deploy -f migrations -C prod
```

--------------------------------

### Deploy Command in Dry-Run Mode

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Simulate a deployment to preview changes without actually executing them. Useful for verifying migration scripts.

```bash
# Dry-run mode to preview changes without executing
schemachange deploy -f ./migrations --dry-run --create-change-history-table
```

--------------------------------

### Verify Schemachange Configuration

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Use the verify command to test connectivity and validate your configuration. This command accepts configuration parameters similar to the deploy command.

```bash
schemachange verify --config-folder ./config
```

```bash
schemachange verify
```

--------------------------------

### Simulate deployments with dry-run

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Use dry-run mode to preview deployment changes without executing SQL. Requires valid Snowflake credentials and access to the change history table.

```bash
# Preview first-time deployment (change history table doesn't exist yet)
schemachange deploy --dry-run --create-change-history-table

# Preview subsequent deployment (change history table exists)
schemachange deploy --dry-run

# ERROR: This will fail if change history table doesn't exist
schemachange deploy --dry-run  # Missing --create-change-history-table
```

--------------------------------

### Use Jinja Templating in CLI Scripts

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Enable dynamic configuration by using the .cli.yml.jinja extension and referencing variables within the YAML.

```yaml
steps:
  - cli: snow
    command: sql
    args:
      - "--query"
      - "USE DATABASE {{ database_name }}"
    description: "Switch to {{ environment }} database"
```

--------------------------------

### Interactive Deployment with Password and MFA

Source: https://github.com/snowflake-labs/schemachange/blob/master/SECURITY.md

Use environment variables for interactive sessions, noting that this will trigger MFA prompts during each deployment.

```bash
# ⚠️ Acceptable for interactive sessions but will prompt for MFA
export SNOWFLAKE_PASSWORD="my_login_password"
schemachange deploy -C dev  # Will prompt for MFA code each time
```

--------------------------------

### Implement Jinja Templating in SQL

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Use Jinja2 syntax for dynamic content generation, with variables provided via CLI or configuration files.

```sql
-- File: V1.1.0__create_environment_schema.sql.jinja
-- Variables passed via --vars or schemachange-config.yml

USE DATABASE {{ database_name }};

CREATE SCHEMA IF NOT EXISTS {{ schema_name }}_{{ environment }};

CREATE TABLE IF NOT EXISTS {{ schema_name }}_{{ environment }}.config (
    key VARCHAR(100) PRIMARY KEY,
    value VARCHAR(1000),
    environment VARCHAR(50) DEFAULT '{{ environment }}',
    updated_at TIMESTAMP_LTZ DEFAULT CURRENT_TIMESTAMP()
);

-- Insert environment-specific configuration
INSERT INTO {{ schema_name }}_{{ environment }}.config (key, value)
VALUES
    ('api_endpoint', '{{ api_endpoint | default("https://api.example.com") }}'),
    ('max_retries', '{{ max_retries | default(3) }}'),
    ('timeout_seconds', '{{ timeout_seconds | default(30) }}');
```

--------------------------------

### Deploy with Programmatic Access Token (PAT)

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Use PATs for CI/CD pipelines where MFA is enabled.

```bash
# Generate PAT in Snowflake UI: User Preferences → Password → Generate Token
# NOTE: SNOWFLAKE_* environment variables are NEW in 4.1.0
export SNOWFLAKE_ACCOUNT="myaccount.us-east-1"
export SNOWFLAKE_USER="my_user"
export SNOWFLAKE_PASSWORD="<your_pat_token>"  # PAT, not password!
export SNOWFLAKE_ROLE="SCHEMACHANGE_DEMO-DEPLOY"
export SNOWFLAKE_WAREHOUSE="SCHEMACHANGE_DEMO_WH"
export SNOWFLAKE_DATABASE="SCHEMACHANGE_DEMO"

schemachange deploy --config-folder ./demo/basics_demo
```

```bash
schemachange deploy \
  --config-folder ./demo/basics_demo \
  --snowflake-account "myaccount.us-east-1" \
  --snowflake-user "my_user" \
  --snowflake-password "${SNOWFLAKE_PASSWORD}" \
  --snowflake-role "SCHEMACHANGE_DEMO-DEPLOY" \
  --snowflake-warehouse "SCHEMACHANGE_DEMO_WH" \
  --snowflake-database "SCHEMACHANGE_DEMO"
```

--------------------------------

### Verify deployment

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Verify the status of migrations via schemachange or by querying the Snowflake metadata table.

```bash
# Check what schemachange sees
schemachange verify -f migrations

# Check Snowflake (using Snowflake CLI)
snow sql -q "SELECT * FROM metadata.schemachange.change_history ORDER BY installed_on DESC LIMIT 5;"
```

--------------------------------

### Configure private key authentication via YAML

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Use YAML configuration files combined with environment variables for the passphrase.

```yaml
config-version: 2

snowflake:
  account: myaccount.us-east-1
  user: service_account
  authenticator: snowflake_jwt
  private-key-file: ~/.ssh/snowflake_key.p8
  # Do NOT put private-key-file-pwd here!
```

```bash
export SNOWFLAKE_PRIVATE_KEY_FILE_PWD="my_passphrase"
schemachange deploy
```

--------------------------------

### Deploy using legacy arguments

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Execute deployment using deprecated unprefixed arguments. These will trigger warnings and are scheduled for removal in 5.0.0.

```bash
# Old unprefixed arguments (deprecated)
schemachange deploy \
  --config-folder ./demo/basics_demo \
  --vars '{"env": "prod"}' \
  --log-level INFO \
  -a "myaccount" \
  -u "deploy_user" \
  -r "DEPLOY_ROLE" \
  -w "DEPLOY_WH" \
  -d "PROD_DB"
```

--------------------------------

### Verify Command with Environment Variables

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Test Snowflake connectivity and display configuration using environment variables. This is a quick way to check credentials.

```bash
# Test connection with environment variables
schemachange verify
```

--------------------------------

### Deploy with External Browser/SSO

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Authenticate via browser for interactive sessions with MFA or SSO enabled.

```bash
# Opens browser for authentication
# NOTE: SNOWFLAKE_* environment variables are NEW in 4.1.0
export SNOWFLAKE_ACCOUNT="myaccount.us-east-1"
export SNOWFLAKE_USER="my_user"
export SNOWFLAKE_AUTHENTICATOR="externalbrowser"
export SNOWFLAKE_ROLE="SCHEMACHANGE_DEMO-DEPLOY"
export SNOWFLAKE_WAREHOUSE="SCHEMACHANGE_DEMO_WH"
export SNOWFLAKE_DATABASE="SCHEMACHANGE_DEMO"

schemachange deploy --config-folder ./demo/basics_demo
```

```bash
schemachange deploy \
  --config-folder ./demo/basics_demo \
  --snowflake-account "myaccount.us-east-1" \
  --snowflake-user "my_user" \
  --snowflake-authenticator "externalbrowser" \
  --snowflake-role "SCHEMACHANGE_DEMO-DEPLOY" \
  --snowflake-warehouse "SCHEMACHANGE_DEMO_WH" \
  --snowflake-database "SCHEMACHANGE_DEMO"
```

--------------------------------

### Render Command with Modules Folder

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Render a SQL script that utilizes shared templates located in a specified modules folder. Ensure the modules path is correctly set.

```bash
# Render with modules folder for shared templates
schemachange render ./migrations/V1.0.0__setup.sql \
  -f ./migrations \
  -m ./modules
```

--------------------------------

### Verify Schemachange Configuration

Source: https://github.com/snowflake-labs/schemachange/blob/master/TROUBLESHOOTING.md

Run the `schemachange verify` command to check your configuration, including the default warehouse.

```bash
schemachange verify
```

--------------------------------

### schemachange deploy --dry-run

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Simulates a deployment without executing any SQL statements to preview changes and validate configurations.

```APIDOC
## CLI COMMAND: schemachange deploy --dry-run

### Description
Simulates a deployment without executing any SQL statements. This is useful for previewing changes, validating scripts, and testing in CI/CD pipelines.

### Parameters
#### Flags
- **--dry-run** (flag) - Required - Enables dry-run mode.
- **--create-change-history-table** (flag) - Optional - Simulates the creation of the change history table if it does not exist.
```

--------------------------------

### Authenticate with CLI Arguments

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Pass connection parameters directly via command-line flags.

```bash
schemachange deploy \
  --config-folder ./demo/basics_demo \
  --snowflake-account "myaccount.us-east-1" \
  --snowflake-user "service_account" \
  --snowflake-password "${SNOWFLAKE_PASSWORD}" \
  --snowflake-role "SCHEMACHANGE_DEMO-DEPLOY" \
  --snowflake-warehouse "SCHEMACHANGE_DEMO_WH" \
  --snowflake-database "SCHEMACHANGE_DEMO"
```

--------------------------------

### Run tests locally as a contributor

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Configures environment variables and executes a deployment to verify local changes.

```bash
# Test your changes against basics_demo
export SNOWFLAKE_ACCOUNT="myaccount"
export SNOWFLAKE_USER="my_user"
export SNOWFLAKE_PASSWORD="<your_password_or_pat>"
export SNOWFLAKE_ROLE="SCHEMACHANGE_DEMO-DEPLOY"
export SNOWFLAKE_WAREHOUSE="SCHEMACHANGE_DEMO_WH"
export SNOWFLAKE_DATABASE="SCHEMACHANGE_DEMO"

# Run a demo to test your code
python -m schemachange deploy --config-folder ./demo/basics_demo
```

--------------------------------

### Deploy Command with CLI Arguments

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Execute a deployment using command-line arguments for Snowflake connection parameters. This method overrides environment variables.

```bash
# Deployment with CLI arguments
schemachange deploy \
  -f ./migrations \
  -a myaccount.us-east-1.aws \
  -u my_user \
  -r MY_ROLE \
  -w MY_WH \
  -d MY_DB \
  --create-change-history-table
```

--------------------------------

### Create GitHub Release

Source: https://github.com/snowflake-labs/schemachange/blob/master/docs/maintainers/README.md

Use the GitHub CLI to create a release associated with a Git tag, using tag notes for the release description.

```bash
gh release create v4.2.0 --title "Release 4.2.0" --notes-from-tag
```

--------------------------------

### Deploy using deprecated short-form arguments

Source: https://github.com/snowflake-labs/schemachange/blob/master/demo/README.MD

Executes a deployment using legacy short-form flags. Note that these are deprecated and will trigger warnings.

```bash
export SNOWSQL_PWD="<your_pat_token>"  # ⚠️ SNOWSQL_PWD is deprecated, use SNOWFLAKE_PASSWORD

schemachange deploy --config-folder ./demo/basics_demo \
  -a "myaccount.us-east-1" \
  -u "my_user" \
  -r "SCHEMACHANGE_DEMO-DEPLOY" \
  -w "SCHEMACHANGE_DEMO_WH" \
  -d "SCHEMACHANGE_DEMO"
```

--------------------------------

### Update CLI Arguments for SchemaChange

Source: https://github.com/snowflake-labs/schemachange/blob/master/TROUBLESHOOTING.md

Demonstrates the transition from deprecated CLI arguments to their recommended replacements in SchemaChange. Use the new prefixed arguments to avoid deprecation warnings.

```bash
# Old (deprecated, works until 5.0.0):
schemachange deploy --vars '{"env": "prod"}' --log-level INFO --query-tag "deployment"

# New (recommended):
schemachange deploy --schemachange-config-vars '{"env": "prod"}' --schemachange-log-level INFO --snowflake-query-tag "deployment"

# Or use short forms:
schemachange deploy -V '{"env": "prod"}' -L INFO -Q "deployment"
```

--------------------------------

### Create a Repeatable Migration Script

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Use the R__ prefix for scripts that re-run whenever their content changes, such as views or stored procedures.

```sql
-- File: R__create_customer_view.sql
-- Naming convention: R__<description>.sql
-- Re-runs when checksum changes

CREATE OR REPLACE VIEW my_app.active_customers AS
SELECT
    c.id,
    c.name,
    c.email,
    COUNT(o.id) as order_count,
    SUM(o.total_amount) as total_spent
FROM my_app.customers c
LEFT JOIN my_app.orders o ON c.id = o.customer_id
GROUP BY c.id, c.name, c.email
HAVING COUNT(o.id) > 0;
```

--------------------------------

### Configuration Priority Hierarchy

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Visual representation of the precedence order for configuration parameters.

```text
🥇 CLI Arguments (--flags)
  ↓ overrides
🥈 Environment Variables (SNOWFLAKE_*, SCHEMACHANGE_*)
  ↓ overrides
🥉 YAML Config File (schemachange-config.yml)
  ↓ overrides
🏅 connections.toml (when explicitly enabled)
```

--------------------------------

### Render Command with Variables from Config File

Source: https://context7.com/snowflake-labs/schemachange/llms.txt

Render a SQL script with Jinja templating, using variables defined in the configuration file. This helps in debugging dynamic SQL.

```bash
# Render a script with variables from config file
schemachange render ./migrations/V1.0.0__create_tables.sql
```

--------------------------------

### Local Development with Vault

Source: https://github.com/snowflake-labs/schemachange/blob/master/README.md

Demonstrates setting Snowflake connection environment variables using a command-line vault tool (like 1Password CLI). Ensure these variables are exported before running schemachange.

```bash
# Fetch secrets from your vault (1Password, AWS Secrets Manager, etc.)
export SNOWFLAKE_ACCOUNT=$(op read "op://Engineering/Snowflake/account")
export SNOWFLAKE_PASSWORD=$(op read "op://Engineering/Snowflake/pat")
export SNOWFLAKE_USER="my_user"
export SNOWFLAKE_ROLE="DEV_ROLE"

schemachange deploy -f migrations
```

--------------------------------

### Test Schemachange Configuration and Connectivity

Source: https://github.com/snowflake-labs/schemachange/blob/master/SECURITY.md

Run the `schemachange verify` command to test your configuration files and Snowflake connectivity. It shows configuration sources, masked parameters, and connection test results.

```bash
# Test your configuration and connectivity
schemachange verify
```

--------------------------------

### Multi-Environment Deployment with JWT

Source: https://github.com/snowflake-labs/schemachange/blob/master/SECURITY.md

Environment variable configuration for deploying to production and staging using JWT authentication.

```bash
# Production
export SNOWFLAKE_ACCOUNT="prod-account.us-east-1"
export SNOWFLAKE_USER="prod_service_account"
export SNOWFLAKE_AUTHENTICATOR="snowflake_jwt"
export SNOWFLAKE_PRIVATE_KEY_FILE="~/.ssh/snowflake_prod.p8"
export SNOWFLAKE_DATABASE="PRODUCTION_DB"

schemachange deploy --config-folder ./config

# Staging
export SNOWFLAKE_ACCOUNT="staging-account.us-east-1"
export SNOWFLAKE_USER="staging_service_account"
export SNOWFLAKE_AUTHENTICATOR="snowflake_jwt"
export SNOWFLAKE_PRIVATE_KEY_FILE="~/.ssh/snowflake_staging.p8"
export SNOWFLAKE_DATABASE="STAGING_DB"

schemachange deploy --config-folder ./config
```