Configuration Reference

Overview

Spry configuration can be set through:

Document Frontmatter - YAML at the top of Spryfiles
Environment Variables - System environment
Command Line Flags - Override at runtime
Code DEFAULTS Directive - Set defaults for code cells

Configuration Precedence

Command-line flags override environment variables, which override code cell metadata, which override Code DEFAULTS, which override document frontmatter. This hierarchy allows flexible configuration across different environments.

Document Frontmatter

YAML block at the start of a Spryfile, delimited by ---:

---
key: value
nested:
  key: value
---

Frontmatter Must Be First

YAML frontmatter must appear at the very beginning of your Spryfile, before any content.

Interpolation Syntax

Environment variables can be interpolated in frontmatter using ${env.VAR} syntax:

---
sqlpage-conf:
  database_url: ${env.DATABASE_URL}
  port: ${env.PORT}
---

Security Best Practice

Never commit sensitive values like passwords or API keys directly in frontmatter. Always use environment variable interpolation.

SQLPage Configuration

For SQLPage playbooks, use the sqlpage-conf key in frontmatter. The configuration is written to sqlpage.json when using --conf:

spry sp spc --conf sqlpage/sqlpage.json

Configuration Options

Option	Type	Description
`database_url`	string	Database connection URL
`web_root`	string	Web root directory for development mode
`port`	number/string	Server port (can use `${env.PORT}`)
`allow_exec`	boolean	Allow exec components
`max_database_pool_connections`	number	Max database connections
`listen_on`	string	Listen address (PostgreSQL: `0.0.0.0:${env.PORT}`)
`site_prefix`	string	URL prefix for the site
`max_uploaded_file_size`	number	Maximum upload size in bytes
`compress_responses`	boolean	Enable gzip compression
`https_domain`	string	Domain name for HTTPS certificates
`environment`	string	Environment identifier

Example Configurations

---
sqlpage-conf:
  database_url: ${env.SPRY_DB}
  web_root: ./dev-src.auto
  port: ${env.PORT}
  allow_exec: true
---

---
sqlpage-conf:
  database_url: sqlite://app.db?mode=rwc
  port: 443
  allow_exec: false
  compress_responses: true
  https_domain: app.example.com
---

---
sqlpage-conf:
  database_url: ${env.SPRY_DB}
  web_root: ./dev-src.auto
  port: ${env.PORT}
  listen_on: 0.0.0.0:${env.PORT}
  allow_exec: true
  max_database_pool_connections: 20
  compress_responses: true
---

Environment Variables

Spry Environment Variables

Variable	Purpose
`SPRY_DB`	Default database URL for SQLPage
`PORT`	SQLPage server port
`NO_COLOR`	Disable colored output when set

Using Environment Variables

In frontmatter:

---
sqlpage-conf:
  database_url: ${env.SPRY_DB}
---

In code cells with interpolation enabled:

```bash task -I
echo "Deploying to ${env.DEPLOY_ENV}"
```

Setting Environment Variables

Using direnv with .envrc:

Create .envrc file in your project directory:

export SPRY_DB="sqlite://app.db?mode=rwc"
export PORT=9227

Enable direnv for the directory:

direnv allow

Recommended Approach

We highly recommend direnv for automatic environment variable management. Variables automatically load when you cd into the directory and unload when you leave.

Shell Export:

export SPRY_DB="sqlite://app.db?mode=rwc"
export PORT=9227

In CI/CD (GitHub Actions):

env:
  SPRY_DB: ${{ secrets.SPRY_DB }}
  PORT: 9227

Generate .envrc with Spry:

```bash prepare-env -C ./.envrc --gitignore --descr "Generate .envrc file"
export SPRY_DB="sqlite://app.db?mode=rwc"
export PORT=9227
```

Run the task:

spry rb task prepare-env

This creates .envrc and automatically adds it to .gitignore!

Code DEFAULTS Directive

