Configuration Reference

Overview

Spry's configuration system is flexible and hierarchical, allowing you to set options at multiple levels. Configuration can be defined through:

Document Frontmatter - YAML at the top of Spryfiles
Environment Variables - System environment settings
Command Line Flags - Runtime overrides
Code DEFAULTS Directive - Default flags for code cells

Configuration Hierarchy

Command-line arguments override environment variables, which override frontmatter, which override defaults. This flexibility lets you develop locally and deploy to different environments seamlessly.

Document Frontmatter

YAML frontmatter provides document-level configuration at the top of your Spryfile.

Basic Syntax

Frontmatter is a YAML block delimited by --- markers:

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

Frontmatter Must Be First

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

Environment Variable Interpolation

Use ${env.VARIABLE_NAME} syntax to reference environment variables anywhere in frontmatter:

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

Security Best Practice

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

SQLPage Configuration

Configure SQLPage applications using the sqlpage-conf key in frontmatter. The configuration is written to sqlpage.json when using the --conf flag:

spry sp spc --conf sqlpage/sqlpage.json

Complete Example

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

Configuration Options Reference

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

Database URL Formats

Relative Path:

database_url: sqlite://app.db?mode=rwc

Absolute Path:

database_url: sqlite:///absolute/path/to/app.db?mode=rwc

Common Query Parameters:

mode=rwc - Read, write, create if not exists
mode=rw - Read and write only (no create)
mode=ro - Read-only
cache=shared - Enable shared cache

Basic Connection:

database_url: postgresql://user:pass@host:5432/database

With Environment Variables:

database_url: postgres://${env.PGUSER}:${env.PGPASSWORD}@${env.PGHOST}/${env.PGDATABASE}

With Connection Parameters:

database_url: postgresql://user:pass@host:5432/db?sslmode=require&connect_timeout=10

Common Query Parameters:

sslmode=require - Require SSL connection
connect_timeout=10 - Connection timeout in seconds
application_name=myapp - Application identifier

Configuration Examples by Environment

---
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

Environment variables provide secure, flexible configuration across different environments.

Core Spry Variables

Variable	Purpose	Example
`SPRY_DB`	Default database URL for SQLPage	`sqlite://app.db?mode=rwc`
`PORT`	SQLPage server port	`9227`
`DATABASE_URL`	Alternative database URL	`postgres://localhost/db`
`GITHUB_TOKEN`	For remote imports	`ghp_xxxxxxxxxxxxx`
`NO_COLOR`	Disable colored output when set	`1`

Using Environment Variables

In Frontmatter:

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

In Code Cells with Interpolation:

Enable interpolation with the -I flag:

```bash deploy -I
echo "Deploying to ${env.DEPLOY_ENV}"
echo "Database: ${env.SPRY_DB}"
```

Setting Environment Variables

Using direnv with .envrc:

Create .envrc file in your project directory:

# .envrc
export SPRY_DB="sqlite://app.db?mode=rwc"
export PORT=9227
export API_KEY="your-secret-key"

Enable direnv for the directory:

direnv allow

Variables automatically load when you cd into the directory and unload when you leave!

Recommended Approach

We highly recommend direnv for automatic environment variable management. It's the cleanest way to handle per-project configuration.

Shell Export:

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

Source from file:

source .envrc

In CI/CD (GitHub Actions):

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

In Docker:

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

Generate .envrc with Spry:

Create a task in your Spryfile:

```bash
# Code block ID: prepare-env
# Flags: -C ./.envrc --gitignore --descr "Generate .envrc file"
export SPRY_DB="sqlite://app.db?mode=rwc"
export PORT=9227
export API_KEY="generated-key"
```

Run the task:

spry rb task prepare-env

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

Multi-Environment Setup

Use environment-specific configuration files:

.envrc.dev

export SPRY_DB="sqlite://dev.db?mode=rwc"
export PORT=9227
export DEBUG=true
export API_URL="http://localhost:3000"

Load with: source .envrc.dev

.envrc.staging

export SPRY_DB="postgresql://user:pass@staging-db/app"
export PORT=9227
export DEBUG=false
export API_URL="https://api-staging.example.com"

Load with: source .envrc.staging

.envrc.production

