### Plan Output Example

Source: https://github.com/datacoves/snowcap/blob/main/docs/python-api.md

Illustrates the output of the `print_plan()` function, showing proposed changes to Snowflake resources.

```text
» snowcap
» Plan: 3 to add, 0 to change, 0 to destroy.

+ urn::ABCD123:warehouse/transforming {
  + name                = "transforming"
  + owner               = "SYSADMIN"
  + warehouse_type      = "STANDARD"
  + warehouse_size      = "LARGE"
  ... 
}

+ urn::ABCD123:role/transformer {
  + name    = "transformer"
  + owner   = "USERADMIN"
}

+ urn::ABCD123:grant/TRANSFORMER?priv=USAGE&on=warehouse/TRANSFORMING {
  + priv    = "USAGE"
  + on      = "transforming"
  + to      = TRANSFORMER
}
```

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

### Run Integration Tests (Setup)

Source: https://github.com/datacoves/snowcap/blob/main/tests/README.md

Execute integration tests after configuring credentials and setting up static resources. Specify the EDITION if needed.

```bash
make integration EDITION=standard
```

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

### Apply Output Example

Source: https://github.com/datacoves/snowcap/blob/main/docs/python-api.md

Shows the SQL commands executed by the `apply()` function to implement the planned changes in Snowflake.

```text
[SNOWCAP_USER:SYSADMIN]  > USE SECONDARY ROLES ALL
[SNOWCAP_USER:SYSADMIN]  > CREATE WAREHOUSE TRANSFORMING warehouse_type = STANDARD ...
[SNOWCAP_USER:SYSADMIN]  > USE ROLE USERADMIN
[SNOWCAP_USER:USERADMIN] > CREATE ROLE TRANSFORMER
[SNOWCAP_USER:USERADMIN] > USE ROLE SYSADMIN
[SNOWCAP_USER:SYSADMIN]  > GRANT USAGE ON WAREHOUSE transforming TO TRANSFORMER
```

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

### Configure Snowflake Credentials

Source: https://github.com/datacoves/snowcap/blob/main/tests/README.md

Copy the example environment file and update it with your Snowflake connection details. Choose either key-pair or password authentication.

```bash
cp tests/.env.example tests/.env
```

```bash
# Required
TEST_SNOWFLAKE_ACCOUNT=your_account_identifier
TEST_SNOWFLAKE_USER=your_username
TEST_SNOWFLAKE_ROLE=ACCOUNTADMIN
TEST_SNOWFLAKE_WAREHOUSE=COMPUTE_WH

# Authentication - choose one:
# Option 1: Key-pair (recommended)
TEST_SNOWFLAKE_PRIVATE_KEY_PATH=/path/to/your/rsa_key.p8

# Option 2: Password
# TEST_SNOWFLAKE_PASSWORD=your_password
```

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

### Snowflake Credentials Environment File

Source: https://github.com/datacoves/snowcap/blob/main/docs/role-based-access-control.md

Set up your Snowflake connection details in a .env file for authentication. This example uses key-pair authentication.

```bash
SNOWFLAKE_ACCOUNT=your-account
SNOWFLAKE_USER=your-user
SNOWFLAKE_ROLE=SECURITYADMIN
SNOWFLAKE_PRIVATE_KEY_PATH=/path/to/rsa_key.p8
SNOWFLAKE_AUTHENTICATOR=SNOWFLAKE_JWT
```

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

### Basic Python API Example

Source: https://github.com/datacoves/snowcap/blob/main/docs/python-api.md

Defines Snowflake resources (Role, Warehouse, Grant), connects to Snowflake, creates a Blueprint, plans changes, and applies them.

```python
import os
import snowflake.connector

from snowcap.blueprint import Blueprint, print_plan
from snowcap.resources import Grant, Role, Warehouse

# Configure resources by instantiating Python objects
role = Role(name="transformer")

warehouse = Warehouse(
    name="transforming",
    warehouse_size="large",
    auto_suspend=60,
)

usage_grant = Grant(priv="usage", to=role, on=warehouse)

# Connect to Snowflake
connection_params = {
    "account": os.environ["SNOWFLAKE_ACCOUNT"],
    "user": os.environ["SNOWFLAKE_USER"],
    "password": os.environ["SNOWFLAKE_PASSWORD"],
    "role": "SYSADMIN",
}
session = snowflake.connector.connect(**connection_params)

# Create a Blueprint and pass your resources into it
bp = Blueprint(resources=[
    role,
    warehouse,
    usage_grant,
])

# Generate a plan (like Terraform)
plan = bp.plan(session)
print_plan(plan)

# Apply changes to Snowflake
bp.apply(session, plan)
```

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

### Configure Snowflake Credentials

Source: https://github.com/datacoves/snowcap/blob/main/TESTING.md

Set up environment variables in tests/.env by copying from the example file. This includes account details, user, role, and warehouse.

```bash
TEST_SNOWFLAKE_ACCOUNT=xy12345.us-east-1
TEST_SNOWFLAKE_USER=TEST_USER
TEST_SNOWFLAKE_ROLE=ACCOUNTADMIN
TEST_SNOWFLAKE_WAREHOUSE=COMPUTE_WH
```

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

### Example Exported YAML Configuration

Source: https://github.com/datacoves/snowcap/blob/main/docs/export.md

This is an example of the YAML output generated by the `snowcap export` command. The format is directly usable with `snowcap plan` and `snowcap apply`.

```yaml
# Exported warehouses.yml
warehouses:
  - name: ANALYTICS
    warehouse_size: XSMALL
    auto_suspend: 60
    auto_resume: true

  - name: LOADING
    warehouse_size: SMALL
    auto_suspend: 300
    auto_resume: true
```

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

