Django Snowflake Backend

Common errors

• django.core.exceptions.ImproperlyConfigured: 'django_snowflake' isn't an available database backend. Try using 'django.db.backends.XXX', where XXX is one of: 'mysql', 'oracle', 'postgresql', 'sqlite3'.

  cause The `django-snowflake` package is not installed or the `ENGINE` string in `settings.py` is misspelled.
  fix Run `pip install django-snowflake` and verify that `DATABASES['default']['ENGINE']` is set to `'django_snowflake'`.

• ModuleNotFoundError: No module named 'snowflake.connector'

  cause The `snowflake-connector-python` dependency, required by `django-snowflake`, is not installed in your environment.
  fix Install the underlying Snowflake connector: `pip install snowflake-connector-python`.

• django.db.utils.OperationalError: Failed to connect to DB: <your-account>.snowflakecomputing.com:443. ... Invalid username or password.

  cause Incorrect credentials (user, password, account, role, warehouse) or network issues preventing connection to Snowflake.
  fix Double-check your `USER`, `PASSWORD`, `ACCOUNT`, `WAREHOUSE`, and `ROLE` settings in `DATABASES['default']['OPTIONS']`. Ensure your network allows outbound connections to Snowflake endpoints.

• django.core.exceptions.ImproperlyConfigured: The DATABASE 'default' engine was missing the following key(s): NAME

  cause The `NAME` parameter is missing from the `DATABASES` configuration, which is required by `django-snowflake` to specify the Snowflake database.
  fix Add `"NAME": "your_snowflake_database"` to your `DATABASES['default']` configuration. Even when using a DSN, a top-level `NAME` might be expected or can be deduced from the DSN itself.

Warnings

• breaking django-snowflake v6.0 requires Django 5.x. Previous versions of django-snowflake supported older Django versions.
  Fix: Ensure your Django project is running Django 5.x. If not, upgrade Django or use an older compatible version of django-snowflake (e.g., v5.x for Django 4.x).
• gotcha The `TYPE: 'SNOWFLAKE'` option is no longer required in `DATABASES` settings for django-snowflake versions >= 5.0. Including it is harmless but unnecessary.
  Fix: You can safely remove `"TYPE": "SNOWFLAKE"` from your `DATABASES` configuration if you are on django-snowflake 5.0 or newer. It will not cause errors if left in.
• gotcha When using a DSN (Data Source Name) in `OPTIONS`, ensure all required parameters (user, password, account, database, schema, warehouse, role) are correctly embedded or provided. Mixing DSN with individual options can lead to unexpected behavior.
  Fix: Prefer either a complete DSN string OR individual `OPTIONS` parameters. Avoid using both for the same connection unless explicitly documented for specific overrides.
• gotcha Snowflake's default session schema might not be 'public'. If your Django models expect a specific schema, you must define it explicitly in the `SCHEMA` option or within the DSN.
  Fix: Set `"SCHEMA": "your_schema_name"` in the `OPTIONS` dictionary of your `DATABASES` configuration to ensure Django queries target the correct schema.

Install

• pip install django-snowflake Install stable version

Imports

• ENGINE setting
  wrong:

  DATABASES = {'default': {'ENGINE': 'django_snowflake.base', ...}}

  correct:

  DATABASES = {'default': {'ENGINE': 'django_snowflake', ...}}

  The correct engine path is simply 'django_snowflake', not a deeper internal module path.

Quickstart

Configure your `settings.py` `DATABASES` entry. It's recommended to use environment variables for sensitive credentials and connection details. The `NAME` parameter typically refers to the database in Snowflake. You can provide connection details via individual `OPTIONS` or a full `DSN` string.

import os

DATABASES = {
    "default": {
        "ENGINE": "django_snowflake",
        "NAME": os.environ.get("SNOWFLAKE_DATABASE", "mydb"),
        "USER": os.environ.get("SNOWFLAKE_USER", "my_user"),
        "OPTIONS": {
            "ACCOUNT": os.environ.get("SNOWFLAKE_ACCOUNT", "myaccount"),
            "PASSWORD": os.environ.get("SNOWFLAKE_PASSWORD", ""),
            "WAREHOUSE": os.environ.get("SNOWFLAKE_WAREHOUSE", "my_warehouse"),
            "ROLE": os.environ.get("SNOWFLAKE_ROLE", "my_role"),
            # Optional: Specify the schema if not using a DSN that includes it
            "SCHEMA": os.environ.get("SNOWFLAKE_SCHEMA", "public")
            # For key-pair authentication, provide PRIVATE_KEY instead of PASSWORD:
            # "PRIVATE_KEY": os.environ.get("SNOWFLAKE_PRIVATE_KEY", ""),
            # "PRIVATE_KEY_PASSPHRASE": os.environ.get("SNOWFLAKE_PRIVATE_KEY_PASSPHRASE", "")
        },
    }
}

# Example of using a DSN (Data Source Name) instead of separate options:
# DATABASES = {
#     "default": {
#         "ENGINE": "django_snowflake",
#         "NAME": os.environ.get("SNOWFLAKE_DATABASE", "mydb"),
#         "OPTIONS": {
#             "DSN": os.environ.get(
#                 "SNOWFLAKE_DSN",
#                 "snowflake://{user}:{password}@{account}.snowflakecomputing.com/{database}/{schema}?warehouse={warehouse}&role={role}"
#             ).format(
#                 user=os.environ.get("SNOWFLAKE_USER", "my_user"),
#                 password=os.environ.get("SNOWFLAKE_PASSWORD", ""),
#                 account=os.environ.get("SNOWFLAKE_ACCOUNT", "myaccount"),
#                 database=os.environ.get("SNOWFLAKE_DATABASE", "mydb"),
#                 schema=os.environ.get("SNOWFLAKE_SCHEMA", "public"),
#                 warehouse=os.environ.get("SNOWFLAKE_WAREHOUSE", "my_warehouse"),
#                 role=os.environ.get("SNOWFLAKE_ROLE", "my_role")
#             )
#         },
#     }
# }