Configuration

Overview

Spry uses YAML frontmatter, environment variables, and cell-level options to configure applications. This reference covers all available configuration options and best practices.

Configuration Layers

Spry's configuration system is hierarchical: command-line arguments override environment variables, which override frontmatter, which override defaults. This flexibility lets you develop locally and deploy to different environments seamlessly.

Frontmatter

Document-level configuration uses YAML frontmatter at the top of Spryfiles.

Basic Syntax

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

Frontmatter Must Be First

YAML frontmatter must appear at the very beginning of your Spryfile, before any content. It's delimited by --- markers on both ends.

SQLPage Configuration

Configure SQLPage applications with the sqlpage-conf key in frontmatter.

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

Available Options

Option	Type	Description
database_url	string	Database connection URL
web_root	string	Web content directory
port	number/string	Server port
listen_on	string	Listen address (PostgreSQL)
allow_exec	boolean	Allow exec component
max_uploaded_file_size	number	Max upload size in bytes
compress_responses	boolean	Enable gzip compression
https_domain	string	HTTPS domain for certificates
environment	string	Environment name

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

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}

Connection Parameters:

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

Common Options:

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

Security Note

Never commit database passwords directly in your Spryfile. Always use environment variables with ${env.VARIABLE} syntax.

Environment Variables

Environment variables provide secure, flexible configuration across different environments.

Interpolation Syntax

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

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

Common Variables

Variable	Description	Example
`SPRY_DB`	Database connection URL	`sqlite://app.db?mode=rwc`
`PORT`	Server port	`9227`
`DATABASE_URL`	Alternative database URL	`postgres://localhost/db`
`GITHUB_TOKEN`	For remote imports	`ghp_xxxxxxxxxxxxx`

Setting Variables

Using direnv (.envrc):

Create .envrc file:

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

Enable direnv:

direnv allow

Variables automatically load when entering the directory!

Manual Export:

export SPRY_DB="sqlite://app.db?mode=rwc"
export PORT=9227
source .envrc  # Or export individually

In CI/CD:

# GitHub Actions
env:
  SPRY_DB: ${{ secrets.SPRY_DB }}
  PORT: 9227

Docker:

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

Generate with Spry:

In your Spryfile:

```envrc prepare-env -C ./.envrc --gitignore
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 adds it to .gitignore automatically!

Best Practice: direnv

We highly recommend using direnv for automatic environment variable management. It loads variables when you cd into your project and unloads them when you leave.

Custom Metadata

Add arbitrary metadata for custom processing, documentation, or workflow management.

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

Use Cases

Documentation Generation

Extract project info for README generation and API docs

Deployment Automation

Use metadata to route deployments to correct environments

Compliance Tracking

Track audit requirements and test status

Custom Workflows

Build domain-specific automation based on metadata

Specialized Configurations

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 - pending, passed, failed
last_review - ISO date of last review
reviewer - Reviewer email

Extensible Metadata

These are examples - you can define any frontmatter structure that suits your workflow. Access custom metadata in projections and custom code.

Cell Options

Cell-level options configure individual code blocks.

Task Options

Option	Syntax	Description
Description	--descr "text"	Human-readable 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 to .gitignore
Graph	--graph <name>	Assign to named graph

Example:

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

SQLPage Cell Options

Add route metadata as JSON attributes:

```sql page.sql { route: { caption: "Dashboard", description: "Main dashboard view" } }
SELECT 'card' AS component;
```

Route Attributes:

Attribute	Description	Example
`caption`	Navigation title	`"Dashboard"`
`description`	Page description	`"Main dashboard view"`
`path`	Custom route path	`"/admin/users"`
`virtual`	Hide from navigation	`true`

Directive Options

PARTIAL Directive

Inject shared content 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)

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

Directive Placement

Directives like PARTIAL and import are processed during the build phase and affect how other cells are generated or combined.

Configuration Precedence

When the same setting is defined in multiple places, Spry uses this priority order:

1. Command-line arguments

Highest priority - always wins

↓

2. Environment variables

From .envrc, shell exports, or CI/CD

↓

3. Frontmatter in Spryfile

YAML configuration at document top

↓

4. Default values

Lowest priority - built-in defaults

Example:

# Environment variable
export PORT=8080

# Frontmatter says
# port: 9227

# Command-line argument wins
spry sp spc --port 3000  # Uses 3000

Validation

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

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

Check for Issues

Validate your Spryfile before running:

# Check for configuration issues
spry rb issues

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

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

Example Output:

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

Validation Best Practice

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

Multi-Environment Setup

Use environment-specific .envrc files:

.envrc.dev

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

Load: 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: 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: source .envrc.production

Secrets Management

Never commit secrets to git. Use environment variables:

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

Load from vault or 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 template Spryfiles for common patterns:

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

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

How is this guide?

Configuration

Documentation Generation

Deployment Automation

Compliance Tracking

Custom Workflows

On this page