### Install Snowcap

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Install Snowcap using pip within a Python virtual environment. Activate the environment before installation.

```sh
# MacOS / Linux
python -m venv .venv
source .venv/bin/activate
pip install snowcap

# Windows
python -m venv .venv
.\.venv\Scripts\activate
pip install snowcap
```

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

### SQL Fixture Example

Source: https://github.com/datacoves/snowcap/blob/main/TESTING.md

Define expected CREATE SQL statements for resources. This format is used for SQL fixtures and specifies resource properties.

```sql
CREATE RESOURCE MY_RESOURCE
OWNER = SYSADMIN
COMMENT = 'Test resource'
```

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

### Install Snowcap

Source: https://github.com/datacoves/snowcap/blob/main/README.md

Install the snowcap package using pip. Ensure you are using Python 3.10 or later.

```shell
pip install snowcap
```

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

### GitHub Actions Workflow for Planning and Applying

Source: https://github.com/datacoves/snowcap/blob/main/docs/cli.md

This workflow automates the process of planning resources and then applying the generated plan. It includes steps for checking out code, installing Snowcap, generating a plan, and uploading it as an artifact, followed by downloading and applying the plan in a separate job, with an optional production environment approval step.

```yaml
jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install snowcap
      - run: snowcap plan --config resources/ --out plan.json
      - uses: actions/upload-artifact@v4
        with:
          name: plan
          path: plan.json

  apply:
    needs: plan
    runs-on: ubuntu-latest
    environment: production  # Requires approval
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: plan
      - run: pip install snowcap
      - run: snowcap apply --plan plan.json
```

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

### Run dlt Pipeline and Apply PII Tags

Source: https://github.com/datacoves/snowcap/blob/main/docs/masking-policies.md

Example of running a dlt pipeline and then immediately applying PII tags to sensitive columns using the `apply_pii_tag` utility. This ensures data is protected as soon as it lands.

```python
# load/dlt/loans_data.py
import dlt
from utils.datacoves_utils import apply_pii_tag

@dlt.resource(write_disposition="replace")
def personal_loans():
    # ... load logic
    yield df

if __name__ == "__main__":
    pipeline = dlt.pipeline(
        pipeline_name="loans",
        destination=dlt.destinations.snowflake(destination_name="datacoves_snowflake"),
        dataset_name="loans"
    )

    load_info = pipeline.run(personal_loans())
    print(load_info)

    # Apply PII tags to sensitive columns immediately after load
    apply_pii_tag(pipeline, "personal_loans", ["addr_state", "annual_inc"])
```

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

### Key-Pair Authentication Setup

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Configure `.env` for key-pair authentication with Snowflake. This method uses a private key file and specifies the authenticator as `SNOWFLAKE_JWT`.

```sh
# .env
SNOWFLAKE_ACCOUNT=my-account
SNOWFLAKE_USER=my-user
SNOWFLAKE_ROLE=SECURITYADMIN
SNOWFLAKE_PRIVATE_KEY_PATH=/path/to/private-key.pem
SNOWFLAKE_AUTHENTICATOR=SNOWFLAKE_JWT
```

```sh
PRIVATE_KEY_PASSPHRASE=your-passphrase
```

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

### Configure Snowflake Warehouse with Snowcap

Source: https://github.com/datacoves/snowcap/blob/main/README.md

Define Snowflake warehouse resources using a YAML configuration file. This example sets up an 'analytics' warehouse with an 'xsmall' size and auto-suspension after 60 seconds.

```yaml
warehouses:
  - name: analytics
    warehouse_size: xsmall
    auto_suspend: 60
```

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

### Generate dbt Macros with Snowcap CLI (with options)

Source: https://github.com/datacoves/snowcap/blob/main/docs/masking-policies.md

Example of generating Snowcap dbt macros using the CLI with all options specified directly. This avoids interactive prompts and allows for automated configuration.

```bash
snowcap generate dbt-macros \
  --dbt-path ./transform \
  --tag-database GOVERNANCE \
  --tag-schema TAGS \
  --policy-database GOVERNANCE \
  --policy-schema POLICIES
```

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

### Minimal End-to-End Example: AWS S3 Tables behind Lake Formation (YAML)

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/iceberg_rest_catalog_integration.md

YAML configuration for an Iceberg REST catalog integration for AWS S3 Tables using Lake Formation, detailing catalog and authentication settings.

```yaml
# catalog_integrations: tells Snowflake where Iceberg *metadata* lives.
# CATALOG_NAME is the federated <account>:s3tablescatalog/<bucket> form
# that Lake Formation auto-creates — note this DOES NOT work with the
# legacy GlueCatalogIntegration / CATALOG_SOURCE=GLUE path; you must use
# ICEBERG_REST + CATALOG_API_TYPE=AWS_GLUE for S3 Tables.
catalog_integrations:
  - name: ci_p21_iceberg_prd
    catalog_source: ICEBERG_REST
    table_format: ICEBERG
    catalog_namespace: p21
    rest_config:
      catalog_uri: https://glue.us-east-1.amazonaws.com/iceberg
      catalog_api_type: AWS_GLUE
      catalog_name: '123456789012:s3tablescatalog/bcs-iceberg-raw-prd'
      access_delegation_mode: VENDED_CREDENTIALS
    rest_authentication:
      type: SIGV4
      sigv4_iam_role: arn:aws:iam::123456789012:role/snowflake-s3-tables-read
      sigv4_signing_region: us-east-1
    enabled: true
    comment: 'P21 raw Iceberg tables (PRD) - S3 Tables federated catalog via ICEBERG_REST.'

# storage_integrations: tells Snowflake where the Iceberg *data files* live.
# Bucket-level allow so any namespace (p21, spire, future sources) under
# the same bucket is reachable without per-namespace edits. The catalog

```

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

