Skip to content

docs(macros): document that bind parameter nullability is not compile-checked - #4345

Merged
abonander merged 1 commit into
transact-rs:mainfrom
jeremie0342:docs/query-macro-nullability-bind-params
Aug 18, 2026
Merged

abonander merged 1 commit into
transact-rs:mainfrom
jeremie0342:docs/query-macro-nullability-bind-params

Conversation

@jeremie0342

Copy link
Copy Markdown
Contributor

What

Restructures the ## Nullability: Bind Parameters section in the query! macro documentation (src/macros/mod.rs).

Why

Users regularly report the same confusion (e.g. #2642): they write sqlx::query!("INSERT INTO foo (data) VALUES (\$1)", None::<String>) against a NOT NULL column, expecting a compile-time error, and are surprised when the code compiles but fails at runtime.

The existing section technically covered this (Option::None will be bound as NULL, so ... be sure your query can support it), but the phrasing understated the limitation and hid it behind guidance about WHERE clauses.

What changed

  • New opening paragraph states upfront, in bold, that bind parameter nullability is not verified at compile time.
  • Adds a short explanation of why (SQLx does not parse SQL) with a link to the FAQ entry.
  • Adds the concrete failing example from Query macro documentation understates lack of nullability checking on bind parameters #2642 as a runnable-looking snippet.
  • Provides two actionable workarounds (stricter Rust types, integration tests).
  • The pre-existing guidance about WHERE clause / NULL comparisons is preserved as a sub-section (### Bind parameters in WHERE clauses).

Scope

  • One file changed: src/macros/mod.rs
  • Documentation only, no code change, no behavior change
  • cargo doc -p sqlx --no-deps produces no new warnings in the edited range

Closes #2642

…-checked

Restructures the "Nullability: Bind Parameters" section of the query!
macro documentation to state upfront that the nullability of bind
parameters is not verified at compile time, why (SQLx does not parse
SQL), and give the concrete example from transact-rs#2642.

The previous phrasing understated the limitation and hid it behind
guidance about WHERE clauses, which is now demoted to a sub-section.

Closes transact-rs#2642
@abonander
abonander merged commit 218ff5f into transact-rs:main Aug 18, 2026
147 checks passed
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.

Query macro documentation understates lack of nullability checking on bind parameters

2 participants