From ff54362285397bf5e4084d986e331b3883864e5c Mon Sep 17 00:00:00 2001 From: Ishjaap Singh Date: Thu, 19 Nov 2026 16:54:33 +0000 Subject: [PATCH v1 3/4] doc: Explain how ECPG inserts host variables into EXECUTE name(...) When a prepared statement is executed as EXECUTE name(:var, ...), ecpglib inserts the host variable values into the text of the EXECUTE command without quoting and sends the result to the server as plain SQL. This was not documented anywhere. As a result, a character host variable has to contain a complete, correctly escaped SQL literal, and boolean and date/time host variables don't work in that list at all. Applications using this form have to quote character values themselves, so say so in the dynamic SQL section, point to PQescapeLiteral() for building the literal, and point to EXECUTE ... USING for passing values as separate parameters. Add a short pointer from the ECPG PREPARE page. Backpatch-through: 15 --- doc/src/sgml/ecpg.sgml | 66 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index 4651382b635..0558a447e30 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -1998,6 +1998,65 @@ EXEC SQL EXECUTE mystmt USING 42, 'foobar'; + + A prepared statement can also be executed by writing its parameter + values in parentheses after the statement name, as in the SQL + command : + +EXEC SQL PREPARE mystmt2(int, text) AS INSERT INTO test1 VALUES($1, $2); + ... +EXEC SQL EXECUTE mystmt2(:id, :name); + + In this form, host variables in the parenthesized list are not sent + to the server as separate parameter values. Instead, the value of + each host variable is inserted, without quoting, into the text of + the EXECUTE command, and the server parses the + resulting command as SQL. This is the case regardless of how the + statement was prepared. As a consequence: + + + + + + Integer, floating-point and numeric host variables work + as expected for ordinary finite values. NaN and + infinite values of floating-point and numeric host + variables do not work. + + + + + + A character host variable must contain a complete SQL literal for + the parameter, including the enclosing single quotes and escaped as + required by the connection's client encoding and settings. For + example, to pass the string O'Brien, the variable + must contain 'O''Brien'. A value that is not + written this way is parsed as part of the SQL command, so a value + taken from untrusted input can change the command that is executed. + The libpq function + , called with the connection + handle returned by ECPGget_PGconn() + (see ), produces such a literal. + + + + + + Boolean, date, timestamp and interval host variables do not work in + this list, because their values are not inserted as valid literals + of their types. + + + + + + To pass host variable values to a prepared statement as separate + parameter values, without these restrictions, use + USING as shown above. This works regardless of how + the statement was prepared. + + When you don't need the prepared statement anymore, you should deallocate it: @@ -7660,6 +7719,13 @@ PREPARE prepared_name FROM + + + A prepared statement can be executed with USING, + or with its parameter values in parentheses after the statement name. + In the second form, host variable values are inserted into the + command text without quoting; see . + -- 2.43.0