### Example GitHub Actions Workflow for Snowcap

Source: https://github.com/datacoves/snowcap/blob/main/docs/snowcap-github-action.md

This workflow automates Snowflake deployments. It includes jobs for planning changes on pull requests and applying changes on merge to the main branch. Ensure your private key is stored as a GitHub secret.

```yaml
# .github/workflows/snowcap.yml
name: Snowcap

on:
  pull_request:
    paths:
      - 'snowcap/**'
  push:
    branches: [main]
    paths:
      - 'snowcap/**'

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - run: pip install snowcap

      - name: Write private key
        run: echo "${{ secrets.SNOWFLAKE_PRIVATE_KEY }}" > /tmp/rsa_key.pem

      - name: Plan changes
        run: snowcap plan --config ./snowcap/
        env:
          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
          SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
          SNOWFLAKE_PRIVATE_KEY_PATH: /tmp/rsa_key.pem
          SNOWFLAKE_AUTHENTICATOR: SNOWFLAKE_JWT
          SNOWFLAKE_ROLE: ${{ secrets.SNOWFLAKE_ROLE }}

  apply:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - run: pip install snowcap

      - name: Write private key
        run: echo "${{ secrets.SNOWFLAKE_PRIVATE_KEY }}" > /tmp/rsa_key.pem

      - name: Apply changes
        run: snowcap apply --config ./snowcap/
        env:
          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
          SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
          SNOWFLAKE_PRIVATE_KEY_PATH: /tmp/rsa_key.pem
          SNOWFLAKE_AUTHENTICATOR: SNOWFLAKE_JWT
          SNOWFLAKE_ROLE: ${{ secrets.SNOWFLAKE_ROLE }}

```

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

### Export All Supported Resources

Source: https://github.com/datacoves/snowcap/blob/main/docs/export.md

Use this command to export all supported Snowflake resources into a single configuration file. This is useful for initial setup or full environment migration.

```sh
snowcap export \
  --resource=warehouse,role,grant \
  --out=snowcap.yml
```

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

### Create Governance Databases and Schemas

Source: https://github.com/datacoves/snowcap/blob/main/docs/masking-policies.md

Define a dedicated location for governance objects like tags and policies. This setup uses YAML for resource definition.

```yaml
# resources/databases.yml
databases:
  - name: governance
    owner: sysadmin
```

```yaml
# resources/schemas.yml
schemas:
  - name: governance.tags
    managed_access: true
  - name: governance.policies
    managed_access: true
```

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

### JSON Fixture Example

Source: https://github.com/datacoves/snowcap/blob/main/TESTING.md

Define expected resource properties for identity and serialization tests using JSON format. Includes fields like name, owner, and comment.

```json
{
  "name": "MY_RESOURCE",
  "owner": "SYSADMIN",
  "comment": "Test resource"
}
```

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

### Create Tags and Grant Apply Privilege

Source: https://github.com/datacoves/snowcap/blob/main/docs/masking-policies.md

Define data classification tags and roles that can apply these tags. This example shows how to create PII and confidential tags and grant the necessary privileges.

```yaml
# resources/tags.yml
tags:
  - name: governance.tags.pii
    comment: Personally Identifiable Information
    propagate: ON_DATA_MOVEMENT

  - name: governance.tags.confidential
    comment: Confidential business data
    propagate: ON_DATA_MOVEMENT

roles:
  - name: z_tag__apply__pii
  - name: z_tag__apply__confidential

grants:
  - priv: APPLY
    on: tag governance.tags.pii
    to: z_tag__apply__pii

  - priv: APPLY
    on: tag governance.tags.confidential
    to: z_tag__apply__confidential
```

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

### Generate Blueprint Plan

Source: https://github.com/datacoves/snowcap/blob/main/docs/blueprint.md

Call the 'plan()' method on a Blueprint object to compare your configuration with Snowflake and get a list of necessary changes. Requires a Snowflake session object.

```python
plan = bp.plan(session)
```

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

### Plan Static Resource Changes

Source: https://github.com/datacoves/snowcap/blob/main/TESTING.md

Preview the changes that will be applied when setting up static resources without actually applying them.

```bash
./tests/fixtures/static_resources/plan.sh
```

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

### Compose Functional Roles

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Define functional roles and their associated grants in `roles__functional.yml`. This example shows grants for 'analyst' and 'transformer' roles.

```yaml
roles:
  - name: analyst
  - name: loader
  - name: transformer

role_grants:
  - to_role: analyst
    roles:
      - z_db__analytics
      - z_schema__marts
      - z_wh__querying
      - z_tables_views__select

  - to_role: transformer
    roles:
      - z_db__raw
      - z_db__analytics
      - z_wh__transforming
```

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

### Enable ACCOUNT_USAGE via CLI

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Use the `--use-account-usage` flag with `plan` or `apply` commands to enable this optimization.

```sh
snowcap plan --config snowcap.yml --use-account-usage
```

```sh
snowcap apply --config snowcap.yml --use-account-usage
```

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

### Set Test Snowflake Role to ACCOUNTADMIN

Source: https://github.com/datacoves/snowcap/blob/main/TESTING.md

For the simplest setup and full test coverage, set the TEST_SNOWFLAKE_ROLE environment variable to ACCOUNTADMIN.

```bash
TEST_SNOWFLAKE_ROLE=ACCOUNTADMIN
```

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

### Apply Static Resource Changes

Source: https://github.com/datacoves/snowcap/blob/main/tests/fixtures/static_resources/README.md

Run this script to apply the static resources. This command should be executed after reviewing the changes with the plan script.

```bash
./tests/fixtures/static_resources/apply.sh
```

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

### Create Static Test Resources

Source: https://github.com/datacoves/snowcap/blob/main/tests/README.md

Run this command to set up necessary static resources in Snowflake for integration tests. This includes databases, schemas, roles, warehouses, tables, views, and stages.

```bash
make setup-test-resources
```

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

### Run Unit and Integration Tests

Source: https://github.com/datacoves/snowcap/blob/main/tests/README.md

Use 'make test' for unit tests only. For all tests including integration tests, use 'make integration' with an optional EDITION.

```bash
# Run unit tests only (no Snowflake connection required)
make test
```

```bash
# Run all tests including integration tests
make integration EDITION=standard
```

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

### Create Image Repository in Python

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/image_repository.md

Instantiate an ImageRepository object in Python. Set the required name for the repository.

```python
image_repository = ImageRepository(
    name="some_image_repository",
)
```

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

### Loading Credentials from Environment

Source: https://github.com/datacoves/snowcap/blob/main/docs/python-api.md

Demonstrates how to use `python-dotenv` to load Snowflake connection parameters from a `.env` file into `os.environ`.

```python
from dotenv import load_dotenv
load_dotenv()

# Now os.environ has values from .env
```

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

### Initialize Blueprint with Resources

Source: https://github.com/datacoves/snowcap/blob/main/docs/blueprint.md

Use this Python snippet to initialize a Blueprint with specific resources like databases and schemas. It configures the run mode, allows certain resource types, and performs a dry run.

```python
from snowcap.blueprint import Blueprint
from snowcap.resources import Database, Schema

bp = Blueprint(
    run_mode='create-or-update',
    resources=[
        Database('my_database'),
        Schema('my_schema', database='my_database'),
    ],
    allowlist=["database", "schema"],
    dry_run=False,
)
plan = bp.plan(session)
bp.apply(session, plan)
```

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

### plan(session)

Source: https://github.com/datacoves/snowcap/blob/main/docs/blueprint.md

Compares the current configuration to Snowflake and returns a list of changes needed.

```APIDOC
## plan(session)

### Description
Compares your configuration to Snowflake and returns a list of changes needed to reach the desired state.

### Method
`plan`

### Parameters
- **session** - Snowflake connection object.

### Returns
- `list[ResourceChange]` - A list of changes required to synchronize the configuration with Snowflake.

### Request Example
```python
plan = bp.plan(session)
```
```

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

### Define TableStream in YAML

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/table_stream.md

Configure a Snowflake TableStream using YAML. Specify stream name, source table, owner, and time-based or stream-based start points.

```yaml
streams:
  - name: some_stream
    on_table: some_table
    owner: SYSADMIN
    copy_grants: true
    at:
      TIMESTAMP: "2022-01-01 00:00:00"
    before:
      STREAM: some_other_stream
    append_only: false
    show_initial_rows: true
    comment: This is a sample stream.
```

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

### Create Databases, Roles, and Grants with Templates

Source: https://github.com/datacoves/snowcap/blob/main/docs/role-based-access-control.md

Use `for_each` to dynamically create databases, associated roles, and grant USAGE privileges. This template requires a `var.databases` variable to be defined.

```yaml
# Create databases
databases:
  - for_each: var.databases
    name: "{{ each.value.name }}"
    owner: "{{ each.value.owner }}"
    max_data_extension_time_in_days: "{{ each.value.max_data_extension_time_in_days }}"

# Create a role for each database
roles:
  - for_each: var.databases
    name: "z_db__{{ each.value.name }}"

# Grant USAGE on each database to its corresponding role
grants:
  - for_each: var.databases
    priv: USAGE
    on: "database {{ each.value.name }}"
    to: "z_db__{{ each.value.name }}"
```

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

### Reference Variables in Resource Definitions

Source: https://github.com/datacoves/snowcap/blob/main/docs/blueprint.md

Demonstrates how to reference variables within resource definitions using either the 'var.' prefix or Jinja-style syntax. This enables dynamic configuration of resources.

```python
from snowcap.blueprint import Blueprint
from snowcap.resources import Database
from snowcap import var

# Reference a variable
db = Database(name=var.db_name)

# Or use Jinja-style syntax in strings
db = Database(name="db_{{ var.environment }}")

# Pass values when creating the blueprint
bp = Blueprint(
    resources=[db],
    vars={"db_name": "analytics", "environment": "prod"},
)
```

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

### Define Stage Roles and Grants

Source: https://github.com/datacoves/snowcap/blob/main/docs/role-based-access-control.md

Configure read and write roles for a specific stage, granting appropriate privileges. This example defines roles for reading and writing to the 'raw.dbt_artifacts.artifacts' stage.

```yaml
stages:
  - name: raw.dbt_artifacts.artifacts
    type: internal
    owner: transformer_dbt
    directory:
      enable: true
    comment: Used to store dbt artifacts

roles:
  - name: z_stage__raw__dbt_artifacts__artifacts__read
  - name: z_stage__raw__dbt_artifacts__artifacts__write

grants:
  - priv: "READ"
    on: "stage raw.dbt_artifacts.artifacts"
    to: z_stage__raw__dbt_artifacts__artifacts__read

  - priv:
      - READ
      - WRITE
    on: "stage raw.dbt_artifacts.artifacts"
    to: z_stage__raw__dbt_artifacts__artifacts__write
```

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

### Set Environment Variable for Secret

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/generic_secret.md

Before using secrets with environment variable references in YAML, set the required environment variables. This example shows how to export a variable for an API key.

```bash
# Set in your environment or .env file (loaded before running snowcap)
export SNOWCAP_VAR_API_KEY="your-secret-api-key"
```

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

