The squirrels.yml file is the main manifest configuration file for a Squirrels project. It defines your project’s metadata, database connections, datasets, and other settings. The file supports Jinja templating, allowing you to use environment variables and dynamic values.
File structure overview The manifest file contains the following top-level sections:
Section Required Description project_variablesYes Core project metadata like name and version packagesNo External Squirrels packages to import connectionsNo Database connection definitions parametersNo Parameter widget definitions configurablesNo Project-level configurable placeholders datasetsNo Dataset endpoint configurations selection_test_setsNo Test sets for parameter selections
project_variables Defines the core metadata for your Squirrels project. This section is required .
project_variables : name : my_project label : "My Analytics Project" description : This is a sample Squirrels project major_version : 1 The unique identifier for your project. Must only contain alphanumeric characters, underscores, and dashes. This is used in API routes.
label
string
default: "(derived from name)"
A human-readable label for the project displayed in the UI. If not specified, it is derived from the name using title case.
A description of the project.
The major version number of the project. Used in API versioning (e.g., /project/my_project/v1/).
The project_variables section allows additional custom fields beyond the ones listed above. These extra fields can be accessed in your Python configurations and Jinja templates.
packages Defines external Squirrels packages to import. Packages allow you to reuse models, macros, and other assets across projects.
packages : - git : https://github.com/org/shared-analytics.git revision : v1.0.0 directory : shared_analytics Each package is defined as a list item with the following properties:
The Git repository URL for the package.
The Git revision (tag, branch, or commit) to use.
directory
string
default: "(derived from git URL)"
The local directory name to clone the package into. Defaults to the repository name from the Git URL.
Run sqrl deps to download and install all packages defined in this section.
connections Defines database connections used by your models. Alternatively, connections can be defined with Python in pyconfigs/connections.py.
connections : - name : default label : Main Database type : sqlalchemy uri : sqlite:///{project_path}/assets/database.db Each connection is defined as a list item with the following properties:
A unique identifier for the connection. Use this name to reference the connection in your models.
A human-readable label for the connection.
type
string
default: "sqlalchemy"
The connection type. One of:
sqlalchemy: Uses SQLAlchemy for database connections (most compatible).connectorx: Uses ConnectorX for high-performance data loading.adbc: Uses Arrow Database Connectivity.duckdb: Native DuckDB connection/attachment. The connection URI. Format varies by database and connection type. The special placeholder {project_path} is replaced with the absolute path to your project directory.
Additional arguments passed to SQLAlchemy’s create_engine() function used by Squirrels. Only applicable when type is sqlalchemy.
The connections URI format varies depending on the connection type and database:
Standard format: dialect://username:password@host:port/database Examples:
SQLite: sqlite:///{project_path}/assets/database.db
PostgreSQL: postgresql://user:pass@localhost:5432/mydb
MySQL: mysql+pymysql://user:pass@localhost:3306/mydb
See the SQLAlchemy documentation for more details.
Similar to SQLAlchemy but with subtle differences for some databases. Examples:
SQLite: sqlite://{project_path}/assets/database.db (note: two slashes, not three)
PostgreSQL: postgresql://user:pass@localhost:5432/mydb
See the ConnectorX documentation for more details. Note that ConnectorX and ADBC do not support placeholders in SQL queries.
For attaching external databases directly to DuckDB. Examples:
DuckDB: {project_path}/assets/database.duckdb
SQLite: sqlite:{project_path}/assets/database.db
PostgreSQL: postgres:dbname=mydb user=user password=pass host=localhost port=5432
DuckLake:
DuckLake with DuckDB: ducklake:{project_path}/assets/database.duckdb
DuckLake with PostgreSQL: ducklake:postgres:dbname=mydb user=user password=pass host=localhost port=5432
Use Jinja templating to substitute environment variables in your connection URIs: connections : - name : production_db uri : {{ env_vars.DATABASE_URL }} parameters Defining parameters here in yaml is not recommended. Defining parameters with Python in pyconfigs/parameters.py is preferred, especially when using an IDE that provides autocomplete and type checking for Python.
Defines parameter widgets for your datasets. Alternatively, parameters can be defined with Python in pyconfigs/parameters.py.
parameters : - type : SingleSelectParameter factory : CreateWithOptions arguments : name : region label : Region all_options : - id : na label : North America is_default : true - id : eu label : Europe Each parameter is defined as a list item with the following properties:
The parameter type. One of:
SingleSelectParameter: Dropdown selection of one option.MultiSelectParameter: Selection of multiple options.DateParameter: Single date picker.DateRangeParameter: Date range picker.NumberParameter: Single number input.NumberRangeParameter: Number range input (min/max).TextParameter: Free text input. The factory method to create the parameter. One of:
CreateSimple: Create with minimal configuration.CreateWithOptions: Create with explicit options defined inline.CreateFromSource: Create with options loaded from a data source. Arguments passed to the factory method. The available arguments depend on the type and factory combination. Common arguments include name, label, description, and type-specific options.
configurables Defines project-level configurables that can be set at runtime via HTTP headers. Unlike parameters, these do not get exposed as arguments for MCP tools (i.e., AI agents cannot control them). The default values can also be overridden at the dataset level.
configurables : - name : schema_name label : Database Schema description : The schema to query from default : public Each configurable is defined as a list item with the following properties:
A unique identifier for the configurable.
A human-readable label for the configurable.
A description of what this configurable controls.
The default value for the configurable.
datasets Defines the dataset endpoints exposed by your Squirrels API. Each dataset maps to a data model, and can specify parameters and access scopes.
datasets : - name : sales_report label : Sales Report description : Daily sales transactions model : sales_model scope : protected parameters : - date_range - region configurables : - name : schema_name default : sales Each dataset is defined as a list item with the following properties:
A unique identifier for the dataset. Used in API routes (e.g., /datasets/sales_report).
label
string
default: "(same as name)"
A human-readable label for the dataset displayed in the UI.
A description of the dataset.
model
string
default: "(same as name)"
The name of the data model that produces this dataset. If not specified, defaults to the dataset name.
The access scope for the dataset. One of:
public: Accessible without authentication.protected: Requires authentication to access.private: Only accessible by users with the admin access level. parameters
list[string]
default: "null"
List of parameter names used by this dataset. If not specified, all parameters are available to the dataset.
Dataset-level overrides for project configurables. Each item specifies a name (which must be a valid name from the configurables section) and default (for a different default value for this dataset).
selection_test_sets Defines test sets for parameter selections. Test sets are useful for testing and compiling models with specific parameter values.
selection_test_sets : - name : q1_report user : access_level : admin custom_fields : department : sales parameters : date_range : [ "2024-01-01" , "2024-03-31" ] region : na configurables : schema_name : test Each test set is defined as a list item with the following properties:
A unique identifier for the test set. Use this name with sqrl compile --test-set.
User context for the test set. The user’s access level. One of admin, member, or guest.
Custom user fields defined in your user.py configuration.
Parameter name-value pairs to use for the test set. Values should match the expected format for each parameter type.
Configurable name-value pairs to use for the test set.
A test set named default is automatically used when no test set is specified during compilation. You can override the default behavior by defining a test set with this name.
Using Jinja templating The squirrels.yml file supports Jinja templating, allowing you to:
Reference environment variables
Use conditional logic
Include dynamic content
Environment variables Access environment variables using the env_vars dictionary:
connections : - name : main_db uri : {{ env_vars.DATABASE_URL }} Environment variables are loaded from .env and .env.local files in your project directory, as well as from system environment variables.
Complete example Here’s a complete example of a squirrels.yml file:
project_variables : name : expense_analytics label : "Expense Analytics" description : Analytics project for expense tracking major_version : 1 packages : - git : https://github.com/org/shared-macros.git revision : v1.0.0 connections : - name : default label : Expenses Database type : sqlalchemy uri : {{ env_vars.SQLITE_URI }} datasets : - name : expense_transactions label : Expense Transactions description : All expense transactions model : expense_model scope : protected parameters : - date_range - category - name : expense_summary label : Expense Summary description : Aggregated expense data scope : public selection_test_sets : - name : default parameters : date_range : [ 2024-01-01 , 2024-12-31 ] - name : admin_view user : access_level : admin parameters : date_range : [ 2024-01-01 , 2024-12-31 ] category : all 