export SPRY_DB="postgresql://user:pass@prod-db/app"
export PORT=443
export DEBUG=false
export API_URL="https://api.example.com"
export HTTPS_DOMAIN="app.example.com"

Load with: source .envrc.production

Code Cell Configuration

Configure individual code blocks with cell-level options and defaults.

Code DEFAULTS Directive

Set default flags for code cells matching specific patterns:

```code DEFAULTS
sql * --interpolate
bash test-* --silent
python deploy-* --graph deploy
```

Syntax:

LANGUAGE PATTERN FLAGS

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

Examples:

# All SQL cells use interpolation
```code DEFAULTS
sql * --interpolate
```

# Test scripts run silently
```code DEFAULTS
bash test-* --silent
```

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

Task Cell Options

Configure individual code cells with inline flags:

Option	Syntax	Description
Description	`--descr "text"`	Human-readable task description
Dependencies	`--dep a,b,c`	Required tasks (comma-separated)
Silent	`--silent`	Suppress output
Capture	`-C <path>`	Write output to file
Git Ignore	`--gitignore`	Add output file to .gitignore
Graph	`--graph <name>`	Assign to named dependency graph
Interpolate	`-I` or `--interpolate`	Enable variable interpolation

Example:

```bash build-app --descr "Build production bundle" --dep test,lint -C ./dist/output.log --gitignore
npm run build
```

SQLPage Cell Metadata

Add route configuration as JSON attributes:

```sql dashboard.sql { route: { caption: "Dashboard", icon: "home" } }
SELECT 'card' AS component, 'Welcome' AS title;
```

Route Attributes:

Attribute	Type	Description	Example
`caption`	string	Navigation title	`"Dashboard"`
`description`	string	Page description	`"Main dashboard view"`
`icon`	string	Icon name	`"home"`
`path`	string	Custom route path	`"/admin/users"`
`virtual`	boolean	Hide from navigation	`true`

Directive Configuration

Spry provides special directives for content management and imports.

PARTIAL Directive

Create shared content that injects into multiple pages:

```sql PARTIAL global-layout.sql --inject **/*.sql
SELECT 'shell' AS component, 'My App' AS title;
```

Options:

--inject <glob> - Pattern of files to inject into (supports ** for recursive matching)

Use cases:

Global navigation shells
Common headers and footers
Shared authentication checks
Consistent styling

IMPORT Directive

Import code from external files:

```import --base ./lib --spc
sql database-schema.sql HEAD
sql seed-data.sql TAIL
```

Options:

--base <path> - Base directory for relative imports
--spc - Include in SQLPage content generation

Position Keywords:

HEAD - Insert at beginning
TAIL - Insert at end

CONTRIBUTE Directive

Include external files in the document's resource pool:

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

Syntax:

contribute TARGET --base DIRECTORY
GLOB_PATTERNS

Custom Metadata

Define arbitrary metadata for custom processing, documentation, or workflow automation.

Project Metadata

---
project:
  name: My Application
  version: 1.0.0
  author: Your Name
  repository: https://github.com/user/repo
  
deployment:
  environment: production
  region: us-east-1
  cdn: cloudflare
---

Runbook Configuration

For DevOps automation and executable runbooks:

---
runbook:
  name: Server Maintenance
  version: 1.0.0
  author: DevOps Team
  timeout: 3600
  retry: 3
  notify:
    - ops@example.com
---

Fields:

name - Runbook identifier
version - Semantic version
author - Owner or team
timeout - Maximum execution time (seconds)
retry - Number of retry attempts
notify - Email addresses for notifications

Data Quality Configuration

For data validation and quality checks:

---
dq:
  dataset: users
  severity: error
  threshold: 0.95
  notify:
    - data-team@example.com
  schedule: "0 2 * * *"
---

Fields:

dataset - Dataset identifier
severity - error, warning, or info
threshold - Quality score threshold (0-1)
notify - Alert recipients
schedule - Cron expression for automated runs

Compliance Configuration

For audit and compliance tracking:

---
doc-classify:
  role: evidence
  framework: SOC2
  control: CC6.1
  status: pending
  last_review: 2025-01-15
  reviewer: security@example.com
---

Fields:

role - Document role: evidence, policy, procedure
framework - Compliance framework: SOC2, CMMC, ISO27001
control - Specific control identifier
status - Current status: pending, passed, failed
last_review - ISO date of last review
reviewer - Reviewer email address