### Preview Snowcap Configuration Changes

Source: https://github.com/datacoves/snowcap/blob/main/README.md

Use the 'snowcap plan' command to preview the SQL changes that will be applied based on your configuration file. This helps in reviewing modifications before execution.

```shell
# Preview changes
snowcap plan --config snowcap.yml
```

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

### Deploy Schema Configuration to Staging and Production

Source: https://github.com/datacoves/snowcap/blob/main/docs/yaml-configuration.md

CLI commands to deploy the finance configuration to staging and production environments using the `--vars` flag to set the environment variable.

```sh
# Deploy to staging
snowcap apply --config finance.yml --vars '{"env": "STAGE"}'

# Deploy to production
snowcap apply --config finance.yml --vars '{"env": "PROD"}'
```

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

### Apply Static Resources

Source: https://github.com/datacoves/snowcap/blob/main/TESTING.md

Set up shared test fixtures required before running integration tests. This can be done using 'make' or by directly executing a shell script.

```bash
# Using make
make setup-test-resources
```

```bash
# Or directly
./tests/fixtures/static_resources/apply.sh
```

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

### Execute Wrapper Script for Snowcap Apply

Source: https://github.com/datacoves/snowcap/blob/main/docs/cli.md

These commands demonstrate how to make the wrapper script executable and then use it to apply changes or perform a dry run. The `"$@"` syntax ensures that any additional arguments passed to the script are forwarded to the `snowcap apply` command.

```bash
chmod +x snowcap-apply.sh
./snowcap-apply.sh                    # Apply changes
./snowcap-apply.sh --dry-run          # Preview only
```

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

### Configure Snowflake Credentials

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Set up environment variables in a `.env` file for Snowflake authentication. Ensure this file is added to your `.gitignore`.

```sh
# .env
SNOWFLAKE_ACCOUNT=my-account
SNOWFLAKE_USER=my-user
SNOWFLAKE_PASSWORD=my-password
SNOWFLAKE_ROLE=SYSADMIN
```

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

### Create Warehouses, Roles, and Grants with Templates

Source: https://github.com/datacoves/snowcap/blob/main/docs/role-based-access-control.md

Use `for_each` to generate warehouses, their corresponding roles, and grant USAGE and MONITOR privileges. This template requires a `var.warehouses` variable.

```yaml
# Create warehouses
warehouses:
  - for_each: var.warehouses
    name: "{{ each.value.name }}"
    warehouse_size: "{{ each.value.size }}"
    auto_suspend: "{{ each.value.auto_suspend }}"
    auto_resume: true
    initially_suspended: true

# Create a role for each warehouse
roles:
  - for_each: var.warehouses
    name: "z_wh__{{ each.value.name }}"

# Grant USAGE and MONITOR on each warehouse to its corresponding role
grants:
  - for_each: var.warehouses
    priv:
      - USAGE
      - MONITOR
    on: "warehouse {{ each.value.name }}"
    to: "z_wh__{{ each.value.name }}"
```

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

### Create Resource Monitor in Python

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/resource_monitor.md

Instantiate a ResourceMonitor object in Python to configure credit limits, monitoring periods, and notification recipients.

```python
resource_monitor = ResourceMonitor(
    name="some_resource_monitor",
    credit_quota=1000,
    frequency="DAILY",
    start_timestamp="2049-01-01 00:00",
    end_timestamp="2049-12-31 23:59",
    notify_users=["user1", "user2"]
)
```

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

### Blueprint Initialization

Source: https://github.com/datacoves/snowcap/blob/main/docs/blueprint.md

Initializes a Blueprint object with various configuration parameters.

```APIDOC
## Blueprint Initialization

### Description
Initializes a Blueprint object with configuration parameters like run mode, resources, allowlist, and dry run settings.

### Parameters

#### Blueprint Constructor Parameters
- **run_mode** (string) - Defines how the blueprint interacts with the Snowflake account. Possible values: 'create-or-update' (default), 'sync'.
- **resources** (list) - List of resources to manage.
- **allowlist** (list) - Limits which resource types the blueprint can manage. Required when using 'sync' mode.
- **dry_run** (boolean) - If True, `apply()` returns SQL commands without executing them.
- **vars** (dict) - A dictionary of variable values for templating.
- **vars_spec** (list) - Defines expected variables with types and optional defaults.
- **scope** (string) - Limits Snowcap to managing resources within a specific scope.
- **database** (string) - Limits Snowcap to managing resources within a specific database.
- **schema** (string) - Limits Snowcap to managing resources within a specific schema.
- **use_account_usage** (boolean) - Controls whether Snowcap uses `SNOWFLAKE.ACCOUNT_USAGE` views for fetching grants. Defaults to `False`.

### Request Example
```python
from snowcap.blueprint import Blueprint
from snowcap.resources import Database, Schema

bp = Blueprint(
    run_mode='create-or-update',
    resources=[
        Database('my_database'),
        Schema('my_schema', database='my_database'),
    ],
    allowlist=["database", "schema"],
    dry_run=False,
    vars={
        "environment": "prod",
        "owner": "analytics_team",
    },
    vars_spec=[
        {"name": "environment", "type": "string"},
        {"name": "size", "type": "string", "default": "XSMALL"},
    ],
    scope="DATABASE",
    database="RAW",
    use_account_usage=True
)
```
```

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

### Workflow: Migrate from Manual Management

Source: https://github.com/datacoves/snowcap/blob/main/docs/export.md

This sequence demonstrates migrating from manual Snowflake management to Snowcap. It involves exporting the current configuration, adding it to version control, and then managing changes via Snowcap commands.

```sh
snowcap export --resource=all --out=snowcap.yml
```