Set default flags for code cells matching patterns:

```code DEFAULTS
sql * --interpolate
bash test-* --silent
```

Syntax

LANGUAGE PATTERN FLAGS

LANGUAGE - Language identifier (bash, sql, python, etc.)
PATTERN - Glob pattern for matching cell identities (* for all)
FLAGS - Flags to apply to matching cells

Examples

# All SQL cells are interpolated
```code DEFAULTS
sql * --interpolate
```

# All bash cells with test- prefix are silent
```code DEFAULTS
bash test-* --silent
```

# Multiple defaults
```code DEFAULTS
sql * --interpolate --injectable
bash deploy-* --graph deploy
python * --executable
```

Runtime Catalogs

Spry's unified execution framework (lib/spawn) supports catalog-based runtime configuration. Catalogs define how code is executed declaratively.

Catalog Format

Catalogs are defined in YAML and parsed via catalogFromYaml():

runtimes:
  dev-db:
    engine: sqlite3
    connection: sqlite://app.db?mode=rwc

  prod-db:
    engine: psql
    connection: ${env.DATABASE_URL}

  shell:
    engine: bash

Using Catalogs

In code, catalogs are loaded and used via the factory.ts API:

import { catalogFromYaml, using } from "./lib/spawn/factory.ts";

// Parse catalog from YAML
const catalog = catalogFromYaml(yamlContent);

// Get an executor for a specific runtime
const executor = using(catalog, "dev-db");

// Execute SQL
const result = await executor.spawn({
  code: "SELECT * FROM users;",
});

Supported Engines

Engine	Description
`psql`	PostgreSQL via psql CLI
`sqlite3`	SQLite via sqlite3 CLI
`duckdb`	DuckDB via duckdb CLI
`bash`	Bash shell
`sh`	POSIX shell
`pwsh`	PowerShell
`cmd`	Windows Command Prompt
`fish`	Fish shell
`env`	Environment variable processor (in-process)
`envrc`	direnv configuration processor (in-process)

Execution Modes

Engines support different execution modes for passing code:

Mode	Description
`stdin`	Pass code via stdin
`file`	Write code to temp file, pass file path
`eval`	Pass code as command-line argument
`auto`	Engine chooses the best mode

Contribution Specs

Include external files into the document's resource pool:

```contribute sqlpage_files --base ./templates
**/*.sql
```

contribute Syntax

contribute TARGET --base DIRECTORY
GLOB_PATTERNS

This allows you to include files matching glob patterns from a specified directory.

Configuration Precedence

When the same setting appears in multiple places:

Command-line flags (highest priority)
Environment variables
Code cell metadata
Code DEFAULTS directive
Document frontmatter (lowest priority)

Example:

# Environment variable
export PORT=8080

# Frontmatter says port: 9227

# Command-line argument wins
spry sp spc --port 3000  # Actually uses 3000

Validation

Validate your configuration:

# Check document structure
spry axiom inspect myfile.md

# View detected issues
spry rb issues myfile.md

# List tasks
spry rb ls myfile.md

CI/CD Integration

Add validation to your CI/CD pipeline to catch configuration errors before deployment:

# .github/workflows/validate.yml
- name: Validate Spryfile
  run: spry rb issues --format json

Complete Example

Here's a comprehensive Spryfile demonstrating all configuration features:

---
sqlpage-conf:
  database_url: ${env.SPRY_DB}
  web_root: ./dev-src.auto
  port: ${env.PORT}
  allow_exec: true
---

# My Application

## Code Defaults

```code DEFAULTS
sql * --interpolate
bash test-* --silent

Environment Setup

export SPRY_DB="sqlite://app.db?mode=rwc"
export PORT=9227

Development Commands

spry sp spc --fs dev-src.auto --destroy-first --watch --with-sqlpage

Pages

SELECT 'card' as component, 'Welcome' as title;

How is this guide?

Configuration Reference

On this page