English for sqlx Rust Developers

sqlx’s compile-time query verification is one of its most distinctive features, and discussing it precisely requires vocabulary — “offline mode,” “query macro,” “connection pool exhaustion” — that’s specific to how sqlx bridges Rust’s type system with raw SQL. This guide covers the English used when discussing sqlx code with a team.

Key Vocabulary

Compile-time query checking — sqlx’s ability to validate a SQL query’s syntax and result types against a live or cached database schema at compile time, catching mistakes before runtime. “This typo in the column name would have been a runtime error in most ORMs — sqlx’s compile-time checking caught it as a build failure instead.”

Query macro (query!, query_as!) — the macros that perform compile-time checking and generate strongly-typed row structs, as opposed to the runtime-only query function. “Switch this from the runtime query function to the query_as! macro — we lose nothing at runtime, and we gain compile-time verification against the actual schema.”

Offline mode — a mode where sqlx validates queries against a cached schema snapshot (sqlx-data.json or .sqlx/) instead of a live database connection, needed for CI environments without database access. “CI doesn’t have a database to connect to during the build step — make sure the offline query cache is regenerated and committed whenever the schema or queries change.”

Connection pool — a managed set of reusable database connections (via PgPool or similar), avoiding the overhead of establishing a new connection per query. “We’re creating a new pool per request handler instead of sharing one pool application-wide — that’s why we’re seeing connection exhaustion under moderate load.”

Migration — a versioned SQL file managed by sqlx-cli, applied in order to bring a database schema to a known state, and the source of truth compile-time checking validates against. “Don’t hand-edit the database schema directly in staging — write a migration, or the compile-time query cache will validate against a schema that doesn’t match what’s actually running elsewhere.”

Async runtime integration — the requirement that sqlx’s async database calls run inside a compatible async runtime (Tokio or async-std), since sqlx itself doesn’t manage threads or scheduling. “This blocking database call inside an async handler is going to stall the runtime’s worker thread — make sure every query actually goes through the pool’s async interface, not a blocking wrapper.”

Common Phrases

• “Is this using the query macro for compile-time checking, or the runtime-only function?”
• “Is the offline query cache up to date with the latest migration, or will CI fail on a stale snapshot?”
• “Are we sharing one connection pool across the application, or spinning up new pools per request?”
• “Was this schema change applied through a migration, or does it only exist in one environment?”
• “Is this call actually going through the async pool interface, or is something blocking the runtime under the hood?”

Example Sentences

Reviewing a pull request: “This query uses the untyped query function even though we know the schema — switch to query_as! so a future column rename fails the build instead of failing silently at runtime.”

Explaining a design decision: “We committed the offline query cache to the repo so CI can validate queries without needing a live database connection during the build.”

Describing an incident: “The connection exhaustion incident traced back to a handler creating a fresh pool per request instead of reusing the application-wide shared pool.”

Professional Tips

• Say “compile-time checking” precisely when explaining sqlx’s value over a traditional ORM — it’s the specific guarantee that differentiates it, not just “type safety” in general.
• Name “offline mode” explicitly when discussing CI setup — it’s the mechanism that lets builds succeed without a live database dependency.
• Flag “pool exhaustion” as a specific failure mode distinct from general “slowness” — it points reviewers directly at connection lifecycle bugs.
• Distinguish the query macro from the runtime function in review comments — recommending one over the other is a common, well-understood sqlx code review pattern.

Practice Exercise

1. Explain in two sentences why compile-time query checking catches bugs that a traditional ORM might miss.
2. Write a one-sentence code review comment recommending query_as! over the runtime query function.
3. Describe, in your own words, why offline mode is necessary for CI environments.