```sh
git add snowcap.yml
git commit -m "Import existing Snowflake configuration"
```

```sh
# Edit snowcap.yml, then:
snowcap plan --config snowcap.yml
snowcap apply --config snowcap.yml
```

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

### Create Object Store Catalog Integration in Python

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/object_store_catalog_integration.md

Instantiate an ObjectStoreCatalogIntegration object in Python to configure an integration for object storage with the ICEBERG table format.

```python
object_store_catalog_integration = ObjectStoreCatalogIntegration(
    name="some_catalog_integration",
    table_format="ICEBERG",
    enabled=True,
    comment="Integration for object storage."
)
```

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

### Run Full Test Suite

Source: https://github.com/datacoves/snowcap/blob/main/TESTING.md

Execute all tests, including integration tests, by first configuring your environment, setting up static resources, and then running pytest.

```bash
# 1. Copy and configure your environment
cp tests/.env.example tests/.env
# Edit tests/.env with your Snowflake credentials

# 2. Set up static resources (one-time)
make setup-test-resources

# 3. Run all tests
pytest tests/ --snowflake -v
```

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

### Create Schemas, Roles, and Grants with Templates

Source: https://github.com/datacoves/snowcap/blob/main/docs/role-based-access-control.md

Dynamically create schemas, roles, and grant USAGE privileges using `for_each`. This template requires a `var.schemas` variable and can inherit the owner from a parent resource.

```yaml
# Create schemas
schemas:
  - for_each: var.schemas
    name: "{{ each.value.name.split('.')[1] }}"
    database: "{{ each.value.name.split('.')[0] }}"
    owner: "{{ each.value.get('owner', parent.owner) }}"

# Create a role for each schema
roles:
  - for_each: var.schemas
    name: "z_schema__{{ each.value.name.split('.')[1] }}"

# Grant USAGE on each schema to its corresponding role
grants:
  - for_each: var.schemas
    priv: USAGE
    on: "schema {{ each.value.name }}"
    to: "z_schema__{{ each.value.name.split('.')[1] }}"
```

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

### CI/CD Workflow: Generate and Save Plan

Source: https://github.com/datacoves/snowcap/blob/main/docs/cli.md

Generate a plan and save it to a JSON file for review in a CI/CD pipeline. This is the first step in a two-step deployment process.

```bash
snowcap plan --config resources/ --out plan.json
```

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

### apply(session, plan)

Source: https://github.com/datacoves/snowcap/blob/main/docs/blueprint.md

Executes SQL commands to apply the plan to Snowflake.

```APIDOC
## apply(session, plan)

### Description
Executes the SQL commands necessary to apply the generated plan to your Snowflake account.

### Method
`apply`

### Parameters
- **session** - Snowflake connection object.
- **plan** *(optional)* - List of changes. If not provided, generates a plan automatically before applying.

### Returns
- `list[str]` - A list of SQL commands that were executed.

### Request Example
```python
results = bp.apply(session, plan)
```
```

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

### Define Databases with Variables

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Define a list of database configurations using variables in `databases.yml`. This allows for easy management and reuse.

```yaml
vars:
  - name: databases
    type: list
    default:
      - name: raw
        owner: loader
      - name: analytics
        owner: transformer
      - name: analytics_dev
        owner: transformer
```

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

### Create Parquet File Format using Python SDK

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/parquet_file_format.md

Instantiate a ParquetFileFormat object using the Python SDK to define file format settings. This includes specifying compression, binary handling, and null value mappings.

```python
file_format = ParquetFileFormat(
    name="some_file_format",
    owner="SYSADMIN",
    compression="AUTO",
    binary_as_text=True,
    trim_space=False,
    replace_invalid_characters=False,
    null_if=["NULL"],
    comment="This is a Parquet file format."
)
```

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

### Apply Snowflake Resource Configuration

Source: https://github.com/datacoves/snowcap/blob/main/docs/cli.md

Apply a resource configuration to a Snowflake account. Use --dry-run to preview changes without applying them.

```bash
snowcap apply --config <path>
```

```bash
# Apply from config
snowcap apply --config resources/
```

```bash
# Apply from saved plan
snowcap apply --plan plan.json
```

```bash
# Dry run (preview only)
snowcap apply --config resources/ --dry-run
```

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

### Snowcap CLI Help

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Display the help message for the Snowcap CLI to see available commands and options.

```sh
snowcap --help
```

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

### add(resource)

Source: https://github.com/datacoves/snowcap/blob/main/docs/blueprint.md

Adds resources to the blueprint after its initialization.

```APIDOC
## add(resource)

### Description
Adds one or more resources to the blueprint after it has been initialized.

### Method
`add`

### Parameters
- **resource** - A single resource object, or a list of resource objects to add to the blueprint.

### Request Example
```python
# Add a single resource
bp.add(Database('another_db'))

# Add multiple resources
bp.add(role1, role2, role3)

# Add a list of resources
bp.add([schema1, schema2])
```
```

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

### Configure Password Authentication

Source: https://github.com/datacoves/snowcap/blob/main/TESTING.md

Set up password authentication for Snowflake by providing the password via an environment variable.

```bash
TEST_SNOWFLAKE_PASSWORD=your_password
```

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

### Enable ACCOUNT_USAGE via YAML Config

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Configure Snowcap to use ACCOUNT_USAGE by setting `use_account_usage` to `true` in your `snowcap.yml` file.

```yaml
# snowcap.yml
use_account_usage: true
```

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

### Parquet File Format Initialization

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/parquet_file_format.md

This snippet demonstrates how to create a Parquet file format object using Python, setting various configuration parameters.

