mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Create a function quote_nullable(), which works the same as quote_literal()

Browse Source 
except that it returns the string 'NULL', rather than a SQL null, when called
with a null argument.  This is often a much more useful behavior for
constructing dynamic queries.  Add more discussion to the documentation
about how to use these functions.

Brendan Jurd
This commit is contained in:
Tom Lane 2008-03-23 00:24:20 +00:00
parent 40a3dfb7e3
commit 7de81124d5
6 changed files with 134 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
doc/src/sgml/func.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.424 2008/03/10 12:39:22 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.425 2008/03/23 00:24:19 tgl Exp $ -->
<chapter id="functions">
<title>Functions and Operators</title>
@ -1262,6 +1262,9 @@
<indexterm>
<primary>quote_literal</primary>
</indexterm>
<indexterm>
<primary>quote_nullable</primary>
</indexterm>
<indexterm>
<primary>repeat</primary>
</indexterm>
@ -1523,6 +1526,7 @@
Quotes are added only if necessary (i.e., if the string contains
non-identifier characters or would be case-folded).
Embedded quotes are properly doubled.
See also <xref linkend="plpgsql-quote-literal-example">.
</entry>
<entry><literal>quote_ident('Foo bar')</literal></entry>
<entry><literal>"Foo bar"</literal></entry>
@ -1535,6 +1539,10 @@
Return the given string suitably quoted to be used as a string literal
in an <acronym>SQL</acronym> statement string.
Embedded single-quotes and backslashes are properly doubled.
Note that <function>quote_literal</function> returns null on null
input; if the argument might be null,
<function>quote_nullable</function> is often more suitable.
See also <xref linkend="plpgsql-quote-literal-example">.
</entry>
<entry><literal>quote_literal('O\'Reilly')</literal></entry>
<entry><literal>'O''Reilly'</literal></entry>
@ -1551,6 +1559,32 @@
<entry><literal>'42.5'</literal></entry>
</row>
<row>
<entry><literal><function>quote_nullable</function>(<parameter>string</parameter> <type>text</type>)</literal></entry>
<entry><type>text</type></entry>
<entry>
Return the given string suitably quoted to be used as a string literal
in an <acronym>SQL</acronym> statement string; or, if the argument
is null, return <literal>NULL</>.
Embedded single-quotes and backslashes are properly doubled.
See also <xref linkend="plpgsql-quote-literal-example">.
</entry>
<entry><literal>quote_nullable(NULL)</literal></entry>
<entry><literal>NULL</literal></entry>
</row>
<row>
<entry><literal><function>quote_nullable</function>(<parameter>value</parameter> <type>anyelement</type>)</literal></entry>
<entry><type>text</type></entry>
<entry>
Coerce the given value to text and then quote it as a literal;
or, if the argument is null, return <literal>NULL</>.
Embedded single-quotes and backslashes are properly doubled.
</entry>
<entry><literal>quote_nullable(42.5)</literal></entry>
<entry><literal>'42.5'</literal></entry>
</row>
<row>
<entry><literal><function>regexp_matches</function>(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</literal></entry>
<entry><type>setof text[]</type></entry>

94
doc/src/sgml/plpgsql.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.123 2008/01/23 02:04:47 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.124 2008/03/23 00:24:19 tgl Exp $ -->
<chapter id="plpgsql">
<title><application>PL/pgSQL</application> - <acronym>SQL</acronym> Procedural Language</title>
@ -1066,6 +1066,24 @@ EXECUTE <replaceable class="command">command-string</replaceable> <optional> INT
</para>
</note>
<example id="plpgsql-quote-literal-example">
<title>Quoting values in dynamic queries</title>
<indexterm>
<primary>quote_ident</primary>
<secondary>use in PL/PgSQL</secondary>
</indexterm>
<indexterm>
<primary>quote_literal</primary>
<secondary>use in PL/PgSQL</secondary>
</indexterm>
<indexterm>
<primary>quote_nullable</primary>
<secondary>use in PL/PgSQL</secondary>
</indexterm>
<para>
When working with dynamic commands you will often have to handle escaping
of single quotes. The recommended method for quoting fixed text in your
@ -1091,32 +1109,64 @@ EXECUTE 'UPDATE tbl SET '
</programlisting>
</para>
<indexterm>
<primary>quote_ident</primary>
<secondary>use in PL/PgSQL</secondary>
</indexterm>
<indexterm>
<primary>quote_literal</primary>
<secondary>use in PL/PgSQL</secondary>
</indexterm>
<para>
This example demonstrates the use of the
<function>quote_ident</function> and
<function>quote_literal</function> functions. For safety,
expressions containing column and table identifiers should be
passed to <function>quote_ident</function>. Expressions containing
values that should be literal strings in the constructed command
should be passed to <function>quote_literal</function>. Both
take the appropriate steps to return the input text enclosed in
double or single quotes respectively, with any embedded special
characters properly escaped.
<function>quote_literal</function> functions (see <xref
linkend="functions-string">). For safety, expressions containing column
or table identifiers should be passed through
<function>quote_ident</function> before insertion in a dynamic query.
Expressions containing values that should be literal strings in the
constructed command should be passed through <function>quote_literal</>.
These functions take the appropriate steps to return the input text
enclosed in double or single quotes respectively, with any embedded
special characters properly escaped.
</para>
<para>
Because <function>quote_literal</function> is labelled
<literal>STRICT</literal>, it will always return null when called with a
null argument. In the above example, if <literal>newvalue</> or
<literal>keyvalue</> were null, the entire dynamic query string would
become null, leading to an error from <command>EXECUTE</command>.
You can avoid this problem by using the <function>quote_nullable</>
function, which works the same as <function>quote_literal</> except that
when called with a null argument it returns the string <literal>NULL</>.
For example,
<programlisting>
EXECUTE 'UPDATE tbl SET '
|| quote_ident(colname)
|| ' = '
|| quote_nullable(newvalue)
|| ' WHERE key = '
|| quote_nullable(keyvalue);
</programlisting>
If you are dealing with values that might be null, you should usually
use <function>quote_nullable</> in place of <function>quote_literal</>.
</para>
<para>
As always, care must be taken to ensure that null values in a query do
not deliver unintended results. For example the <literal>WHERE</> clause
<programlisting>
'WHERE key = ' || quote_nullable(keyvalue)
</programlisting>
will never succeed if <literal>keyvalue</> is null, because the
result of using the equality operator <literal>=</> with a null operand
is always null. If you wish null to work like an ordinary key value,
you would need to rewrite the above as
<programlisting>
'WHERE key IS NOT DISTINCT FROM ' || quote_nullable(keyvalue)
</programlisting>
(At present, <literal>IS NOT DISTINCT FROM</> is handled much less
efficiently than <literal>=</>, so don't do this unless you must.
See <xref linkend="functions-comparison"> for
more information on nulls and <literal>IS DISTINCT</>.)
</para>
<para>
Note that dollar quoting is only useful for quoting fixed text.
It would be a very bad idea to try to do the above example as:
It would be a very bad idea to try to write this example as:
<programlisting>
EXECUTE 'UPDATE tbl SET '
|| quote_ident(colname)
@ -1129,8 +1179,10 @@ EXECUTE 'UPDATE tbl SET '
happened to contain <literal>$$</>. The same objection would
apply to any other dollar-quoting delimiter you might pick.
So, to safely quote text that is not known in advance, you
<emphasis>must</> use <function>quote_literal</function>.
<emphasis>must</> use <function>quote_literal</>,
<function>quote_nullable</>, or <function>quote_ident</>, as appropriate.
</para>
</example>
<para>
A much larger example of a dynamic command and

18
src/backend/utils/adt/quote.c
View File

@ -7,7 +7,7 @@
*
*
* IDENTIFICATION
* $PostgreSQL: pgsql/src/backend/utils/adt/quote.c,v 1.23 2008/01/01 19:45:52 momjian Exp $
* $PostgreSQL: pgsql/src/backend/utils/adt/quote.c,v 1.24 2008/03/23 00:24:19 tgl Exp $
*
*-------------------------------------------------------------------------
*/
@ -96,3 +96,19 @@ quote_literal(PG_FUNCTION_ARGS)
PG_RETURN_TEXT_P(result);
}
/*
* quote_nullable -
* Returns a properly quoted literal, with null values returned
* as the text string 'NULL'.
*/
Datum
quote_nullable(PG_FUNCTION_ARGS)
{
if (PG_ARGISNULL(0))
PG_RETURN_DATUM(DirectFunctionCall1(textin,
CStringGetDatum("NULL")));
else
PG_RETURN_DATUM(DirectFunctionCall1(quote_literal,
PG_GETARG_DATUM(0)));
}

