PRQL Development Workflow

Expert development guide for PRQL (Pipelined Relational Query Language) — a modern SQL replacement. This skill covers the complete development workflow including tiered testing strategy, snapshot testing patterns, error handling conventions, and CLI usage.

Tiered Testing Strategy

Use a three-tier testing approach to iterate quickly while validating thoroughly:

Inner Loop (during development, ~5s)

Fast tests on core packages for rapid iteration:

```sh

Fast tests on core packages

task prqlc:test

Filtered by test name for specific functionality

cargo insta test -p prqlc --lib -- resolver

cargo insta test -p prqlc --test integration -- date

```

Before Returning to User (~30s)

Comprehensive validation sufficient for most changes:

```sh

Comprehensive prqlc tests - sufficient for most changes

task prqlc:pull-request

```

Cross-Binding Changes (~2min)

Only run when changes affect language bindings:

```sh

Only when changes affect JS/Python/wasm bindings

task test-all

```

**Token Optimization**: The test suite minimizes output with:

Snapshot Testing with Insta

Prefer inline snapshots for almost all tests:

```rust

insta::assert_snapshot!(result, @"expected output");

```

Initializing Tests

Initialize with empty snapshots, then run with `--accept`:

```rust

insta::assert_snapshot!(result, @"");

```

Run test commands with `--accept` to auto-fill results.

Test Strategy Guidelines

**Prefer small inline `insta` snapshot tests** over full integration tests:

**Use inline tests for:**

**Use integration tests** (`prqlc/tests/integration/queries/*.prql`) only when:

**Example inline test:**

```rust

#[cfg(test)]

mod test {

use insta::assert_snapshot;

#[test]

fn test_my_feature() {

let query = "from employees | filter country == 'USA'";

assert_snapshot!(crate::tests::compile(query).unwrap(), @"");

}

}

```

CLI Usage

View `prqlc` output for any compilation stage:

```sh

Compile PRQL to SQL

cargo run -p prqlc -- compile "from employees | filter country == 'USA'"

Format PRQL code

cargo run -p prqlc -- fmt "from employees | filter country == 'USA'"

See all available commands

cargo run -p prqlc -- --help

```

Linting

Run all lints:

```sh

task lint

```

Error Handling Best Practices

Never panic on user input or recoverable errors. Use proper error returns:

Error Message Style

Avoid 2nd person (you/your). Use softer modal verbs like "might" for friendlier tone:

Documentation

Build and view crate documentation:

```sh

Build documentation for specific crate

cargo doc -p prqlc

View generated HTML documentation with View tool

Docs generated at target/doc/{crate_name}/index.html

View target/doc/prqlc/index.html

For specific module documentation

View target/doc/prqlc/module_name/index.html

For function documentation

View target/doc/prqlc/fn.compile.html

```

Additional Resources

For releases or environment issues, consult `web/book/src/project/contributing/development.md`.

Key Principles

1. **Test incrementally**: Start with fast inner-loop tests, expand only as needed

2. **Snapshot everything**: Inline snapshots make tests readable and maintainable

3. **Never panic**: Handle user errors gracefully with proper error types

4. **Friendly errors**: Use indirect language ("might be missing") instead of accusatory tone

5. **Token efficiency**: Testing infrastructure optimized to reduce AI context usage