PRQL Development Assistant

Expert assistant for developing PRQL (Pipelined Relational Query Language) - a modern language for transforming data that serves as a simple, powerful SQL replacement.

Development Workflow

Use a tiered testing approach to iterate quickly while validating thoroughly:

Inner Loop (during development, ~5s)

Run fast tests on core packages while actively developing:

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

Run comprehensive tests before presenting work:

```sh

Comprehensive prqlc tests - sufficient for most changes

task prqlc:pull-request

```

Cross-Binding Changes Only (~2min)

Only run when changes affect JS/Python/wasm bindings:

```sh

Only when changes affect JS/Python/wasm bindings

task test-all

```

The test suite is optimized to minimize token usage:

Testing Strategy

Prefer Inline Snapshot Tests

Use inline `insta` snapshot tests for almost all testing:

```rust

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

```

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

```rust

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

```

The test commands with `--accept` will fill in the result automatically.

Test Selection Guidelines

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

- Add `#[test]` functions in a `#[cfg(test)]` module at the end of the file

- Use `insta::assert_snapshot!` for compact, readable test assertions

- Fast to run, easy to review in PRs

- Developing large, complex features that need comprehensive testing

- Testing end-to-end behavior across multiple compilation stages

- The test requires external resources or multi-file scenarios

Example of a good 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(), @"");

}

}

```

Running the CLI

For viewing `prqlc` output at any stage of the compilation process:

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

```

Error Handling Rules

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

Error Message Guidelines

Error messages should avoid 2nd person (you/your). Use softer modal verbs like "might" for a friendlier tone:

Linting

Run all lints before committing:

```sh

task lint

```

Documentation

To view crate documentation:

```sh

Build documentation for a specific crate

cargo doc -p prqlc

View the generated HTML documentation with the Read tool

The docs are generated at target/doc/{crate_name}/index.html

Read target/doc/prqlc/index.html

For specific module documentation

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

For function documentation

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

```

Key Principles

1. **Test efficiently**: Use the tiered approach - fast inner loop, comprehensive validation before delivery

2. **Prefer inline tests**: Small, focused snapshot tests over large integration tests

3. **Handle errors properly**: Never panic on user input, always return proper errors

4. **Write friendly errors**: Use modal verbs, avoid "you/your" language

5. **Optimize for tokens**: The test suite is configured to minimize output verbosity

6. **Document as you go**: Build and view docs when exploring unfamiliar code

Additional Resources

For releases or environment issues, see `web/book/src/project/contributing/development.md` in the repository.