granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/do.sgml

   1 <!--
   2 doc/src/sgml/ref/do.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-DO">
   7  <refmeta>
   8   <refentrytitle>DO</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>DO</refname>
  15   <refpurpose>execute an anonymous code block</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-do">
  19   <primary>DO</primary>
  20  </indexterm>
  21
  22  <indexterm zone="sql-do">
  23   <primary>anonymous code blocks</primary>
  24  </indexterm>
  25
  26  <refsynopsisdiv>
  27 <synopsis>
  28 DO [ LANGUAGE <replaceable class="PARAMETER">lang_name</replaceable> ] <replaceable class="PARAMETER">code</replaceable>
  29 </synopsis>
  30  </refsynopsisdiv>
  31
  32  <refsect1>
  33   <title>Description</title>
  34
  35   <para>
  36    <command>DO</command> executes an anonymous code block, or in other
  37    words a transient anonymous function in a procedural language.
  38   </para>
  39
  40   <para>
  41    The code block is treated as though it were the body of a function
  42    with no parameters, returning <type>void</>.  It is parsed and
  43    executed a single time.
  44   </para>
  45
  46   <para>
  47    The optional <literal>LANGUAGE</> clause can be written either
  48    before or after the code block.
  49   </para>
  50  </refsect1>
  51
  52  <refsect1>
  53   <title>Parameters</title>
  54
  55   <variablelist>
  56    <varlistentry>
  57     <term><replaceable class="PARAMETER">code</replaceable></term>
  58     <listitem>
  59      <para>
  60       The procedural language code to be executed.  This must be specified
  61       as a string literal, just as in <command>CREATE FUNCTION</>.
  62       Use of a dollar-quoted literal is recommended.
  63      </para>
  64     </listitem>
  65    </varlistentry>
  66
  67    <varlistentry>
  68     <term><replaceable class="PARAMETER">lang_name</replaceable></term>
  69     <listitem>
  70      <para>
  71       The name of the procedural language the code is written in.
  72       If omitted, the default is <literal>plpgsql</>.
  73      </para>
  74     </listitem>
  75    </varlistentry>
  76   </variablelist>
  77  </refsect1>
  78
  79  <refsect1>
  80   <title>Notes</title>
  81
  82   <para>
  83    The procedural language to be used must already have been installed
  84    into the current database by means of <command>CREATE LANGUAGE</>.
  85    <literal>plpgsql</> is installed by default, but other languages are not.
  86   </para>
  87
  88   <para>
  89    The user must have <literal>USAGE</> privilege for the procedural
  90    language, or must be a superuser if the language is untrusted.
  91    This is the same privilege requirement as for creating a function
  92    in the language.
  93   </para>
  94  </refsect1>
  95
  96  <refsect1 id="sql-do-examples">
  97   <title id="sql-do-examples-title">Examples</title>
  98   <para>
  99    Grant all privileges on all views in schema <literal>public</> to
 100    role <literal>webuser</>:
 101 <programlisting>
 102 DO $$DECLARE r record;
 103 BEGIN
 104     FOR r IN SELECT table_schema, table_name FROM information_schema.tables
 105              WHERE table_type = 'VIEW' AND table_schema = 'public'
 106     LOOP
 107         EXECUTE 'GRANT ALL ON ' || quote_ident(r.table_schema) || '.' || quote_ident(r.table_name) || ' TO webuser';
 108     END LOOP;
 109 END$$;
 110 </programlisting></para>
 111  </refsect1>
 112
 113  <refsect1>
 114   <title>Compatibility</title>
 115
 116   <para>
 117    There is no <command>DO</command> statement in the SQL standard.
 118   </para>
 119  </refsect1>
 120
 121  <refsect1>
 122   <title>See Also</title>
 123
 124   <simplelist type="inline">
 125    <member><xref linkend="sql-createlanguage"></member>
 126   </simplelist>
 127  </refsect1>
 128 </refentry>