```APIDOC
## Parquet File Format Initialization (Python)

### Description
Initializes a ParquetFileFormat object with specified properties.

### Fields
* `name` (string, required) - The name of the file format.
* `owner` (string or [Role](role.md)) - The owner role of the file format. Defaults to "SYSADMIN".
* `compression` (string) - The compression type for the file format. Defaults to "AUTO".
* `binary_as_text` (bool) - Whether to interpret binary data as text. Defaults to True.
* `trim_space` (bool) - Whether to trim spaces. Defaults to False.
* `replace_invalid_characters` (bool) - Whether to replace invalid characters. Defaults to False.
* `null_if` (list) - A list of strings to be interpreted as NULL.
* `comment` (string) - A comment for the file format.

### Example (Python)
```python
file_format = ParquetFileFormat(
    name="some_file_format",
    owner="SYSADMIN",
    compression="AUTO",
    binary_as_text=True,
    trim_space=False,
    replace_invalid_characters=False,
    null_if=["NULL"],
    comment="This is a Parquet file format."
)
```
```

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

### Configure Snowservices OAuth Security Integration (Python)

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/snowservices_oauth_security_integration.md

Instantiate the SnowservicesOAuthSecurityIntegration class in Python to set up an OAuth security integration. Provide the integration name, enabled status, and an optional comment.

```python
snowservices_oauth = SnowservicesOAuthSecurityIntegration(
    name="some_security_integration",
    enabled=True,
    comment="Integration for external OAuth services."
)
```

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

### Define Streamlit App from Stage (YAML)

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/streamlit.md

Use this YAML configuration to define a Streamlit app sourced from a Snowflake stage. Ensure the `main_file` exists in the specified stage.

```yaml
streamlits:
  # From a stage
  - name: my_db.my_schema.my_streamlit
    from: "@my_stage"
    main_file: app.py
    title: My Streamlit App
    query_warehouse: my_warehouse
    comment: A sample Streamlit app from a stage
    owner: SYSADMIN
    tags:
      project: demo
```

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

### Directory Structure for Scalability

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Organize Snowcap configurations into a structured directory. This includes separate files for different resource types and a directory for object templates.

```tree
snowcap/
├── resources/
│   ├── databases.yml            # Database definitions
│   ├── schemas.yml              # Schema definitions
│   ├── warehouses.yml           # Warehouse definitions
│   ├── stages.yml               # Stage definitions
│   ├── users.yml                # User definitions
│   ├── roles__base.yml          # Atomic privilege roles
│   └── roles__functional.yml    # Functional roles + grants
│
└── object_templates/            # Auto-generate resources with for_each
    ├── database.yml
    ├── schema.yml
    └── warehouses.yml
```

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

### Test Variable Substitution with `snowcap plan`

Source: https://github.com/datacoves/snowcap/blob/main/docs/secrets-and-variables.md

Preview configuration changes by substituting variables before applying them to Snowflake. This command requires the `.env` file to be sourced and a valid `snowcap.yml` configuration.

```bash
source .env && snowcap plan --config snowcap.yml
```

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

### Plan Snowflake Resource Changes

Source: https://github.com/datacoves/snowcap/blob/main/docs/cli.md

Compare resource configuration to the current state of Snowflake and display proposed changes. Use --sync_resources to make the config the source of truth, deleting resources in Snowflake not present in the config.

```bash
snowcap plan --config <path>
```

```bash
# Basic plan
snowcap plan --config resources/
```

```bash
# Plan with sync mode for roles
snowcap plan --config resources/ --sync_resources role,grant,role_grant
```

```bash
# Exclude enterprise features for standard accounts
snowcap plan --config resources/ --exclude masking_policy,row_access_policy
```

```bash
# Output as JSON
snowcap plan --config resources/ --json --out plan.json
```

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

### Enable ACCOUNT_USAGE via Python API

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Instantiate the `Blueprint` class with `use_account_usage=True` to enable this feature programmatically.

```python
bp = Blueprint(
    resources=[...],
    use_account_usage=True,
)
```

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

### Creating Roles and Grants with `for_each`

Source: https://github.com/datacoves/snowcap/blob/main/docs/yaml-configuration.md

A common pattern is creating a role and grant for each resource using `for_each`.

```yaml
vars:
  - name: databases
    type: list
    default:
      - name: raw
      - name: analytics

# Create a role for each database
roles:
  - for_each: var.databases
    name: "z_db__{{ each.value.name }}"

# Grant USAGE on each database to its corresponding role
grants:
  - for_each: var.databases
    priv: USAGE
    on: "database {{ each.value.name }}"
    to: "z_db__{{ each.value.name }}"
```

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

### Apply a Saved Plan

Source: https://github.com/datacoves/snowcap/blob/main/docs/cli.md

Use this command to apply changes directly from a previously saved plan file without re-computation.

```bash
snowcap apply --plan plan.json
```

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

### Create Authentication Policy in Python

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/authentication_policy.md

Instantiate an AuthenticationPolicy object in Python to configure authentication rules, including methods, MFA, and client types.

```python
authentication_policy = AuthenticationPolicy(
    name="some_authentication_policy",
    authentication_methods=["PASSWORD", "SAML"],
    mfa_authentication_methods=["PASSWORD"],
    mfa_enrollment="REQUIRED",
    client_types=["SNOWFLAKE_UI"],
    security_integrations=["ALL"],
    comment="Policy for secure authentication."
)
```

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

### Run Snowcap with Directory Config

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Execute Snowcap commands to plan and apply changes when using a directory structure for configurations. Load environment variables first.

```sh
# Load environment variables from .env
export $(cat .env | xargs)

# Preview all changes
snowcap plan --config ./snowcap/

# Apply all changes
snowcap apply --config ./snowcap/
```

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

