overrides this variable.
        </para>
        </listitem>
      </varlistentry>

    </variablelist>

   </refsect3>

   <refsect3 id="app-psql-interpolation" xreflabel="SQL Interpolation">
    <title><acronym>SQL</acronym> Interpolation</title>

    <para>
    A key feature of <application>psql</application>
    variables is that you can substitute (<quote>interpolate</quote>)
    them into regular <acronym>SQL</acronym> statements, as well as the
    arguments of meta-commands.  Furthermore,
    <application>psql</application> provides facilities for
    ensuring that variable values used as SQL literals and identifiers are
    properly quoted.  The syntax for interpolating a value without
    any quoting is to prepend the variable name with a colon
    (<literal>:</literal>).  For example,
<programlisting>
testdb=&gt; <userinput>\set foo 'my_table'</userinput>
testdb=&gt; <userinput>SELECT * FROM :foo;</userinput>
</programlisting>
    would query the table <literal>my_table</literal>. Note that this
    may be unsafe: the value of the variable is copied literally, so it can
    contain unbalanced quotes, or even backslash commands. You must make sure
    that it makes sense where you put it.
    </para>

    <para>
    When a value is to be used as an SQL literal or identifier, it is
    safest to arrange for it to be quoted.  To quote the value of
    a variable as an SQL literal, write a colon followed by the variable
    name in single quotes.  To quote the value as an SQL identifier, write
    a colon followed by the variable name in double quotes.
    These constructs deal correctly with quotes and other special
    characters embedded within the variable value.
    The previous example would be more safely written this way:
<programlisting>
testdb=&gt; <userinput>\set foo 'my_table'</userinput>
testdb=&gt; <userinput>SELECT * FROM :"foo";</userinput>
</programlisting>
    </para>

    <para>
    Variable interpolation will not be performed within quoted
    <acronym>SQL</acronym> literals and identifiers.  Therefore, a
    construction such as <literal>':foo'</literal> doesn't work to produce a quoted
    literal from a variable's value (and it would be unsafe if it did work,
    since it wouldn't correctly handle quotes embedded in the value).
    </para>

    <para>
    One example use of this mechanism is to
    copy the contents of a file into a table column.
    First load the file into a variable and then interpolate the variable's
    value as a quoted string:
<programlisting>
testdb=&gt; <userinput>\set content `cat my_file.txt`</userinput>
testdb=&gt; <userinput>INSERT INTO my_table VALUES (:'content');</userinput>
</programlisting>
    (Note that this still won't work if <filename>my_file.txt</filename> contains NUL bytes.
    <application>psql</application> does not support embedded NUL bytes in variable values.)
    </para>

    <para>
    Since colons can legally appear in SQL commands, an apparent attempt
    at interpolation (that is, <literal>:name</literal>,
    <literal>:'name'</literal>, or <literal>:"name"</literal>) is not
    replaced unless the named variable is currently set. In any case, you
    can escape a colon with a backslash to protect it from substitution.
    </para>

    <para>
    The <literal>:{?<replaceable>name</replaceable>}</literal> special syntax returns TRUE
    or FALSE depending on whether the variable exists or not, and is thus
    always substituted, unless the colon is backslash-escaped.
    </para>

    <para>
    The colon syntax for variables is standard <acronym>SQL</acronym> for
    embedded query languages, such as <application>ECPG</application>.
    The colon syntaxes for array slices and type casts are
    <productname>PostgreSQL</productname> extensions, which can sometimes
    conflict with the standard usage.  The colon-quote syntax for escaping a
    variable's value as an SQL literal or identifier is a
    <application>psql</application> extension.