Debian Codegraph @

doc/src/sgml/ref/do.sgml

raw
1 <!--
2 doc/src/sgml/ref/do.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="sql-do">
7 <indexterm zone="sql-do">
8 <primary>DO</primary>
9 </indexterm>
10
11 <indexterm zone="sql-do">
12 <primary>anonymous code blocks</primary>
13 </indexterm>
14
15 <refmeta>
16 <refentrytitle>DO</refentrytitle>
17 <manvolnum>7</manvolnum>
18 <refmiscinfo>SQL - Language Statements</refmiscinfo>
19 </refmeta>
20
21 <refnamediv>
22 <refname>DO</refname>
23 <refpurpose>execute an anonymous code block</refpurpose>
24 </refnamediv>
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</type>. It is parsed and
43 executed a single time.
44 </para>
45
46 <para>
47 The optional <literal>LANGUAGE</literal> 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</command>.
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</literal>.
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 EXTENSION</command>.
85 <literal>plpgsql</literal> is installed by default, but other languages are not.
86 </para>
87
88 <para>
89 The user must have <literal>USAGE</literal> 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
95 <para>
96 If <command>DO</command> is executed in a transaction block, then the
97 procedure code cannot execute transaction control statements. Transaction
98 control statements are only allowed if <command>DO</command> is executed in
99 its own transaction.
100 </para>
101 </refsect1>
102
103 <refsect1 id="sql-do-examples">
104 <title>Examples</title>
105 <para>
106 Grant all privileges on all views in schema <literal>public</literal> to
107 role <literal>webuser</literal>:
108 <programlisting>
109 DO $$DECLARE r record;
110 BEGIN
111 FOR r IN SELECT table_schema, table_name FROM information_schema.tables
112 WHERE table_type = 'VIEW' AND table_schema = 'public'
113 LOOP
114 EXECUTE 'GRANT ALL ON ' || quote_ident(r.table_schema) || '.' || quote_ident(r.table_name) || ' TO webuser';
115 END LOOP;
116 END$$;
117 </programlisting></para>
118 </refsect1>
119
120 <refsect1>
121 <title>Compatibility</title>
122
123 <para>
124 There is no <command>DO</command> statement in the SQL standard.
125 </para>
126 </refsect1>
127
128 <refsect1>
129 <title>See Also</title>
130
131 <simplelist type="inline">
132 <member><xref linkend="sql-createlanguage"/></member>
133 </simplelist>
134 </refsect1>
135 </refentry>