### Configure Key-Pair Authentication

Source: https://github.com/datacoves/snowcap/blob/main/TESTING.md

Set up key-pair authentication for Snowflake by specifying the private key path and optionally a passphrase. A command is provided to generate the key.

```bash
TEST_SNOWFLAKE_PRIVATE_KEY_PATH=/path/to/rsa_key.p8
# If key is encrypted:
TEST_SNOWFLAKE_PRIVATE_KEY_PASSPHRASE=your_passphrase
```

```bash
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
```

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

### Create AWS Glue Catalog Integration (Python)

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/glue_catalog_integration.md

Instantiate a GlueCatalogIntegration object in Python to define the integration with AWS Glue. This object requires essential parameters such as name, table format, AWS role ARN, Glue catalog ID, and namespace.

```python
glue_catalog_integration = GlueCatalogIntegration(
    name="some_catalog_integration",
    table_format="ICEBERG",
    glue_aws_role_arn="arn:aws:iam::123456789012:role/SnowflakeAccess",
    glue_catalog_id="some_glue_catalog_id",
    catalog_namespace="some_namespace",
    enabled=True,
    glue_region="us-west-2",
    comment="Integration for AWS Glue with Snowflake."
)
```

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

### Grant Usage on API Integration (YAML)

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/api_integration.md

Demonstrates how to grant USAGE privilege on an API integration using YAML. It shows both the preferred explicit subtype and the supported umbrella syntax for granting permissions.

```yaml
grants:
  - priv: USAGE
    on: api integration github_api_integration   # preferred — explicit subtype
    to: some_role
  - priv: USAGE
    on: integration github_api_integration       # also supported (umbrella)
    to: another_role
```

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

### Run Snowcap CLI Commands

Source: https://github.com/datacoves/snowcap/blob/main/docs/getting-started.md

Execute Snowcap commands to preview or apply infrastructure changes. Load environment variables from the `.env` file first.

```sh
# Load environment variables
export $(cat .env | xargs)

# Preview changes
snowcap plan --config snowcap.yml

# Apply changes
snowcap apply --config snowcap.yml
```

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

### Create a Compute Pool Object in Python

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/compute_pool.md

Instantiate a ComputePool object in Python with parameters for node count, instance family, and auto-suspend. Ensure necessary Snowflake permissions are granted.

```python
compute_pool = ComputePool(
    name="some_compute_pool",
    owner="ACCOUNTADMIN",
    min_nodes=2,
    max_nodes=10,
    instance_family="CPU_X64_S",
    auto_resume=True,
    initially_suspended=False,
    auto_suspend_secs=1800,
    comment="Example compute pool"
)
```

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

### Export Snowflake Resources to Configuration

Source: https://github.com/datacoves/snowcap/blob/main/docs/cli.md

Generate a resource configuration file from existing Snowflake resources. Specify resource types or use --all to export everything.

```bash
snowcap export --resource <types>
```

```bash
snowcap export --all
```

```bash
# Export databases
snowcap export --resource database --out databases.yml
```

```bash
# Export all resources
snowcap export --all --out snowcap.yml
```

```bash
# Export all except users and roles
snowcap export --all --exclude user,role --out snowcap.yml
```

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

### Create GCS Storage Integration in Python

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/gcs_storage_integration.md

Instantiate a GCSStorageIntegration object in Python to configure integration with Google Cloud Storage.

```python
gcs_storage_integration = GCSStorageIntegration(
    name="some_gcs_storage_integration",
    enabled=True,
    storage_allowed_locations=['gcs://bucket/path/'],
    storage_blocked_locations=['gcs://bucket/blocked_path/']
)
```

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

### Create API Authentication Security Integration (Python)

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/api_authentication_security_integration.md

Instantiate an API authentication security integration object in Python. This is useful for programmatic configuration and management.

```python
api_auth_integration = APIAuthenticationSecurityIntegration(
    name="some_api_authentication_security_integration",
    auth_type="OAUTH2",
    oauth_token_endpoint="https://example.com/oauth/token",
    oauth_client_auth_method="CLIENT_SECRET_POST",
    oauth_client_id="your_client_id",
    oauth_client_secret="your_client_secret",
    oauth_grant="client_credentials",
    oauth_access_token_validity=3600,
    oauth_allowed_scopes=["read", "write"],
    enabled=True,
    comment="Integration for external API authentication."
)
```

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

### Create Azure Storage Integration (Python)

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/azure_storage_integration.md

Instantiate an Azure storage integration object in Python. This requires specifying the integration name, tenant ID, and storage location policies.

```python
azure_storage_integration = AzureStorageIntegration(
    name="some_azure_storage_integration",
    enabled=True,
    azure_tenant_id="some_tenant_id",
    storage_allowed_locations=["azure://somebucket/somepath/"]
    storage_blocked_locations=["azure://someotherbucket/somepath/"]
    comment="This is an Azure storage integration."
)
```

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

### Define Resource Monitor in YAML

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/resource_monitor.md

Use this YAML configuration to define a resource monitor with a credit quota, frequency, start/end times, and users to notify.

```yaml
resource_monitors:
  - name: some_resource_monitor
    credit_quota: 1000
    frequency: DAILY
    start_timestamp: "2049-01-01 00:00"
    end_timestamp: "2049-12-31 23:59"
    notify_users:
      - user1
      - user2
```

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

### Create External Access Integration (YAML)

Source: https://github.com/datacoves/snowcap/blob/main/docs/resources/external_access_integration.md

Define an external access integration using YAML configuration. Specify allowed network rules and whether the integration is enabled.

```yaml
external_access_integrations:
  - name: some_external_access_integration
    allowed_network_rules:
      - rule1
      - rule2
    enabled: true
```