4
src/include/catalog/catversion.h
View File

@ -37,7 +37,7 @@
* Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* $PostgreSQL: pgsql/src/include/catalog/catversion.h,v 1.443 2008/03/22 01:55:14 ishii Exp $
* $PostgreSQL: pgsql/src/include/catalog/catversion.h,v 1.444 2008/03/23 00:24:19 tgl Exp $
*
*-------------------------------------------------------------------------
*/
@ -53,6 +53,6 @@
*/
/* yyyymmddN */
#define CATALOG_VERSION_NO 200803221
#define CATALOG_VERSION_NO 200803222
#endif

6
src/include/catalog/pg_proc.h
View File

@ -7,7 +7,7 @@
* Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* $PostgreSQL: pgsql/src/include/catalog/pg_proc.h,v 1.483 2008/03/22 01:55:14 ishii Exp $
* $PostgreSQL: pgsql/src/include/catalog/pg_proc.h,v 1.484 2008/03/23 00:24:19 tgl Exp $
*
* NOTES
* The script catalog/genbki.sh reads this file and generates .bki
@ -2635,6 +2635,10 @@ DATA(insert OID = 1283 ( quote_literal PGNSP PGUID 12 1 0 f f t f i 1 25 "25
DESCR("quote a literal for usage in a querystring");
DATA(insert OID = 1285 ( quote_literal PGNSP PGUID 14 1 0 f f t f v 1 25 "2283" _null_ _null_ _null_ "select pg_catalog.quote_literal($1::pg_catalog.text)" - _null_ _null_ ));
DESCR("quote a data value for usage in a querystring");
DATA(insert OID = 1289 ( quote_nullable PGNSP PGUID 12 1 0 f f f f i 1 25 "25" _null_ _null_ _null_ quote_nullable - _null_ _null_ ));
DESCR("quote a possibly-null literal for usage in a querystring");
DATA(insert OID = 1290 ( quote_nullable PGNSP PGUID 14 1 0 f f f f v 1 25 "2283" _null_ _null_ _null_ "select pg_catalog.quote_nullable($1::pg_catalog.text)" - _null_ _null_ ));
DESCR("quote a possibly-null data value for usage in a querystring");
DATA(insert OID = 1798 ( oidin PGNSP PGUID 12 1 0 f f t f i 1 26 "2275" _null_ _null_ _null_ oidin - _null_ _null_ ));
DESCR("I/O");

3
src/include/utils/builtins.h
View File

@ -7,7 +7,7 @@
* Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
* $PostgreSQL: pgsql/src/include/utils/builtins.h,v 1.308 2008/01/01 19:45:59 momjian Exp $
* $PostgreSQL: pgsql/src/include/utils/builtins.h,v 1.309 2008/03/23 00:24:20 tgl Exp $
*
*-------------------------------------------------------------------------
*/
@ -914,6 +914,7 @@ extern int32 type_maximum_size(Oid type_oid, int32 typemod);
/* quote.c */
extern Datum quote_ident(PG_FUNCTION_ARGS);
extern Datum quote_literal(PG_FUNCTION_ARGS);
extern Datum quote_nullable(PG_FUNCTION_ARGS);
/* guc.c */
extern Datum show_config_by_name(PG_FUNCTION_ARGS);