Skip to main content
Environment variables allow you to configure various aspects of your Squirrels project without modifying code. These variables can be set in a .env or .env.local file at the root of your project, or as system environment variables. It is also common practice to include a .env.example file in your project to contain example environment variables, especially if the .env file is not committed to version control.
If the same variable is defined in both .env.local and .env, the value in .env.local takes precedence.

​
Secrets

If your .env.local or .env file contains these secret environment variables that start with SQRL_SECRET__, do not commit it to version control!
​
SQRL_SECRET__KEY
string
Secret key used for JWT token signing and session management. Required for authentication features like creating access tokens and API keys.You can generate a secure key using the following command for instance:
python -c "import secrets; print(secrets.token_hex(32))"
​
SQRL_SECRET__ADMIN_PASSWORD
string
Password for the admin user (i.e., the user with username admin). When set, the password of the admin user is created or updated on server startup.

​
Authentication and permissions

​
SQRL_AUTH__DB_FILE_PATH
string
default:"{project_path}/target/auth.sqlite"
Path to the SQLite database file used for storing user accounts, API keys, and OAuth client data. Supports the {project_path} placeholder.
​
SQRL_AUTH__TOKEN_EXPIRE_MINUTES
integer
default:"30"
Expiration time for JWT access tokens in minutes.
​
SQRL_AUTH__ALLOWED_ORIGINS_FOR_COOKIES
string
default:"https://squirrels-analytics.github.io"
Comma-separated list of origins allowed to send credentials (cookies) with requests. These origins get Access-Control-Allow-Credentials: true in CORS responses.By including https://squirrels-analytics.github.io in the list, you may also use the following Squirrels Studio site to log in to your Squirrels project with a “bring your own backend service” approach.https://squirrels-analytics.github.io/squirrels-studio-v1
​
SQRL_PERMISSIONS__ELEVATED_ACCESS_LEVEL
string
default:"admin"
The minimum access level required for elevated privileges (e.g., using configurables via headers). Valid values: admin, member, or guest.

​
Parameters

​
SQRL_PARAMETERS__DATASOURCE_REFRESH_MINUTES
integer
default:"60"
Interval in minutes for automatically refreshing datasource parameter options in the background. Set to 0 or a negative number to disable automatic refresh.
​
SQRL_PARAMETERS__CACHE_SIZE
integer
default:"1024"
Maximum number of entries in the parameters cache.
​
SQRL_PARAMETERS__CACHE_TTL_MINUTES
integer
default:"60"
Time-to-live for cached parameter results in minutes.

​
Datasets and dashboards

​
SQRL_DATASETS__MAX_ROWS_FOR_AI
integer
default:"100"
Maximum number of rows that AI can see through MCP (Model Context Protocol) tools. This is to prevent excessive context usage.
​
SQRL_DATASETS__CACHE_SIZE
integer
default:"128"
Maximum number of entries in the dataset results cache.
​
SQRL_DATASETS__CACHE_TTL_MINUTES
integer
default:"60"
Time-to-live for cached dataset results in minutes.
​
SQRL_DASHBOARDS__CACHE_SIZE
integer
default:"128"
Maximum number of entries in the dashboards cache.
​
SQRL_DASHBOARDS__CACHE_TTL_MINUTES
integer
default:"60"
Time-to-live for cached dashboard results in minutes.

​
Seeds

​
SQRL_SEEDS__INFER_SCHEMA
boolean
default:"true"
Whether to automatically infer column types when loading CSV seed files. Set to false to treat all columns as strings.
​
SQRL_SEEDS__NA_VALUES
string
default:"[]"
A JSON array of strings to treat as null/NA values when parsing seed CSV files.Example: ["", "NA", "N/A", "null"].

​
Connections

​
SQRL_CONNECTIONS__DEFAULT_NAME_USED
string
default:"default"
The default connection name to use when no connection is explicitly specified.

​
Virtual Data Lake (VDL)

​
SQRL_VDL__CATALOG_DB_PATH
string
default:"see below (too long to fit here)"
Path to the ducklake catalog database for the Virtual Data Lake. Supports the {project_path} placeholder.Default value is ducklake:{project_path}/target/vdl_catalog.duckdb.
​
SQRL_VDL__DATA_PATH
string
default:"{project_path}/target/vdl_data/"
Directory path of the ducklake data files for the Virtual Data Lake. Supports the {project_path} placeholder.

​
Squirrels Studio

​
SQRL_STUDIO__BASE_URL
string
default:"see below (too long to fit here)"
URL for fetching the CSS and JavaScript files for the Squirrels Studio application built in to the Squirrels API server. Can be changed to point to a locally-hosted or self-hosted instance of Squirrels Studio.Default value is https://squirrels-analytics.github.io/squirrels-studio-v1.

​
Logging

​
SQRL_LOGGING__LOG_LEVEL
string
default:"INFO"
The logging level. Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL.
​
SQRL_LOGGING__LOG_FORMAT
string
default:"text"
Format for log output. Valid values: text or json.
​
SQRL_LOGGING__LOG_TO_FILE
boolean
default:"false"
Whether to write logs to a file in the logs/ directory in addition to console output.
​
SQRL_LOGGING__LOG_FILE_SIZE_MB
integer
default:"50"
Maximum size of each log file in megabytes before rotation occurs. Ignored if SQRL_LOGGING__LOG_TO_FILE is false.
​
SQRL_LOGGING__LOG_FILE_BACKUP_COUNT
integer
default:"1"
Number of backup log files to keep after rotation. Ignored if SQRL_LOGGING__LOG_TO_FILE is false.

​
Example .env file

The following are examples of frequently used environment variables.
.env
# Secrets
SQRL_SECRET__KEY=your-secret-key-here
SQRL_SECRET__ADMIN_PASSWORD=your-admin-password

# Parameters
SQRL_PARAMETERS__DATASOURCE_REFRESH_MINUTES=1440  # 1 day

# Datasets
SQRL_DATASETS__MAX_ROWS_FOR_AI=20

# Logging
SQRL_LOGGING__LOG_LEVEL=DEBUG
SQRL_LOGGING__LOG_TO_FILE=true