Module variables 

psql-style variable resolution for SQL files.

Resolves :foo, :'foo', and :"foo" syntax in raw SQL text before it reaches the SQL parser. Variables are defined per-profile in [<profile>.variables] in project.toml.

Variable Syntax

Syntax	Semantics	Example output
:name	Raw substitution — value inserted verbatim	analytics
:'name'	SQL literal — value wrapped in single quotes, ' doubled	'it''s-a-host'
:"name"	SQL identifier — value wrapped in double quotes, " doubled	"my""col"

Resolution Rules

1. Variables are looked up in the BTreeMap<String, String> passed to resolve_variables. This map is populated from project.toml’s [<profile>.variables] section.
2. If a referenced variable has no definition, it is left as-is in the output and an UnresolvedVariable (with byte offset and length) is recorded in ResolvedSql::unresolved. Each occurrence is tracked separately (not deduplicated) so the LSP can highlight every reference.
3. Every resolved substitution is recorded as a Substitution in ResolvedSql::substitutions, enabling resolved_to_original to map byte offsets in the resolved text back to the original source positions.
4. The caller decides whether unresolved variables are errors or warnings based on the PRAGMA WARN_ON_MISSING_VARIABLES; directive.

Context Awareness

Variable references are not resolved inside:

• Single-quoted string literals ('...')
• Double-quoted identifiers ("...")
• Line comments (-- ...)
• Block comments (/* ... */), including nested blocks
• Dollar-quoted strings ($$...$$ or $tag$...$tag$)

The :: token (PostgreSQL type cast) is never interpreted as a variable reference.

Structs

ResolvedSql 🔒

Result of resolving psql-style variables in SQL text.

Substitution 🔒

A resolved variable substitution, for mapping offsets between original and resolved text.

UnresolvedVariable

An unresolved variable reference with its location in the original SQL.

VariableError

Error returned when SQL contains variable references that have no definition.

Enums

VarKind 🔒

The kind of variable reference found in the SQL text.

Constants

PRAGMA 🔒

Functions

consume_block_comment 🔒

Consume a block comment (with nesting). i is the position after /*. Returns the position after the final */.

consume_dollar_quoted 🔒

Consume a dollar-quoted string. i is the position after the opening tag. Scans for the matching closing tag.

consume_double_quoted 🔒

Consume a double-quoted identifier. i is the position after the opening ". Returns the position after the closing ".

consume_line_comment 🔒

Consume a line comment. i is the position after --. Returns the position after \n (or end of input).

consume_single_quoted 🔒

Consume a single-quoted string. i is the position after the opening '. Returns the position after the closing '.

detect_warn_pragma 🔒

Check whether the first non-whitespace content in sql is a comment containing the warn-on-missing-variables pragma.

find_variable_at_position 🔒

Find the variable reference (if any) that contains the given byte offset.

push_sql_escaped 🔒

Push value into out, doubling any occurrence of quote.

resolve_variables 🔒

Resolve psql-style variables (:foo, :'foo', :"foo") in SQL text.

resolved_to_original 🔒

Map a byte offset in resolved text back to the corresponding offset in original text.

starts_with 🔒

Check if bytes[i..] starts with needle.

try_dollar_tag 🔒

Check if $ at position i starts a dollar-quote tag. Returns (end_pos, tag_bytes) where end_pos is the position after the closing $ of the tag.

try_read_variable 🔒

Try to read a variable reference starting at position i (which must be :).