[OffgridwithJD]

Depends on #12. This branch is stacked on #12, so until #12 merges the diff also shows its three commits. Only the last two belong here. This is a breaking change, intended for 3.0.

Problem

An interpolation in the SQL argument of query / fetch_one / execute / open_cursor / return_query / perform was lowered three different ways:

• Static SQL (a single literal, no binds): the interpolated expression was spliced in as a plpgsql variable reference. That is safe, but '#{x}' silently became the literal text 'x'.
• Dynamic SQL (execute, or any call with a bind argument): the value was concatenated unquoted. Data could inject SQL, and adding a $1 to a safe call silently switched it to this form. The core audit's repro: fetch_one("... WHERE name = '#{uname}' LIMIT $1", lim) with uname = "nobody' OR name = 'bob" returned bob.

Change

A string-literal SQL argument is now a template:

Where the interpolation sits	Static SQL	Dynamic SQL
outside quotes: id = #{n}	id = n (unchanged)	id = $k, passed with USING after the call's own binds
a whole literal: '#{s}'	(s)	($k)
inside a longer literal: '%#{s}%'	('%' || (s)::text || '%')	('%' || ($k)::text || '%') (an E'' literal stays E'')
inside a quoted identifier: "#{t}"	rejected	rejected

Utility statements: only planned statements take $n parameters (SELECT, INSERT, UPDATE, DELETE, MERGE, WITH, VALUES, TABLE, CALL, EXPLAIN; checked on 18.4). In any other dynamic statement (CREATE, ALTER, SET, COMMENT, GRANT, ...), a value is spliced through quote_nullable(), so it's still quoted.

Explicit helpers may wrap an interpolation (plxphp spells them {ident($t)}, {literal($v)}, {raw($s)}, recognized only inside a SQL argument). Each one makes the call dynamic:

• ident(e) → quote_ident(e), for table and column names
• literal(e) → quote_nullable(e), a quoted literal in any statement
• raw(e) → e unquoted, for a trusted fragment such as a sort order

So data never becomes SQL unless the author writes raw().

fetch_one("SELECT id, name FROM users WHERE name = '#{uname}' LIMIT $1", lim)
→ EXECUTE 'SELECT id, name FROM users WHERE name = ($2) LIMIT $1' INTO u USING lim, uname;

execute("COMMENT ON TABLE #{ident(t)} IS '#{c}'")
→ EXECUTE 'COMMENT ON TABLE ' || quote_ident((t)::text) || ' IS ' || quote_nullable((c)::text);

Rejected with a hint:

• an interpolation inside "..."
• ident()/literal()/raw() inside a quoted string
• a value inside a longer literal in a statement that takes no parameters

Not covered (documented): a string built elsewhere and passed in a variable is ordinary concatenation, because the call can't see the interpolation.

Implementation: one helper, plx_sql_arg, now backs every call site, including the query loops in the brace, Ruby and Python front ends, which each had their own copy of the static/dynamic switch.

Breaking

A body that interpolated an identifier (FROM #{t}) or a SQL fragment on purpose fails when re-created (syntax error at or near "$1") until it uses ident() or raw(). Stored functions are unaffected until their DDL is re-run. New page: doc/DYNAMIC-SQL.md, added to the mkdocs nav.

Two cookbook recipes interpolated a table name and are updated to use ident(). I re-ran every runnable example in the README, USERGUIDE, MIGRATION, DEBUGGING and all cookbooks against this build: no other new errors. Once this merges, #13's injection paragraphs (USERGUIDE "Trust and security") should point to the new page.

Testing

• New plx_features cases:
  • Hostile values (quotes, a trailing backslash, '); DROP TABLE ...; --, $$-quoted RAISE) round-trip exactly through every position, in a planned and in a utility statement (COMMENT), and again with standard_conforming_strings = off. The table survives.
  • The generated SQL for the audit's repro.
  • Static '#{x}'.
  • ident(), including plxphp {ident($t)}.
  • raw().
  • All three rejections.
• Template fuzzer: 1,500 random templates mixing ', '', ", E', \, $$, comments and all four interpolation kinds across the call forms. No crashes or internal errors.
• make installcheck (13/13) and make differentialcheck pass on PG 18.4. test/fuzz.py and the annotation fuzzer: no crashes.

🤖 Generated with Claude Code