Skip to content

docs: document the supported sql.redshift dialect - #6159

Merged
max-sixty merged 2 commits into
mainfrom
docs/redshift-dialect
Aug 7, 2026
Merged

docs: document the supported sql.redshift dialect#6159
max-sixty merged 2 commits into
mainfrom
docs/redshift-dialect

Conversation

@prql-bot

@prql-bot prql-bot commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator

Dialect::Redshift is classified SupportLevel::Supported in sql/dialect.rs, has its own RedshiftDialect handler, and compiles today:

$ printf 'prql target:sql.redshift\nfrom employees\nsort age\ntake 10\n' | prqlc compile
SELECT * FROM employees ORDER BY age LIMIT 10

But sql.redshift appears nowhere in the book — grep -rn redshift web/book/src/ returns nothing. It's missing from both the Supported and Unsupported lists in project/target.md, so a user reading the docs has no way to learn the dialect exists. Every other Dialect variant is listed. This adds it to Supported, matching support_level().

Regression test. The two lists are a hand-maintained copy of Dialect::support_level, which is exactly why they drifted. test_target_dialects_documented parses the bullets out of target.md and asserts they match Dialect::iter() partitioned by support level, so the next dialect that ships undocumented fails CI instead of going unnoticed. Confirmed it fails on the pre-fix doc:

 documented: ["clickhouse", "duckdb", "generic", "glaredb", "mysql", "postgres", "sqlite"]
     actual: ["clickhouse", "duckdb", "generic", "glaredb", "mysql", "postgres", "redshift", "sqlite"]

This follows the pattern of test_date_format_specifiers_compile added in #6140 — asserting a hand-written doc table against the implementation it describes.

Notes

Found during the nightly rolling survey of web/book/src/project/target.md.

The test uses strum::IntoEnumIterator, already a dependency of mdbook-prql, and prqlc::sql::{Dialect, SupportLevel}, both already public. The discriminant comparison is because SupportLevel doesn't derive PartialEq; adding the derive to the public enum felt like a wider change than this fix warrants.

SupportLevel::Nascent is declared and matched on in tests/integration/queries.rs:60 but never returned by support_level(), so no dialect is currently nascent and neither doc list covers it. Left alone.

@prql-bot prql-bot left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Self-review — the doc change matches support_level() and the guard works: I removed the sql.redshift bullet locally and test_target_dialects_documented failed with the expected diff, so it isn't passing vacuously.

One brittleness in the section parser, with an inline suggestion. Separately, the test's stated guarantee — the next dialect that ships undocumented fails CI — doesn't hold for a SupportLevel::Nascent dialect: it lands in neither actual() list, so an undocumented nascent dialect passes silently. No dialect is nascent today, so this is a latent gap rather than a bug; making actual exhaustive over Dialect::iter() (e.g. asserting the two documented lists together account for every variant) would close it.

Comment thread web/book/tests/documentation/book.rs
@prql-bot

prql-bot commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator Author

Closed the Nascent gap in 177c199 — the check is now exhaustive over Dialect::iter() rather than two independent per-level comparisons.

Each dialect is grouped by the heading its support level maps to, and every group is asserted against the bullets under that heading, so a variant can't fall outside both lists. Nascent maps to ### Nascent, which doesn't exist in target.md today; since no dialect is nascent the group is empty and never looked up, but the first one that is fails with `### Nascent` heading not found in target.md — pointing at the missing section rather than passing silently. The level → heading mapping is an exhaustive match, so adding a fourth SupportLevel variant is a compile error until it's given a home in the book too.

That also drops the std::mem::discriminant comparison, so the note in the PR description about SupportLevel not deriving PartialEq no longer applies — the public enum is untouched either way.

Verification

Temporarily reclassifying Dialect::Oracle as SupportLevel::Nascent in sql/dialect.rs — which passed silently before this commit:

---- book::test_target_dialects_documented stdout ----
Error: `### Nascent` heading not found in target.md

Reverted; cargo test -p mdbook-prql --test documentation is green (7 passed).

@max-sixty
max-sixty merged commit f5498fe into main Aug 7, 2026
39 checks passed
@max-sixty
max-sixty deleted the docs/redshift-dialect branch August 7, 2026 23:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants