Skip to content

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

Open
jeremie0342 wants to merge 1 commit into
transact-rs:mainfrom
jeremie0342:docs/query-macro-nullability-bind-params
Open

docs(macros): document that bind parameter nullability is not compile-checked#4345
jeremie0342 wants to merge 1 commit into
transact-rs:mainfrom
jeremie0342:docs/query-macro-nullability-bind-params

Conversation

@jeremie0342

Copy link
Copy Markdown

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

1 participant