Extensible by Design

These metadata schemas are examples. You can define any frontmatter structure that suits your workflow and access it in projections and custom code.

FileText

Documentation

Extract project info for README generation and API documentation

Upload

Deployment

Route deployments to correct environments based on metadata

Shield

Compliance

Track audit requirements and test status for certifications

Workflow

Custom Workflows

Build domain-specific automation based on structured metadata

Configuration Precedence

When the same setting appears in multiple places, Spry uses this priority order (highest to lowest):

Command-line arguments - Always wins
Environment variables - From .envrc, shell exports, or CI/CD
Code cell metadata - Cell-level flags
Code DEFAULTS directive - Pattern-based defaults
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 and Debugging

Spry validates all configuration using Zod schemas, providing clear error messages for issues.

Checking for Issues

Validate your Spryfile before running:

# Check current directory
spry rb issues

# Validate specific file
spry rb issues path/to/Spryfile.md

# JSON output for CI/CD
spry rb issues --format json

Understanding Validation Errors

When configuration is invalid, you'll see detailed error messages:

Error: Invalid frontmatter in Spryfile.md

Issues found:
  - sqlpage-conf.port: Expected number, received string "abc"
  - sqlpage-conf.database_url: Required field missing
  - sqlpage-conf.max_uploaded_file_size: Must be positive integer

JSON Format Example:

{
  "issues": [
    {
      "severity": "error",
      "location": "frontmatter.sqlpage-conf.port",
      "message": "Expected number, received string",
      "file": "Spryfile.md"
    }
  ]
}

Inspection Commands

View document structure and metadata:

# Inspect document structure
spry axiom inspect myfile.md

# List all tasks
spry rb ls myfile.md

# Show task details
spry rb ls myfile.md --verbose

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

Common Patterns and Best Practices

Secrets Management

Never commit secrets to version control. Always use environment variables:

---
sqlpage-conf:
  database_url: ${env.DATABASE_URL}
  
api:
  key: ${env.API_KEY}
  secret: ${env.API_SECRET}
---

Load from secrets manager:

# From AWS Secrets Manager
export API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id api-key \
  --query SecretString \
  --output text)

# From 1Password CLI
export API_KEY=$(op read "op://vault/api/key")

# From environment file (not committed)
source .env.secrets

Configuration Templates

Create reusable templates with sensible defaults:

---
sqlpage-conf:
  database_url: ${env.SPRY_DB:-sqlite://app.db?mode=rwc}
  port: ${env.PORT:-9227}
  web_root: ${env.WEB_ROOT:-./dev-src.auto}
  allow_exec: ${env.ALLOW_EXEC:-true}
---

The :- syntax provides default values when variables aren't set.

Git Ignore Patterns

Add generated files to .gitignore:

# Environment files
.envrc
.envrc.*
.env.secrets

# Generated configuration
sqlpage.json
dev-src.auto/

# Build outputs
*.log
dist/

Or use Spry's automatic gitignore with --gitignore flag:

```bash build -C output.log --gitignore
npm run build
```

Complete Example

Here's a full Spryfile demonstrating all configuration features:

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

# Project Metadata
project:
  name: My Web App
  version: 1.0.0
  author: Development Team

# Deployment Configuration
deployment:
  environment: production
  region: us-east-1
---

# My Application

Set default flags for all SQL cells to enable interpolation:

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

Environment Setup

Generate .envrc file with project configuration:

# Code block ID: prepare-env
# Flags: -C ./.envrc --gitignore --descr "Generate environment variables"
export SPRY_DB="sqlite://app.db?mode=rwc"
export PORT=9227
export DEBUG=true

Database Setup

Create database schema:

CREATE TABLE IF NOT EXISTS users (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT UNIQUE
);

Development Server

Start the development server with hot reload:

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

Application Pages

Home page with navigation:

SELECT 'card' AS component, 
       'Welcome' AS title,
       'My Application' AS description;

Dashboard page:

SELECT 'chart' AS component;

Testing

Run test suite:

npm test

Deployment

Build and deploy:

echo "Deploying to ${env.DEPLOY_ENV}"
npm run build
npm run deploy

How is this guide?

Configuration Reference

Documentation

Deployment

Compliance

Custom Workflows

On this page